How to build your own ASP.NET templates for VS.NET

• Download source - 8 Kb

Introduction

Over the last 2 years and 5 small and midsize business related web projects I got tired of copying, pasting and deleting code between projects and pages, I've figured out that either web developers are extremely diligent or I'm missing a big thing here, as a lazy being I've decided that I'm missing something and went looking for it, it wasn't there.

Background

You should probably read these articles first :

• Ben Hinton's most enlightening article at www.dotnetjunkies.com.
• If you are familiar with winforms these articles are very handy too (basically the same principal) : Customizing Visual Studio's Code Generation Templates and Adding Customized Visual Studio Code Generation Templates to the Add new item Dialog Box
• You might want to surf around http://www.vsipdev.com/techinfo and VS.NET product documentation on MSDN

The missing link

Having read all articles suggested above you may have noticed that a crucial part is missing for web developers : manipulating templates of the code behind. If you haven't read the articles above I strongly recommend it, at least the first one as it supply a good tutorial for web pages templates but here is a short brief : (skip to the interesting part)

When adding a new item to a web project VS.NET goes to a certain file that holds registration of file types that can be added to your project, this file is located in

C:\Program Files\Microsoft Visual Studio .NET
           2003\VC#\CSharpProjectItems\WebProjectItems

on a default installation and is called WebProjectItems.vsdir, it looks like this :

We need to copy and mess a little bit with this file so here goes :

• step 1 : create a folder in WebProjectItems directory called MyCustomTemplates
• step 2 : copy WebProjectItems.vsdir to the newly created directory and rename it MyCustomTemplates.vsdir
• step 3 : open the file using VS.NET, notepad or any other text editor
• step 4 : leave only the row that has WebForm.aspx at the end of it (usually the first long one) and delete all the other rows in this file

As for vsdir files here is a small legend :(taken from vsdir files in the MSDN)

Field	Meaning
RelPathName	Required. The name of the Wizard's .vsz file, such as MyWizard.vsz.
{clsidPackage}	Optional. A GUID representing a product (such as Visual C++) that has a DLL containing localized resources. Normally, this field is blank for VSDir files that correspond with third-party Wizards.
LocalizedName	Optional. This is the localizable name of the Wizard or template and the name that appears in the Add Item dialog box. This can be a string or a resource identifier of the form #ResID.
SortPriority	Required. An integer representing the sort order and relative priority of the Wizard, with 1 being highest. For instance, if this item is "1," then this will appear next to other 1s and ahead of all 2s or lower.
Description	Required. A localizable description of the template or Wizard as it will appear in the Add Item dialog box when the item is selected. This can be a string or a resource identifier of the form #ResID. Applies only to template files, not folders.
DLLPath or {clsidPackage}	Required. Specifies a full path to a DLL or EXE file, or a GUID of a product that has a .dll file that contains an icon to load for the Wizard. The icon is loaded as a resource out of a DLL/EXE file using the given IconResourceId. This setting overrides {clsidPackage}, if specified, for icon location. Applies only to template files, not folders.
IconResourceId	Optional. A resource identifier within the DLL file that determines the icon to display. If no icon is defined, the environment substitutes the default icon for a file with the same extension as the item. Applies only to template files, not folders.
Flags	Required. See Flags description and table below. Applies only to template files, not folders.
SuggestedBaseName	Required. The default name for the Wizard, displayed in the Name field in the dialog box. This is either a string or a resource identifier of the form #ResID. If the name is not unique, the environment appends the name with an integer. For example, MyFile.asp might be changed to MyFile1.asp. If no name is provided, then "Project" is used. Applies only to template files, not folders.

Now that we understand all this mambo jambo in the vsdir file we can carry on :

..\CSharpAddWebFormWiz.vsz|{FAE04EC1-301F-11d3-BF4B-00C04F79EFBC}|#2236|
10|#2263|{FAE04EC1-301F-11d3-BF4B-00C04F79EFBC}|4534|0|webForm.aspx

• step 5 : rename the ..\CSharpAddWebFormWiz.vsz at the begining of your file to : ..\..\MyCustomTemplatesAddWebFormWiz.vsz
• step 6 : change #2236 to my page this supplys a description to the icon in the "add new item" right window
• step 7 : change WebForm.aspx to myPage.aspx this supplys the name for the new file

That's it for our .vsdir file. This is how the file should look like now :

..\..\MyCustomTemplatesAddWebFormWiz.vsz|
    {FAE04EC1-301F-11d3-BF4B-00C04F79EFBC}|my page|
10|#2263|{FAE04EC1-301F-11d3-BF4B-00C04F79EFBC}|4534|0|myPage.aspx

We now move on to the .vsz file :

• Go to

  C:\Program Files\Microsoft Visual Studio .NET 
                  2003\VC#\CSharpProjectItems

• Copy CSharpAddWebFormWiz.vsz and rename it to MyCustomTemplatesAddWebFormWiz.vsz

