Tutorials

Generating Custom Exceptions in Visual Studio 2005

pwelter34 — Thu, 06 Apr 2006 21:47:00 GMT

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.

Accessibility	The accessibility of the class to be generated.
Arguments	List of exception argument properties. Example FileName=string
ArgumentMessage	The string format message to use in the ToString method of this exception when there are custom arguments. Example: File '{0}' Not Found.
BaseClass	The name of the Exception class to inherit.
ClassName	The name of the Exception class to be generated.
ClassNamespace	The namespace to contain this class.
ErrorCode	The HResult Error Code this exception represents.

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/

Building a template to generate stored procedures

ejsmith — Wed, 15 Feb 2006 21:07:00 GMT

Download Links

Introduction

CodeSmith is a template based code generator for any ASCII language. It uses a syntax very similar to ASP.NET. This tutorial describes the process of building a template to generate SELECT/INSERT/UPDATE/DELETE stored procedures.

Getting Started

All templates must include a CodeTemplate directive like this one.

<%@ CodeTemplate Language="C#" TargetLanguage="T-SQL"
  Description="Generates SELECT/INSERT/UPDATE/DELETE stored procedures." %>

Here we tell CodeSmith that we plan to use C# as our template language, we plan to generate code for the T-SQL language and we also provide a description for what the template does. The Language attribute tells CodeSmith what language we will use to write our template code and can be C# (C#, CS, CSharp), VB.NET (VB, VBS, VisualBasic, VBScript) or JScript.NET (JS, JScript, JavaScript). The TargetLanguage attribute can be anything, but setting it to T-SQL will cause the template to be grouped together with other T-SQL templates in CodeSmith Explorer's target language view. The TargetLanguage attribute is also used to syntax highlight the static content in a template in CodeSmith Studio. And finally, the Description attribute allows us to provide a brief description of the template that will be shown in CodeSmith Explorer.

In order to be able to generate code based on a database table, the template must somehow know about this table. CodeSmith allows us to provide this contextual information to the template by specifying Property directives.

<%@ Property Name="SourceTable" Type="SchemaExplorer.TableSchema"
  Category="Context"
  Description="Table that the stored procedures should be based on." %>

The Name attribute tells CodeSmith what we want the property to be named in our template. This is the name that we will use to access the property in our template. The Type attribute tells CodeSmith what type our new property should be. This can be any .NET type that has a designer (most built-in .NET types have designers). In this case we use a type from CodeSmith's included Schema Explorer library. This type allows us to pick a table from a database and will then tell us anything we want to know about that table. We will use this information to drive our template. The Category attribute simply allows us to put our new property into a group of properties with the same category. And lastly, the Description attribute allows for a brief description of what the property will be used for in the template.

CodeSmith allows the flexibility for anyone to create a new .NET type and, as long as they also create a designer for that type, it can be used in your templates. The included Schema Explorer library is an example of this flexibility. CodeSmith does not know anything about Schema Explorer, so we must instruct our template on how to find the SchemaExplorer.TableSchema type. We do this by adding an Assembly directive.

<%@ Assembly Name="SchemaExplorer" %>

This just tells our template that we plan to make use of code found in an external assembly. The Name attribute must correspond to an assembly (without the .dll extension) in either the same directory as the template or in the same directory as the CodeSmith executable.

Writing Our Template

Now that we have setup everything that we will need to base our template on, we can begin writing our template content. It is always best to start with an example of what you want the output to look like. Here is an example UPDATE stored procedure for the Northwind..Products table.

-----------------------------------------------------------------
-- Date Created: Thursday, January 02, 2003
-- Created By:   Eric J. Smith
-----------------------------------------------------------------

CREATE PROCEDURE dbo.UpdateProducts
  @ProductID int,
  @ProductName nvarchar(40),
  @SupplierID int,
  @CategoryID int,
  @QuantityPerUnit nvarchar(20),
  @UnitPrice money,
  @UnitsInStock smallint,
  @UnitsOnOrder smallint,
  @ReorderLevel smallint,
  @Discontinued bit
AS

UPDATE [Products] SET
  [ProductName] = @ProductName,
  [SupplierID] = @SupplierID,
  [CategoryID] = @CategoryID,
  [QuantityPerUnit] = @QuantityPerUnit,
  [UnitPrice] = @UnitPrice,
  [UnitsInStock] = @UnitsInStock,
  [UnitsOnOrder] = @UnitsOnOrder,
  [ReorderLevel] = @ReorderLevel,
  [Discontinued] = @Discontinued
WHERE
  [ProductID] = @ProductID

Now we must begin to make this into a dynamic template based on our SourceTable property. Let's start with a simple change to make the Date Created comment dynamic.

-- Date Created: <%= DateTime.Now.ToLongDateString() %>

