Topics in this section:

Prerequisites

Before you start, you will need to download the demo project files for this tutorial here and extract the zip archive somewhere on your computer.

Obviously I'm also assuming you have downloaded and installed the CH3ETAH. If not, you can get the latest version here .

In this tutorial I'm using MS Visual Studio 2003, SQL Server 2000 (along with the Northwind Traders example database). You should be able to complete the tutorial using other versions of these products (or other products entirely), but you may need to adapt the instructions to suit your environment.

A familiarity with code generation concepts in general would certainly be useful, but you can complete the tutorial just fine without it. One of my goals is to make available an introduction to code generation and the principles driving this project. Until then, I highly recommend you check out Code Generation in Microsoft .NET, by Kathleen Dollard and Code Generation in Action, by Jack Herrington. These are two of the best books that I've read on the subject of implementing code generation tools and practices. One of this project's main goals is to implement and build on the concepts taught in these two books.

Creating a code generation project in CH3ETAH

After downloading and extracting the zip file for this tutorial, open CH3ETAH and create a new project by going to the file menu and selecting new. Navigate to the "GettingStarted\Practice" folder, create a name your project such as "Northwind.ch3", and click Save. (Note that here I'm using the name "GettingStarted_Practice.ch3" but the name you choose for your project doesn't really matter)

Editing configuration settings

After your project has loaded, select the root node in the Project Explorer and in the properties window, define the following (relative) paths:

You should see the Packages node loaded with the templates that are in the "Practice" folder which you downloaded earlier. If not, make sure you created your project in the right directory.

Double-click on the global parameters node in the Project Explorer and then click the "Add" button at the bottom to create a new parameter. Named the parameter "EntityNamespace" and give it a value of "Northwind.Domain".

This Global Parameters editor lets you define parameters that will be supplied to your code generation templates at generation time. Here we are telling our templates to output "Northwind.Domain" as the namespace for our classes. (Note that alternately we could define custom metadata for each one of our classes so that they didn't all have to output to the same namespace. More advanced metadata and parameter topics will be covered in more detail later.)

How you access these parameters in your template depends on the template language engine you are using. For example: in NVelocity templates parameters are accessed using the syntax ${ParameterName}, while in XSLT templates you would use <xsl:value-of select="$ParameterName"/>.

You can access "Applications Settings" through the Edit menu. Currently the only settings available through this dialog are those relating to Object-Relational Mapping. Here you can define the defaults that will be used when new data sources are added to a project. Once a data source has been created, you can edit its ORM settings by selecting the data source in the Project Explorer and editing the configuration settings in the Properties Window. Go ahead and change AutoEnableMappedIndexes to false and AutoMapLinks to true, and then click Save.

Getting metadata from SQL Server

Right-click on the Data Sources node now, select "Add New Data Source", and name your new data source "Northwind". In the data source editor window, click the Build button to create your connection string. (Alternately, you can enter your connection string directly into the connection string text box) To connect to the Northwind database in SQL Server, choose "Microsoft OLE DB Provider for SQL Server" under the Provider tab, use the Connection tab to edit your connection settings, and click OK. (Note that your connection settings may differ from those shown here.)

When you close the connection string builder, the Treeview below should be filled with all of the tables and views in your database. Select "Orders" and "Order Details" from under the Tables node and then click the "Add/Update Selected" button on the right to add these two entities to your project.

When you expand the Metadata Files node in the Project Explorer, you should see that an XML file was created for each one of the tables selected in the previous step. Double-click the Orders XML file to edit the properties for this entity. The metadata file editor has two views: Design and XML. Design view allows exploring your metadata tree visually and editing its components through custom GUI widgets as well as the properties window, providing any context-sensitive help that may be available. Currently design view is only supported for O/R (Object Relational) entities, but pluggable support for other strongly typed metadata is in the works.

In the design view for the Orders entity, you'll notice that it was given the same name as the Orders table. In C# (and .NET in general) it's considered good practice to name your classes in the singular, so let's go ahead and change our Orders entity to Order. You should also update the CollectionName and PluralName properties as well. If you look at the links that were generated you will see that the link to our OrderDetails entity is spelled incorrectly. Don't worry about this for now, when we update the OrderDetails entity, this link should be updated automatically for us. Go ahead and make the same changes to the OrderDetails entity now. When you're done editing the entity XML files, save your changes and close the editor windows.

NOTE: in design view, double-clicking on any one of the entities sub-attributes in the Treeview will open up a dialog box that gives you an alternate method of editing that attribute's properties. (More intuitive access to the contents of these dialogs is planned and should be available soon)

Using templates for code generation

Now let's use the XML files we've created to generate some code. Right-click on the "Generator Commands" node in the Project Explorer, and select "Add New Code Generator Command". Name this command "Abstract Entity" using the Properties Window and define the following attribute values in the editor window:

Make sure that both of the XML files are selected and that "Auto-select new files" is checked, then save your changes.

If you click the Edit button next to the template name, you can see and edit the template for this generator command. You can also edit templates from the Packages node under the Project Explorer Later on we'll cover templates editing in more detail.

Add another generator command named "Business Entity" and define the following attribute values in the editor window:

And again select both XML files and then save your changes. The reason why we don't want to overwrite existing files for this command is because this class will inherit from our abstract entity and be used for any customizations that we want to make. We wouldn't want our custom code to be overwritten! Another way of preserving custom changes would be to use regions and merging. The ghostly se subjects will be covered in a future tutorial.

Now let's generate some code! Click the Run Project button on the toolbar (the green arrow). If you've configured everything correctly, you should see a bunch of messages flying by in the output window with information about the generation process. After a couple of seconds, code generation should be complete and for files should have been created in the Northwind.Domain and Northwind.Domain\Generated folders in the output directory where your CH3ETAH project is located.

Go to the output directory and open the Ch3Etah.GettingStarted solution in Visual Studio.

In the Solution Explorer, select the four files that were generated, right-click, and select "Include In Project".

Then open the files and take a look at the code that was generated. There isn't much here right now, but the templates could be modified to support just about any functionality you can think of.

You can open the code editor for the orders form in the Northwind.Gui project and write code to test the entities that we've just generated. If you've done everything correctly up to now, the solution should compile and run.

Something to note: going to all this effort to generate simple classes for two relational entities isn't very efficient. You could probably get the same result in the same, or maybe even less time by hand coding. But the magic of code generation kicks in when you start generating multiple artifacts for larger numbers of entities. We've used this process for dozens of projects with the number of mapped entities ranging anywhere from 10 to about 100. Some of the artifacts we can generate for each entity include much more functional classes than what we just created, binding-friendly collections, NHibernate mapping files, stored procedures, project stubs, and typed datasets to facilitate using the design time formatting capabilities of .NET controls such as those from Janus and Infragistics. In these types of scenarios, the time savings can be astounding. We'll be doing some of that below.

Adding custom metadata

This section is not yet finished

CH3ETAH's metadata structure

How metadata gets passed to templates

Adding custom elements and attributes to a strongly typed metadata structure

Using custom XML structures within CH3ETAH

Creating your own templates and packages

This section is not yet finished