Generating Custom Exceptions in Visual Studio 2005

Overview

The following quick tutorial will demonstrate the use of CodeSmith with Visual Studio. 

Sample Project

This tutorial will use a simple Windows Form application that raises a custom exception.  The applications needs two custom exceptions called NameNotFoundException and ValidationException. The custom exception classes are generated by CodeSmith.

Exception Template

The Custom Exception template generates an exception class that implements the recommend pattern.  The template has the following properties.

Running Template

The first thing you need to do to use the template in Visual Studio is to create an XML file that contains the property set information.  The easiest way to do that is to run CodeSmith, set the property values, and Save Property Set XML.  (See Figure 1)

Integrating into Visual Studio Project

 The next step is to include the property set XML file into the Visual Studio project.  Then edit the XML file to include a <template path="" /> element. Next wrap the <propertySet> element in a <propertySets> element.

The sample application also needs a custom validation exception.  We can modify the XML file to also generate the ValidationException. To do this, you need to add another <propertySet> element that contains a <property> element for ClassName and ClassNamespace.

The XML file should look something like this when done.

<?xml version="1.0" encoding="utf-8"?>
<codeSmith>
  <!-- template needed for CodeSmith Custom Tool -->
  <template path="..\CustomException.cst" />
  <propertySets>
    <!-- NameNotFoundException, setting all properties-->
    <propertySet>
      <property name="Accessibility">Public</property>
      <property name="BaseClass">Exception</property>
      <property name="ClassName">NameNotFoundException</property>
      <property name="ErrorCode">-2146232832</property>
      <property name="Arguments">
        <item key="Name">string</item>
      </property>
      <property name="ClassNamespace">CodeSmith.Tutorial.VisualStudio</property>
      <property name="ArgumentMessage">Name '{0}' Not Found.</property>
    </propertySet>
    <!-- ValidationException, using default properties -->
    <propertySet>
      <property name="ClassName">ValidationException</property>
      <property name="ClassNamespace">CodeSmith.Tutorial.VisualStudio</property>
    </propertySet>
  </propertySets>
</codeSmith>

Running the Custom Tool

To use the CodeSmith custom tool to run the template, you need to set the Custom Tool property on the XML file. To do this, select the XML file in the Solution Explorer.  Then set the Custom Tool property in the properties window to CodeSmithGenerator.   (See Figure 2) You can now right click on the XML file and select Run Custom Tool.  This will generate the new class file that is the result of running the template.

Running in the MSBuild BeforeBuild Target

CodeSmith also includes a MSBuild task that can be used to run templates.  One way to you can use this task in your project is to edit the Visual Studio 2005 project file. First you'll need to add an import for the CodeSmith.Targets file.  Next, you can use the built in target called BeforeBuild that gets called before the project is compiled.  In that target, add the <CodeSmith PropertySetFile="" /> element.  The following project file fragment is an example of what you need to add.

<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <!-- Add at bottom of Project File -->
  <Import Project="$(MSBuildExtensionsPath)\CodeSmith\CodeSmith.Targets"/>
  <Target Name="BeforeBuild">
    <CodeSmith PropertySetFile="Exceptions.xml" OutputFile="Exceptions.cs" />
  </Target>
</Project>

Now, when you start a build of the project, CodeSmtih will run the template before the project is compiled.

References

• CodeSmith - http://www.codesmithtools.com/
• Custom Exception Template - http://community.codesmithtools.com/files/9/templates/entry12291.aspx
• Microsoft Visual Studio 2005 - http://msdn.microsoft.com/vstudio/