The Add New Item dialog isn't set in stone. You can extend it by adding your own item or project template.
When you create a new file in your Visual Studio Projects, you generally use the Add New Item dialog (see Figure 12-1). If you look at the categories listed on the left half of that window, you can see that the dialog box is organized according to the types of files you might need to create in a given project type.
|
Visual Studio provides many different types of template files for the many different types of projects. Rather than just displaying them all in a long list, the Visual Studio team provided some of the gentle guidance you would expect. If you're working on a Web Project, it initially displays all the templates for the types of files that might be used in Web Projects. The most common type of file that developers create in an ASP.NET Web Project is a Web Form. Accordingly, the Web Form template is first one in the list.
Once you choose a given template, you're provided the chance to name the file that will be created from it. A fairly generic name is suggested, like WebForm1.aspx for those created from the Web Form template. You'll almost always change this name.
The final steps are for Visual Studio to add the new file instance, with your chosen filename, to your project and display it in the editor pane of the IDE. Depending on the template you chose, you'll see the appropriate initial content in the editor.
It's what appears in that initial content that is up for grabs in this hack. If this is a source code file, you'll see plain text. The plain text is the starter code or markup for the given file that you or another developer will expand upon. This hack shows you how to create your own template and have it produce the initial plain text you need.
Visual Studio provides a number of built-in templates for nearly all of the file types that are involved in the different types of .NET applications. One hack opportunity is to take one of the existing templates and just modify it to your needs. The other opportunity is to create one from scratch, which is what I will be covering in this hack.
Actually, in this hack, I'd like to make up for a hole in Visual Studio. In addition to the Visual Studio IDE, Microsoft also offers a free tool for web development called Microsoft ASP.NET Web Matrix, or Web Matrix for short. The Web Matrix is a small tool that is not as fully featured as Visual Studio. Visual Studio is able to create many more file types than the Web Matrix. So you'd think that Visual Studio's set of templates would definitely be the superset of file types. Not quite. There's an HTTP Handler file type that appears in the Web Matrix Add New File dialog (see Figure 12-2). Strangely enough, this is missing from Visual Studio. So let's make up for this disparity.
Similar to the .aspx extension for the Web Form templates, ASP.NET HTTP Handlers use an .ashx extension. We won't go into all the differences between a Web Form and an HTTP Handler in this hack. The salient difference to note is that the initial text that the HTTP Handler template uses will be different from the Web Form template. Whereas the .aspx file contains markup text with angle brackets, the HTTP Handler template is actually all code; in this case, it's C# or Visual Basic .NET.
Navigate to the C:\Program Files\Microsoft Visual Studio .NET 2003 folder. Depending on what language (for example, C# or VB), look for either the VC# or VB7 folder. Inside the given language folder, look for CSharpProjectItems or VBProjectItems, respectively. Compare the filenames in the folders to the templates in the Add New Item dialog. This is where Visual Studio stores templates. It uses a combination of .vsz files and .vsdir files. So to get our template display, we've got to create the appropriate .vsz and .vsdir files. The entry in the .vsdir file will point to our .vsz file.
Visual Studio .NET uses .vsz files to launch wizards. These are simple text files that look like the .ini files of old, but with only one section.
To create a new VSZ file, you can copy one of the existing files or start from scratch by creating a new text file in your favorite text editor and saving it with the .vsz file extension. Inside of the file, you first need to specify what version of Visual Studio this template is for, which is done by specifying:
VSWIZARD 7.0
This tells Visual Studio that your template will function with Visual Studio .NET 2002 (7.0) or 2003 (7.1).
|
The next line specifies the class that should be used for the wizard. In this example, I use VsWizard.VsWizardEngine.7.1 (the default wizard engine).
|
Next, you will need to specify any number of parameters to send to the wizard engine. This example specifies the name of the wizard, the type of project, and whether the wizard includes a UI. The complete .vsz file can be seen here for a C# first and then a VB.NET version of the HttpHandler:
VSWIZARD 7.0 Wizard=VsWizard.VsWizardEngine.7.1 Param="WIZARD_NAME = CSharpHTTPHandler" Param="WIZARD_UI = FALSE" Param="PROJECT_TYPE = CSPROJ" VSWIZARD 7.0 Wizard=VsWizard.VsWizardEngine.7.1 Param="WIZARD_NAME = VBNETHTTPHandler" Param="WIZARD_UI = FALSE" Param="PROJECT_TYPE = VBPROJ
The WIZARD_NAME parameter specifies the name of the wizard, in these examples, either CSharpHTTPHandler or VBNETHTTPHandler. The WIZARD_UI parameter specifies whether this is a simple template or a complete wizard; in this example, we are just creating a template, so we will pass false. The last parameter specifies the type of project this item will be added to, CSPROJ and VBPROJ, respectively.
VSDir files are simple text files that tell the Add New Item and New Project dialogs what to display, including details like the name and icon.
Just like the .vsz files, the .vsdir files are plain text files. The format is different though. There are multiple entries inside, one per line, with the pipe symbol (|) separating the different parts of the given entry.
While you can update one of the existing .vsdir files, it is better to create a new .vsdir file. If you modify one of the existing files, your changes will be overwritten if the user reinstalls or repairs his installation of Visual Studio.
First, create a new blank text file in your favorite text editor, save it with an extension of .vsdir, and save it in the Web Project Items subfolder. Next, you need to add a line that represents the new template. Here is the code you need to add for C# and VB.NET. (You should put all the code on a single line, rather than wrapping it as it's shown here):
..\CSharpHTTPHandler.vsz| |HTTP Handler
|15|VSNet Hacks HTTPHandler
|{FAE04EC1-301F-11d3-BF4B-00C04F79EFBC}|4534
|0|HTTPHandler.ashx
..\VBNETHTTPHandler.vsz| |HTTP Handler
|15| VSNet Hacks HTTPHandler
|{164B10B9-B200-11D0-8C61-00A0C91E29D5}|4533
|0|HTTPHandler.ashx
Although it is broken up here, all code should appear on one line in the text file. These entries have up to nine parts. Let's look at the VB.NET code as an example.
The first part (..\VBNETHTTPHandler.vsz) is the relative path to the .vsz file for the template. The second part (the space between the | and |) is optional and left blank in this example.
The third part (HTTP Handler) contains the words that go under the icon for the template in the Add New Item dialog, so keep it short.
The fourth part (15) is important; it's known as the SortPriority. It determines the order in which the templates appear in the dialog. The ones included with Visual Studio start with 10 and continue in increments of 10. For example, the next template that normally appears is the WebService template. It has a SortPriority of 20. I use 15 so that this one shows up between these two.
The fifth part (VSNet Hacks HTTPHandler) is the description that appears in the box of the same dialog when you click on the icon. You'll have a little more room for this, but not much; it has to fit on a single line.
The sixth and seventh ({164B10B9-B200-11D0-8C61-00A0C91E29D5} and 4533) parts have to do with the icon that'll be used in the dialog to represent this custom template. The sixth part is the DLL path or CLSID of a DLL that has an icon resource in it. You can just leave this the same as the one used for the default WebForm. Similar to the resource strings mentioned above, the seventh part is the resource number in that DLL that points to the particular icon in the DLL. Stick with the one from the WebForm for now. The eighth part (0) is a bit mask for some flags; again, you should also stick with the values for the WebForm template.
The ninth part (HTTPHandler.ashx) is the last one. It's the suggested filename I talked about earlier. Set it to HTTPHandler.ashx. Visual Studio will use this as a suggested base name and adjust it to HTTPHandler<N>.ashx, where N will get replaced with an increasing integer in that pattern with which you're familiar (HTTPHandler1.ashx, HTTPHandler2.ashx, etc.).
Now that you've got the Add New Item dialog supplied with the necessary .vsz and .vsdir files, you must put the template where Visual Studio expects it to be. Look back in the VC# and VB folders for the VC#Wizards and VBWizards subfolders. Inside these folders, you'll find the various wizards and templates.
Inside the wizards folders are further subfolders that contain each individual wizard. The names of these folders match the WIZARD_NAME parameter from the .vsz files. So you'll want to add a CSharpHTTPHandler and HTTPHandler folder to the VC#Wizards and VBWizards folders.
Inside these folders, you must follow some conventions for templates and scripts that Visual Studio will require to be able to find your files. You'll need a Templates folder and a Scripts folder. Inside each of those folders needs to be a 1033 folder. 1033 isn't really a magic number. It's a LocaleID that represents standard English. Since we're just dealing with an English installation of Visual Studio here, this is what the folder needs to be named. If you were to use an installation of a different spoken language, you should expect a different number.
You now have nearly everything set up that you need to have this hack work. You've got Visual Studio acknowledging that your template exists. If you bring up the Add New Item dialog box, you'll see an entry for the HTTP Handler (see Figure 12-3). If you click the Open button, it will now try to find the HTTPHandler.ashx file in the Templates/1033 folder of VC#Wizards or VBWizards folder.
Next, you need to create the actual template. Since you're going to use the HTTP Handler from Web Matrix, you can fire it up and copy the template or just use the following code:
<%@ WebHandler language="VB" class="[!output SAFE_ITEM_NAME]" %> Public Class [!output SAFE_ITEM_NAME] : Implements IHttpHandler Public Sub ProcessRequest(context As HttpContext) Implements IHttpHandler.ProcessRequest ' TODO: Write request handling code here End Sub Public ReadOnly Property IsReusable As Boolean Implements IHttpHandler.IsReusable Get Return True End Get End Property End Class
<%@ WebHandler language="C#"
class="[!output SAFE_NAMESPACE_NAME].[!output SAFE_CLASS_NAME]" %>
using System;
using System.Web;
namespace [!output SAFE_NAMESPACE_NAME] {
public class [!output SAFE_CLASS_NAME] : IHttpHandler {
public void ProcessRequest(HttpContext context) {
// TODO: Write request handling code here
}
public bool IsReusable {
get {
return true;
}
}
}
}
You will need to replace the names of the classes and namespaces with [!output SAFE_NAMESPACE_NAME] or [!output SAFE_CLASS_NAME] in C# or [!output SAFE_ITEM_NAME] for the class name in VB.NET. These will be replaced with namespace and class names by the wizard engine.
Change the name of the file to be HTTPHandler.ashx so that it matches the suggested base name you gave in the .vsdir file entry. Save the file into the Templates/1033 folder.
If you are creating a C# wizard, you next need to create an .inf file that lists the files to add to your project. Create a new text file in a text editor and add the following line to that file:
HTTPHandler.ashx
Next, save the file with the name templates.inf.
This is the final step. When Visual Studio gets to the point of adding the template file to the project, it invokes a JavaScript file. This enables anyone who wants to extend Visual Studio to be able to perform any custom steps that might be necessary. The preferred choice for providing this type of extension is scripting.
You don't need anything complicated to add the HTTPHandler.ashx file to the project. Create a new text file and add the following code to that text file:
function OnFinish(selProj, selObj)
{
try
{
var strProjectName = wizard.FindSymbol("PROJECT_NAME");
SetTargetFullPath(selObj);
var strProjectPath = wizard.FindSymbol("TARGET_FULLPATH");
var InfFile = CreateInfFile( );
AddFilesToCSharpProject(selObj, strProjectName,
strProjectPath, InfFile, true);
}
catch(e)
{
if( e.description.length > 0 )
SetErrorInfo(e);
return e.number;
}
finally
{
if( InfFile )
InfFile.Delete( );
}
}
function SetFileProperties(oFileItem, strFileName)
{
}
function OnFinish(selProj, selObj)
{
try
{
var strItemName = wizard.FindSymbol("ITEM_NAME");
var strTemplatePath = wizard.FindSymbol("TEMPLATES_PATH");
var strTemplateFile = strTemplatePath + "\\HTTPHandler.ashx";
var item = AddFileToVSProject(strItemName, selProj,
selObj, strTemplateFile, true);
return 0;
}
catch(e)
{
if( e.description.length > 0 )
SetErrorInfo(e);
return e.number;
}
}
Save the file as default.js in the Scripts/1033 folder of your wizard.
That's it. Create a Visual Studio .NET 2003 Project. Bring up the Add New Item dialog. The HTTP Handler item should appear as the second one in the dialog box. Adjust the HTTPHandler1.aspx name if needed and click the Open button. A new HTTPHandler.ashx file will appear in your project .
Steven Dewalt