October 21, 2014
Hot Topics:
RSS RSS feed Download our iPhone app

Technique Sharing with Project Templates

  • September 13, 2002
  • By Paul Kimmel
  • Send Email »
  • More Articles »

Modifying Source Files

There are several files that we might have to modify. The specific files depend on the template we are creating. There is a common.js file, a default.js file, and specific files that are related to your template. The files ending with .js are JScript.Net files. These files can be found by searching the Vb7 folder. The .js files contain external code that is employed by the VsWizard.dll. The VsWizard.dll is the part of Visual Studio .NET that copies and modifies template files and adds them to your project.

For our purposes we copied an existing template that is close to the final result. The AppConfiguration template adds an App.config file to your Visual Basic .NET project. We want an App.config file with a BooleanSwitch. Thus we only need modify the source template file named App.config. This file can be found in C:\Program Files\Microsoft Visual Studio .NET\Vb7\VBWizards\BooleanSwitch\Templates\1033\App.config. Listing 1 shows the template file after the switch has been added.

Listing 1: An App.config template file that contains the state information for a BooleanSwitch.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.diagnostics>
    <switches>
      <add name="mySwitch" value="0" />
    </switches>
  </system.diagnostics>
</configuration>

The switch is straight forward. The name of the switch is expressed in the add tag's name attribute and the state is indicated by the value attribute. I defined the switch to be named mySwitch and the value is 0. Any non-zero value is treated is a switch being enabled and 0 indicates a disabled switch. (If we write our code to use a BooleanSwitch then we enable or disable that code by modifying the value attribute of the switch.)

Writing the Wizard Launch File

For Visual Studio .NET to launch the wizard and use the template we have to write a wizard launch file. The wizard launch file is read by Visual Studio, which in turn figures out what wizard application to run. Certainly we could create a custom wizard, but project templates are managed by the VsWizard.dll. This DLL comes with Visual Studio .NET. All we have to do is tell Visual Studio .NET to use it. Listing 2 shows the wizard launch file for the BooleanSwitch template.

Listing 2: The wizard launching file content.

VSWIZARD 6.0
Wizard=VsWizard.VsWizardEngine
Param="WIZARD_NAME = BooleanSwitch"
Param="WIZARD_UI = FALSE"
Param="PROJECT_TYPE = VBPROJ"

I named this launching file BooleanSwitch.vsz. Visual Studio .NET needs a reliable way to find these files. The VSDir file plays this role. After you have defined the wizard launch file place it in the C:\Program Files\Microsoft Visual Studio .NET\Vb7\VBProjectItems\ folder. This also happens to be the folder that contains the VSDir file.

Writing the VSDir File

The VSDir file is read by Visual Studio .NET. These files are used to locate wizard launching files. You need to add a specific entry to the VSDir file located at C:\Program Files\Microsoft Visual Studio .NET\Vb7\VBProjectItems\LocalProjectItems\LocalProjectItems.VSDir. This file contains entries with specific information. I will tell you that I simply copied the AppConfiguration line already in the VSDir file and made the necessary modifications.

You can look in Visual Studio .NET help for information describing what these VSDir entries our. I summarized the meaning of the values in Table 1. Listing 3 contains the entry I added to the LocalProjectItems.VSDir file.

Listing 3: The VSDir file entries are used to find wizard launching files.

..\BooleanSwitch.vsz|{164B10B9-B200-11D0-8C61-00A0C91E29D5}|Boolean
Switch Configuration File|255|#3121|{164B10B9-B200-11D0-8C61-
00A0C91E29D5}|4559| |App.config

 

Entry

Description

..\BooleanSwitch.vsz

Relative path name for the wizard launch file

{164B10B9-B200-11D0-8C61-00A0C91E29D5}

The GUID of a resource file. (You can search the registry if you are curious as to what resource file this is)

Boolean Switch Configuration File

The display name for the template item

255

The sort priority

#3121

A resource identifier for a description

{164B10B9-B200-11D0-8C61-00A0C91E29D5}

A GUID or a DLL path for a DLL that contains an icon for the template

4559

The icon resource identifier

<blank>

Flags (see the Visual Studio .NET help)

App.config

The suggested base file name

Table 1: A summarization of entries in the VSDir file.

When you are finished you will see the Boolean Switch Configuration File applet in the Add New Item dialog. You can open this dialog by selecting File|Add New Item. You can test the BooleanSwitch by declaring an instance of the System.Diagnostics.BooleanSwitch class. Listing 4 contains code that shows you how to test the switch.



Click here for larger image

Figure 2: The Boolean Switch Configuration File applet in the Add New Item dialog.

Listing 4: Testing the Boolean Switch template results.

1:  Public Class Form1
2:      Inherits System.Windows.Forms.Form
3:  
4:  [ Windows Form Designer generated code ]
5:    Private Shared Switch As BooleanSwitch = _
6:      New BooleanSwitch("mySwitch", "For debug text")
7:  
8:   Private Sub DebugWrite(ByVal Text As String)
9:     If (Not Switch.Enabled) Then Exit Sub
10:     System.Console.WriteLine( _
11:       DateTime.Now.ToString() + ":" + Text)
12:   End Sub
13: 
14:   Private Sub Button1_Click(ByVal sender As System.Object, _
15:     ByVal e As System.EventArgs) Handles Button1.Click
16: 
17:     DebugWrite("This is a test!")
18: 
19:   End Sub
20: End Class

Lines 5 and 6 show you how to declare and create an instance of a BooleanSwitch. We identify the external switch to examine as the first parameter of the BooleanSwitch constructor. I encapsulated the switch in a method named DebugWrite. Using this approach I only need test the switch in one location, on line 9. When the switch is enabled information will be written to the console. When the switch is disabled the call in effect becomes an empty function call.

Of course you could use conditional pragmas like #If Debug and accomplish the same thing. However, you would have to recompile your code when you changed the Debug state. Using the BooleanSwitch is an improvement over that.

Summary

BooleanSwitches allow you to toggle whether debug and trace code is run from an external source without recompiling your application. This is a great technique that should be shared with all developers. By making a project item template for the switch we can quickly make it accessible, without for example, all programmers learning to write the switch XML.

Creating a template item requires knowledge of a couple of disciplines, like how to write JScript. In our example, we copied an existing template, modified the templates files to define the new behavior, wrote a wizard launching file, and added an entry to the VSDir file. This approach is always a good start when it comes to creating new templates. For more advanced wizards you may have to create a user interface and customize the JScript code. As always a good way to learn is learn from the efforts of others, and there are dozens of wizards that already exist.

About the Author

Paul Kimmel is a freelance writer for Developer.com and CodeGuru.com. Look for his recent book "Advanced C# Programming" from McGraw-Hill/Osborne on Amazon.com. Paul will be a keynote speaker in "Great Debate: .NET or .NOT?" at the Fall 2002 Comdex in Las Vegas, Nevada. Paul Kimmel is available to help design and build your .NET solutions and can be contacted at pkimmel@softconcepts.com.

# # #





Page 2 of 2



Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Sitemap | Contact Us

Rocket Fuel