Now if we look at it in notepad it looks like this :

Change the "WIZARD_NAME=CSharpAddWebFormWiz" param to "WIZARD_NAME=MyCustomTemplatesAddWebFormWiz". That's it.

Let's move on :

• 1. Go to C:\Program Files\Microsoft Visual Studio .NET 2003\VC#\VC#Wizards
• 2. Scroll down and find CSharpAddWebFormWiz directory
• 3. Copy it and rename the copy to MyCustomTemplatesAddWebFormWiz
• 4. Inside you'll notice two directories : scripts and templates
• 5. If you want to change the WebForm.aspx code this is the time.
• 6. Save all changes, close all instances of VS.NET and open a web project (existing or a new one) choose the "add new item" on the project right click menu, on the left window you should see Mycustomtemplates directory under add Project Item and on the right window you should see your custom page "my Page".
• 7. On the file name you should see myPagen.aspx (where n is a number added by VS.NET) .

If something didn't work, follow the instructions and correct any mistakes.

The interesting part

If you have read the articles above and apply the methodology suggested you have noticed that there is no reference to the code behind WebForm.aspx.cs, it is not under the templates directory and apparently it is created by the wizard package using a template taken from somewhere else, this is actually what happens, the template for the code behind file resides on the

C:\Program 
            Files\Microsoft Visual Studio .NET 
            2003\VC#\DesignerTemplates\1033\NewWebFormCode.cs

file. You can check it by changing this file and add a web page by the regular template or your newly created template. This suggests that you can't modify this file because the code you will put there will apply to all your templates and you probably do not want that. So I looked around for a solution and found it in the CSharpAddMobileWebFormWiz under

C:\Program Files\Microsoft 
            Visual Studio .NET 2003\VC#\VC#Wizards\

. For some reason they (MS) wrote another wizard for mobile forms and included the MobileWebForm1.aspx.cs under the templates directory.

So all we need to do now is this :

1. Add the MobileWebForm1.aspx.cs to our MyCustomTemplates\templates\1033 directory, rename it to WebForm1.aspx.cs .
2. Rename the default.js in the MyCustomTemplates\scripts\1033 directory to old default.js
3. Copy default.js script from CSharpAddMobileWebFormWiz\scripts\1033 to MyCustomTemplates\scripts\1033 and open it in VS.NET or notepad.
4. Go to line 278 and change "MobileWebForm1.aspx.cs" to "WebForm1.aspx.cs"
5. Go to line 278 and change "MobileWebForm1.aspx" to "WebForm1.aspx" you will now need the old default.js,
6. Open it in a text editor and go to line 2 copy all 3 first functions shown here :

function AddDefaultServerScriptToWizard(selProj)
{
    wizard.AddSymbol("DEFAULT_SERVER_SCRIPT", "JavaScript");
}

function AddDefaultClientScriptToWizard(selProj)
{
    var prjScriptLang = selProj.Properties("DefaultClientScript").Value;
    // 0 = JScript
    // 1 = VBScript
    if(prjScriptLang == 0)
    {
        wizard.AddSymbol("DEFAULT_CLIENT_SCRIPT", "JavaScript");
    }
    else
    {
        wizard.AddSymbol("DEFAULT_CLIENT_SCRIPT", "VBScript");
    }
}

function AddDefaultDefaultHTMLPageLayoutToWizard(selProj)
{
    var prjPageLayout = selProj.Properties("DefaultHTMLPageLayout").Value;
    // 0 = FlowLayout
    // 1 = GridLayout
    if(prjPageLayout == 0)
    {
        wizard.AddSymbol("DEFAULT_HTML_LAYOUT", "FlowLayout");
    }
    else
    {
        wizard.AddSymbol("DEFAULT_HTML_LAYOUT", "GridLayout");
    }
}

7. Copy them to your new default.js
8. go to line 59 (function AddFileToVSProject) and add calls to these functions:

AddDefaultServerScriptToWizard(selProj);
AddDefaultTargetSchemaToWizard(selProj);
AddDefaultClientScriptToWizard(selProj);
AddDefaultDefaultHTMLPageLayoutToWizard(selProj);            

Notice that there is an extra call here to AddDefaultTargetSchemaToWizard(selProj) this function adds the target schema to tha page and is not existed in the original default.js file (dont know where it comes from...) but it works so I don't really care right now.

9. open the WebForm1.aspx.cs and remove the references

   System.Web.Mobile

   and System.Web.UI.MobileControls
10. change the inheritance of the web page to from this :

public class myPage1 : System.Web.UI.MobileControls.MobilePage 

to this :

public class myPage1 : System.Web.UI.Page

11. add some of your code to the code behind.

private void initializePageParams()
{
    //....
}

private void BindGrid()
{
    //
}

//whatever you want...

That's about it, save all your work and close all instances of VS.NET open a web project and add an item using your template .

Known issues

When adding a page using your new template VS.NET will show you this alert :

You should choose no.