Just like in ASP.NET we use the <%= %> construct. When the template is executed, this expression will be expanded to the current date in long date form.

Now we need to figure out how to build our list of parameters for the stored procedure. We will derive this list from the information in the SourceTable.Columns property. This property is a collection of ColumnSchema objects that represent each column in the selected table. Here is a simple example of outputing each column in the table.

<% for (int i = 0; i < SourceTable.Columns.Count; i++) { %>
  <%= SourceTable.Columns[i[.Name %>
  <% if (i < SourceTable.Columns.Count - 1) { %>,<% } %>
  <% } %>

In this example we use the <% %> construct to add logic to the template. What language you selected in the Language attribute from above will determine the language that you will need to use for your template logic. In our example, we have specified C# as our language so that is what we use here. The output from this example when the selected table is Northwind..Products looks like:

ProductID,
  ProductName,
  SupplierID,
  CategoryID,
  QuantityPerUnit,
  UnitPrice,
  UnitsInStock,
  UnitsOnOrder,
  ReorderLevel,
  Discontinued

This is a nice start, but we have a little more work to do before this looks like a real set of parameters. Since the logic for each parameter will be somewhat complex, we should go ahead and create a method to output each parameter. To do this we will need to use a <script> block. Again, this is just like ASP.NET.

<script runat="template">
public string GetSqlParameterStatement(ColumnSchema column)
{
  string param = "@" + column.Name + " " + column.NativeType;

  switch (column.DataType)
  {
    case DbType.Decimal:
    {
      param += "(" + column.Precision + ", " + column.Scale + ")";
      break;
    }
    default:
    {
      if (column.Size > 0)
      {
        param += "(" + column.Size + ")";
      }
      break;
    }
  }
  return param;
}
</script>

Instead of setting the runat attribute to server like we would do in ASP.NET, we set it to template. This causes the CodeSmith compiler to process this script block as code instead of passing it on as part of the template content. This distinction allows the creation of templates that output ASP.NET code with server <script> blocks. Also, on that note, I should mention that you will need to escape your ASP.NET constructs if you plan to have them output in a template (ie. <%% expression %%> results in this output <% expression %>).

Here is a look at our final code for the UPDATE stored procedure:

-----------------------------------------------------------------
-- Date Created: <%= DateTime.Now.ToLongDateString() %>
-- Created By:   Generated by CodeSmith
-----------------------------------------------------------------

CREATE PROCEDURE dbo.Update<%= SourceTable.Name %>
  <% for (int i = 0; i < SourceTable.Columns.Count; i++) { %>
  <%= GetSqlParameterStatement(SourceTable.Columns) %>
  <% if (i < SourceTable.Columns.Count - 1) { %>,<% } %>
  <% } %>
AS

UPDATE [<%= SourceTable.Name %>] SET
  <% for (int i = 0; i < SourceTable.NonPrimaryKeyColumns.Count; i++) { %>
  [<%= SourceTable.NonPrimaryKeyColumns[i[.Name %>] = @
  <%= SourceTable.NonPrimaryKeyColumns[i[.Name %>
  <% if (i < SourceTable.NonPrimaryKeyColumns.Count - 1) { %>,<% } %>
  <% } %>
WHERE
  <% for (int i = 0; i < SourceTable.PrimaryKey.MemberColumns.Count; i++) { %>
  <% if (i > 0) { %>AND <% } %>
  [<%= SourceTable.PrimaryKey.MemberColumns[i[.Name %>] =
  @<%= SourceTable.PrimaryKey.MemberColumns[i[.Name %>
  <% } %>

Generate The Code

Now that you have built your template, you can use CodeSmith to execute it and see the results. You can execute the template by double-clicking the codesmith_sp.cst file that is included in the download at the top of this page. You will then see a screen that looks like this:

Click the elipses next to the SourceTable property.

Now click the elipses next to the Data Source drop down.

Select Add.

Enter the Data Source information. Name can be anything but you should make it something that represents the database in your connection string since this the name that will be used to select the Data Source in the future. Provider Type can be SqlSchemaProvider or ADOXSchemaProvider. SqlSchemaProvider should be used for any SQL Server or MSDE database and ADOXSchemaProvider should be used for any other database that has an ADOX provider. The Connection String is the same as any other connection string you would specify in your application. See the SqlConnection documentation for SqlSchemaProvider and the ADODB.Connection documentation for the ADOXSchemaProvider. Here we specify the Northwind database located in the .NET SDK sample MSDE instance. These settings should work for anyone who has installed the .NET SDK QuickStart samples. Click OK once you have entered all the information. Then click Close on the Data Source Manager screen. Now you should see a list of tables in the Northwind database. Select the Products table.

Select Generate and see the results! After you generate the code, you can click the Copy Template Output button at the top and the output will be copied to your clipboard. Another great way to generate code once you have finished building your template is using the CodeSmith Explorer window.

This is the window that is displayed if CodeSmith is started with no parameters. It allows you to see all templates in a given directory. You can then drag a template to any application that supports dropping text (this includes VS.NET). When you do so the template properties window will display, you will set all required properties and when you click Generate the output will be added to wherever you dragged the template.

Conclusion

CodeSmith allows the use of templates to avoid repetative coding tasks. We used a previous version of CodeSmith in our last project and were able to generate over 60% of our code. This included generating stored procedures, business objects, collection classes, ASPX pages and codebehind files.

Build a Data Access Layer in less than 15 minutes

ejsmith — Mon, 13 Feb 2006 18:16:00 GMT

Download Links

Introduction

In this article you will learn how to build a Data Access Layer using Microsoft’s Enterprise Library in less than 15 minutes using CodeSmith and the .netTiers Template Library.

The Data Access Layer, from here on out referred to as the DAL, is the layer of application functionality that encapsulates all interactions with the database. Typically this type of code is hand written and requires specialized knowledge, not only of .NET, but of the specific data access routines too. Writing the DAL code for an application is one of the most monotonous, time consuming, repetitive, and likely bug-ridden aspects of building software.

For this article we’ll use the sample Northwind database in SQL Server, but these examples will work with any database. And of course, after this article you’ll no longer view writing the DAL for your application as monotonous and time consuming, but quick, easy, and simple!

If you follow this article at the end you will be able to create a complete best practices Data Access Layer in just under 1 minute (the other 14 minutes are for downloading the software the first time).

Code Generation, a brief overview

Code generation, or the use of software tools to generate code, is not a new concept. In fact, code generation has been around for quite some time. In this article I’m going to use CodeSmith as the tool for generating both the code and T-SQL scripts for the DAL.

CodeSmith is a developer productivity tool that enables developers to use templates to control the formatting and desired code output. Therein is the beauty of CodeSmith - software developers still retain full control over the code created through templates. Templates provide the opportunity for people to create new and interesting code reuse and generation libraries, such as the .netTiers templates used in this article.

Step 1 – Setup

The first step is to get the necessary tools (CodeSmith) and templates (.netTiers). CodeSmith is a commercial developer tool, but there is a 30-day free trial we can use for the purpose of this article:

Download and Install CodeSmith

http://www.codesmithtools.com/

CodeSmith comes with a lot of built-in templates and the next service pack will include the .netTiers templates shown in this article.

Now that CodeSmith is installed, download the .netTiers template library:

Download .netTiers Template Library for CodeSmith

http://www.nettiers.com/

On the .netTiers site click on the "Latest Download" link in the left-column; next, click on "available for download" at the top of the page. This will take you to another page where you can download the latest Windows MSI installer.

The last step is to ensure you have a SQL Server database setup and have a connection string you can use to connect to the database.

Step 2 – CodeSmith

After downloading and installing CodeSmith you should be able to open it from All Programs | CodeSmith 3.1 | CodeSmith Studio. Before we use the .netTiers templates you need to familiarize yourself with CodeSmith.

As mentioned in the introduction, CodeSmith is a template driven code generation tool. There is a window on the right of CodeSmith called the Template Explorer. The Template Explorer provides you with a quick and easy way of accessing the templates you’ve installed or written:

To explain the rest of CodeSmith we need a template. Open the Hashtable.cst template from Template Explorer by double-clicking on it.

Hashtable.cst is one of the great sample templates included with CodeSmith and is used to generate strongly typed collections that use the .NET Hashtable type as the base data type. Before we explain the template, let’s quickly look at another window in CodeSmith, the Properties window:

The Properties window allows you to set properties for the template. When using the Hashtable.cst template we need to set some common elements such as the generated ClassName, ItemType, and KeyType. For example, if you wanted to create a strongly typed collection of Person objects accessed by an integer with a class name of PersonCollection, you would set the ClassName to PersonCollection, the ItemType to Person, and the KeyType to int. You could generate the source for this strongly typed collection now by simply clicking the Run button in CodeSmith (found on the toolbar).

If you took a moment to examine the Hashtable.cst template file you might say to yourself, "This looks a lot like ASP.NET". You’d be correct. CodeSmith templates are modeled after ASP.NET Pages and share many similar ideas. However, whereas ASP.NET Pages are used to generate HTML, CodeSmith Templates are used to generate source files or other text files.

The most important thing to remember about CodeSmith is that CodeSmith does not limit your creativity by forcing you into what code is generated. Since it is template driven the code output is completely controlled by you.

Step 3 – Generate the DAL

Now that you have a basic understanding of CodeSmith I want to show you the .netTiers templates.

Remember, the idea behind CodeSmith is that it allows you to write code faster, with fewer defects. The .netTiers templates take that one step further and create a DAL for you that follows all the recommended Patterns & Practices from the team at Microsoft by the same name.

First we need to add the .netTiers templates to the CodeSmith Template Explorer:

In Template Explorer click on the Open Folder icon to browse for a folder containing templates.
Go to the folder where .netTiers was installed. On my computer this is:
C:\Program Files\SerialCoder\NetTiers 0.9.2 - Caribert\Templates\
Once this folder is created as a shortcut in Template Explorer, expand it and select NetTiers.cst
Now that the .netTiers templates are installed you need to configure a data source. With the NetTiers.cst template open, open the Properties window and configure a Source Database by clicking on the ellipses:
This opens the Database Picker, we’re going to create a new data source so click on the ellipses in the Database Picker to open the Data Source Manager. In the screen shot below is an example of how this should look (choose a name that let’s you quickly know what database you’re working with):
Test the connection to ensure it works and then back out of these dialog windows by clicking OK. Make sure the new data source is selected.
Finally, set the EntireDatabase property to True, set the NameSpace property to Demo, and set the OutputDirectory property to the directory where you would like the generated files to be located. You will need to create the output directory if it doesn’t exist.

Once you’ve completed these steps your property window for the NetTiers.cst template should look similar to the screenshot below (changes highlighted):

We are not going to show anywhere near the full capabilities of .netTiers in this article or CodeSmith, but we’ve now done enough to generate a DAL. Click the Run button in the CodeSmith toolbar to generate the code.

Step 4 – Review the Generated Code

Open Visual Studio .NET and if you followed the directions above you should find a Demo.sln file in the c:\NetTiers\Northwind_Demo\ directory.

Take a moment and browse the solution and project files in Visual Studio:

You should find 3 projects within the solution:

Demo – the main library that contains the classes you will use within your application to interact with the database.
Demo.DataAccessLayer – the library containing the data access implementation code.
Demo.DataAccessLayer.SqlClient – the library containing the Microsoft Patterns & Practices classes for working with the database.

Step 5 – Compile …and we’re done!

Next, with Visual Studio still open, compile the project.

Congratulations! You now have a Data Access Layer that implements the recommended best practices from the Microsoft Patterns & Practices group for working with a database.

You can now begin using your new Data Access Layer in other Visual Studio .NET projects. For example, below is code to retrieve, update and then delete an employee record.

using Demo.DataAccessLayer.SqlClient;

// Select by primary key
Employee employee = SqlDataRepository.EmployeeProvider.GetByEmployeeID(13);
employee.FirstName = "John";
employee.LastName = "Doe";

// Save changes
SqlDataRepository.EmployeeProvider.Save(employee);

// Delete record
SqlDataRepository.EmployeeProvider.Delete(employee);

For more information on how to use the generated DAL, take a look at the .netTiers wiki here:http://nettiers.com/DocumentationPage.ashx

Remember all of the Data Access Layer code was generated by templates, so later when you change your database structure you can simply rebuild the DAL again from the templates. Furthermore, you can even extend the templates with your own ideas, comments, naming conventions, patterns, and so on.

Conclusion

The possibilities for CodeSmith templates are limited only by your own creativity. As I’ve demonstrated in this article, CodeSmith is an exceptionally powerful developer productivity tool. Coupled with the .netTiers templates you can write a best practices Data Access Layer for your application in a matter of minutes.

You can also watch a video of this presentation here:

http://community.codesmithtools.com/r.ashx?id=1

One of the fun features added into version 3.1 was a simple "value calculator". The value calculator provides a conservative estimate of the time saved by using CodeSmith:

As shown in the screenshot above, using the .netTiers templates with CodeSmith generated 91,559 lines of code. Assuming a developer can write approximately 50 lines of code per-hour (had we written this manually) writing the code we generated would have taken 1,800 hours. Taking this a step further and assuming that a developer’s time is approximately $60/hour, CodeSmith and .netTiers together saved you 1,800 hours of your life and $109,000 for your company!

So get CodeSmith… and then go ask for a raise.

CodeSmith and .netTiers Resources

If you have questions about CodeSmith, please be sure to visit the CodeSmith community portal at: http://community.codesmithtools.com. The CodeSmith community portal is a great resource where people can share templates, ideas, and help each other.

If you are interested in purchasing CodeSmith, please visit the CodeSmith website at http://www.codesmithtools.com. There you will find the CodeSmith store where you can purchase license keys to unlock the 30-day trial version. If you have other questions, just email sales@codesmithtools.com.

If you have questions about the .netTiers templates, please visit the .netTiers forum at:

http://community.codesmithtools.com/forums/16/ShowForum.aspx