Visual Studio Hacks [Electronic resources] نسخه متنی

Hack 47. Build a Custom Tool

You can write code, or you can write tools that
write code. How much is your time worth?

Custom tools can be used to generate code
based on an input file. The most familiar custom tool is probably
xsd.exe

, which will create a strongly typed
DataSet based on an XML file [Hack #49] . In this hack, I am going to
cover how to create your own custom tool that takes an XML file and
then generates a piece of code based on that
XML. The example I cover here will
be somewhat simplistic, but it will demonstrate the basic principles
of building a custom tool and will provide you with the information
you need to create your own custom tool.

6.5.1. Write the Code

To create a custom tool, you first need to
create a new project in the language of your choice and then create a
new class in that project. The next thing you need to do is set your
class to inherit from a class called
BaseCodeGeneratorWithSite.

In Visual Studio .NET 2002, this class was available in the
Microsoft.VSDesigner.dll

assembly. However, starting with Visual Studio .NET 2003, this class
was made private and you could no longer inherit from it. Thankfully,
someone at Microsoft has made this class available for download from
GotDotNet, so before you can inherit
from this class, you must first download it from http://www.gotdotnet.com/Community/UserSamples/Details.aspx?SampleGuid=4AA14341-24D5-45AB-AB18-B72351D0371C.

The zip file downloaded from this link contains all the code for the
class, but all you really need is the
BaseCodeGeneratorWithSite.dll.
Reference this .dll from your project, add the
using or Imports statement for
the
CustomToolGenerator namespace, and then you can inherit
from the BaseCodeGeneratorWithSite class in your
code.

After inheriting from BaseCodeGeneratorWithSite,
you will need to implement the abstract method
GenerateCode. This is the method where your generator
will receive the XML file and where you will need to return the
generated code for Visual Studio to include in the project.

Here is what your code should look like so far (this example is in
C#, but a Visual Basic example is available in the sample code
downloadgo to
http://www.oreilly.com/catalog/visualstudiohks to obtain
the sample code for this book):

using System;
using CustomToolGenerator;
namespace CustomToolProject
{
public class CustomGenerator : BaseCodeGeneratorWithSite
{
protected override byte[  ] GenerateCode(
string file, string contents)
{
return null;
}
}
}

Next you will need to implement your GenerateCode
method. For this example, I am going to simply return some arbitrary
code shown here:

protected override byte[  ] GenerateCode(string file, 
string contents)
{
string code = @"using System;
namespace Vehicles
{ 
public class Car { } 
}
";
return System.Text.Encoding.ASCII.GetBytes(code);
}

For Visual
Studio to use your generator, you have to register your custom tool
as a COM class, which means you need to decorate
it with the Guid attribute and include a unique
GUID. To get a new
GUID, you can use the Tools Create GUID tool. This
generates a new GUID using the registry format and then place it in
the Guid attribute on your class. Here is what
your code should now look like:

using System;
using System.Runtime.InteropServices;
using CustomToolGenerator;
namespace CustomToolProject
{
[Guid("8696CA73-4FD7-4e5f-B267-48C9F3CB8F07")]
public class CustomGenerator : BaseCodeGeneratorWithSite
{
protected override byte[  ] GenerateCode(string file, 
string contents)
{
//Code from the preceding example goes here
}
}
}

6.5.2. Add the Tool to Visual Studio

After you have written the code to generate
the code for your custom tool, the next step is to register your
custom tool with Visual Studio. The first thing to do is register
your class as a COM component using the
regasm tool. Here are the steps to register your
class:

Run the Visual Studio Command Prompt (Start Visual Studio
2003 Visual Studio .NET Tools Visual Studio
.NET 2003 Command Prompt).

Navigate to the directory where your .dll file
is located (most likely Your Project/bin/debug).

Type the following command: regasm /codebase
your_assembly.dll.

Next, you will get a warning if your tool is not signed with a strong
name. You can ignore this for now (although signing your tool before
distributing it is recommended).

Now that your tool is registered, you need to tell Visual Studio
where and what the tool is. This is done through the
registry. You will need to add a new
key under the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\<7.1>\Generators

Under this key, you will find a list of

GUIDs. Each of these GUIDs represents a
language, and the first step is to find the language that you would
like to add your custom tool to. Table 6-2 shows a
list of the GUIDs and the languages they correspond to.

After choosing what language type to add
your custom tool to, the next step is to create a new key under that
value. This key should be named the same as your custom tool and will
need to include three values; these values are shown in Table 6-3.

Figure 6-4 shows the registry keys and values for
this example custom tool.

Figure 6-4. Custom tool registry settings

6.5.3. Running the Tool

Now your
custom tool should be ready to use. Inside Visual Studio, you can
create a file and specify that it should be handled by your custom
tool in the Properties window, as shown in Figure 6-5.

Figure 6-5. Specifying the custom tool

Whenever this file is saved, the custom tool will be run and your
code will be generated. You can view this generated code by clicking
the Show All Files button in the Solution Explorer. You will then see
a plus sign next to your file, and when you click that plus sign, you
will see the generated file as shown in Figure 6-6.

Figure 6-6. Viewing the generated file

You can then double-click on the .cs file and
view the code that was generated by your custom tool; in my example,
you would see the following code:

using System;
namespace Vehicles
{ 
public class Car { } 
}

This was a very simple example. Custom tools are limited only by what
you can think of to generate; they are very powerful tools and have
great potential to save time through code generation.