GAX

Sixeyed.Guidance.CodeGeneration: Technical Walkthrough

EltonStoneman — Mon, 09 Mar 2009 18:05:28 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

The Code Generation Guidance Package on CodePlex was designed to be extensible and reusable. There are three main C# projects, which isolate logic for code generation, and the UI and GAX components.

Sixeyed.CodeGeneration

This is the core project, defining how metadata is represented and retrieved, and defining configuration for code generation runs. Metadata is defined in terms of:

A metadata source, which contains the logic for connecting to the source
A metadata provider, which uses the source to provide a list of available items, and to populate requested items
Metadata items, which are a representation of the metadata, typically using an appropriate .NET framework class

Code generation and UI logic always works on the interfaces which define these components, and the relationships between them:

In the Add Generated Items recipe, the available source types, sources and providers are populated from the collection of IMetadataSource objects held in the static SourceContainer class (additional sources can be added to the container at runtime using the SourceAssemblyConfiguration recipe argument – described in Sixeyed.Guidance.CodeGeneration Sample Package). When a provider is selected, GetItemNames is called to populate the list of available metadata items. When the selected items are iterated over in a code generation run, GetItem is called and the populated IMetadataItem is loaded as a property for the T4 template. The metadata item exposes the provider, and the provider exposes the source so the template can connect directly to the metadata if it needs to.

Each metadata interface has an abstract base class which implements it and contains core logic. For a given source, there may be an additional base class which abstracts logic common to that type of source. In Sixeyed.CodeGeneration.Metadata.Database.Source, DatabaseSource contains logic for accessing ADO.NET data sources in terms of IDbConnection and IDbCommand objects; SqlServerSource contains overriding logic to specify SqlConnection and SqlCommand usage – any additional database sources would do the same. Similarly for the SOAP metadata source, the logic for accessing WSDL is abstracted into a base class which may be used by other sources (e.g. a WCF specific source):

IMetadataProvider contains logic for accessing the source and retrieving a list of available items, and for populating a named item. The majority of logic is in the generic base class, so provider classes are quite simple. Simpler still are metadata item classes, which inherit the generic ItemBase class, specifying the underlying type of the item (XmlSchema in this case), without requiring any additional code.

Logic for populating template properties and executing T4 templates is located in the Guidance project rather than the code generation project, as it is dependent on the specific T4 engine being used.

Sixeyed.CodeGeneration.UI

The UI project contains generic user controls which represent metadata selections, and expose various events to notify of selection changes. The Guidance package Wizard uses these components rather than defining its own UI – the controls from this assembly allow code generation to be configured and invoked from a different UI host.

Sixeyed.Guidance.CodeGeneration

This project defines the GAX package and links together the code generation and UI components. The Guidance package is quite straightforward – it contains a single class AddGeneratedItems for the action of generating items from metadata and adding them to the selected project. The action expects SourceConfiguration, SelectedItems and TemplateConfiguration arguments; it connects to the source, iterates over the selected items and executes the template for each item.

To collect the argument values, there are custom wizard pages and value providers for each, allowing a recipe to provide ready-configured settings, or build a UI to gather them from the user:

Sixeyed.Guidance.CodeGeneration.CustomWizardPages. The custom Wizard pages use the static Metadata class to share state for the configured metadata source and provider. They override IsDataValid to determine if the page has collected enough information for the Wizard to proceed and the base class provides EnableNextStep which will advance the Wizard by enabling the Next or Finish button as appropriate. The base class will read the SourceAssemblyConfiguration recipe argument if provided, and use it to add any extra metadata assemblies at runtime.
Sixeyed.Guidance.CodeGeneration.ValueProviders. The value provider classes are straightforward, reading optional arguments from the recipe and populating the relevant metadata settings. Custom recipes can specify value providers to load settings instead of Wizard pages, so the Wizard UI can be restricted.

TODOs

There are a couple of minor changes I'd like to make to the current codebase:

Sixeyed.Guidance.CodeGeneration.CustomWizardPages.SelectTemplate defines its own UI, which should be moved to a user control in the UI project;
Sixeyed.CodeGeneration.Generation.MemberName contains methods for providing valid field and property names, but the Pascal and camel-case conversion is very basic;
Sixeyed.CodeGeneration.UI.SourceUri has some ugly hard-coding to decide which UI dialog it should show for different types of URI. It should be configurable, but I'm not happy moving it to an attribute of IMetadataSource, as that brings the UI into the core project.

And some additional metadata sources which I'll add at a future point – a Clipboard source providing access to clipboard data through text or XML providers, and a BizTalk source which will use the ExplorerOM for providers supplying application, group and instance information as metadata.

Sixeyed.Guidance.CodeGeneration Sample Package

EltonStoneman — Sun, 08 Mar 2009 17:46:00 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

The basic Code Generation Guidance Package on CodePlex comes with an additional sample Guidance package. This sample is intended to demonstrate how the functionality of the base package can be customised to create a project-specific Guidance package, where you can easily add tailored code generation recipes to your package. In the basic package are the Wizard steps necessary to configure ad-hoc code generation, but there are also ValueProviders which can read configuration from recipes without requiring the whole user interface.

Installation

You'll need to modify the hard-coded paths and URIs in the sample package, so it doesn't come with an installed release. If you open the Sixeyed.Guidance.CodeGenerationSample solution you'll see that it references the base Sixeyed.Guidance.CodeGeneration and Sixeyed.CodeGeneration assemblies. The sample contains a set of T4 templates in the \Templates\Text directory, the XML configuration for the package and the XML includes for individual recipes. There's no additional code in the sample project, all the required functionality is in the referenced base package.

Together with the GAX project, there's a database project which you can use to create a SQL Server database suitable for the data-bound recipes to run against. To install, run the CreateDatabase script and then execute the SSIS package to populate data from the included Excel workbook (this is only necessary if you want to run the recipes as-is, otherwise you can modify the XML to use your own database).

Sample T4 Templates

There are T4 templates for each of the metadata providers in the base package. The scripts named _Simple.tt are straightforward and begin with the name of the expected provider; to run them, you can use Add Generated Items from the base package, select the relevant metadata and point to the template. To demonstrate more useful code generation, there are two more substantial templates:

ConfigurationSection.cs.tt – use the File source and the Text provider on this template. If you select Configuration.txt (from the database project) as the source, the recipe will generate a typed configuration class, which has a static property to access the current config settings. The template can be easily extended to add a Default value for optional settings, and the same text file can be used to drive a different T4 template to generate the actual configuration settings;
StoredProcedure.cs.tt – use the SQL Server database source and the Stored Procedure provider. Select a procedure and the recipe will generate a DAL class to execute the stored procedure. This class won't compile, as it inherits from a base class which isn't provided, but it demonstrates one approach for DAL generation.

Sample Recipes

The included recipes demonstrate configuring one or more settings for code generation so that the Wizard can be tailored or avoided altogether. Generate Stored Procedure shows this best, configuring the metadata provider using the SourceConfigurationValueProvider:

<ValueProvider Type="SourceConfigurationValueProvider"

SourceTypeName="Database"

SourceName="SqlServer Database"

SourceUri="Data Source=x\y;Integrated Security=True;Initial Catalog=Scratchpad;"

ProviderName="Stored Procedure Provider">

</ValueProvider>

</Argument>

These settings are the equivalent of the first Wizard page, selecting the metadata source. It specifies the source type and source name, the URI for the source (in this case, the Scratchpad database included with the sample), and the metadata provider name. Having the SourceConfiguration argument pre-populated means the first Wizard page will be skipped. The recipe also specifies the T4 template to use with the TemplateConfigurationValueProvider:

<ValueProvider Type="TemplateConfigurationValueProvider"

TemplatePath="x:\y\z\Templates\Text\StoredProcedure.cs.tt">

</ValueProvider>

</Argument>

Only the template path is specified here, but other settings (target namespace, class name etc.) can also be provided. Having the TemplateConfiguration argument populated means the third Wizard page will not be shown. Running this recipe gives you a Wizard form which only contains the second page, for selecting metadata items, pre-populated with the list which has already been loaded from the configured database:

- note that the other pages are not available, so the user is constrained to using the configured source and T4 template.

Other recipes demonstrate configuring all or part of the settings needed for code generation. Generate Simple runs a template which requires no metadata, so it connects to the metadata source, runs the template and adds the project output with no user intervention. Additional Source demonstrates how you can extend the base code generation guidance package with additional metadata sources and providers of your own, without rebuilding the base package. Specify the SourceAssemblyConfiguration argument:

<ValueProvider Type="SourceAssemblyConfigurationValueProvider"

AssemblyList="Sixeyed.CodeGeneration.Tests">

</ValueProvider>

</Argument>

- and the .NET assemblies named in AssemblyList (semi-colon separated) will be interrogated at run-time to identify IMetadataSource and IMetadataProvider implementations (there'll be more detail on those interfaces in a coming post). Any available classes will be added to the list of sources and providers shown in Add Generated Items, and can also be used in SourceConfiguration argument values.

Usage

By providing custom recipes, you can tailor your own Guidance packages which contain recipes for generating classes or other artifacts based on established patterns. This gives the project team an easy way of ensuring consistency for common coding problems in the domain – configuration sections and stored procedure wrappers are simple examples. Note that the URIs and paths are hard-coded. The code generation guidance package will attempt to find a T4 template if the path is not fully stated, but it won't always succeed (there's an issue with returning the running GuidancePackage instance that I haven't tracked down). In a typical project though, templates would be in SCM and source URIs would be consistent among developers, so fully-qualified hard-coded text shouldn't be a problem.

I'll be extending the sample package to include other templates that may be useful starting points for common code generation tasks – enums to represent reference data, unit tests for .NET and BizTalk artifacts, MSBuild scripts and anything else that occurs. If you have any templates of your own which would fit in a standard library, let me know and I'll add you as a CodePlex contributor.

Code Generation Guidance Package

EltonStoneman — Sat, 07 Mar 2009 19:51:14 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

I've been working on a Guidance package which lets you use Visual Studio as a front end to generate items from T4 templates. Using a recipe wizard you choose your metadata from a Web service, database or file system source, and the template is rendered against each of the metadata objects you select. It's on CodePlex here: Code Generation Guidance Package, and comes in two flavours. The basic Guidance package has a single recipe "Add generated items" – when you run it, you specify a metadata provider, select the items to use for metadata and the T4 template to render against the items.

The second package is a sample which extends the functionality of the main Guidance package with custom recipes. This demonstrates how you can define recipes for pre-configured generation types, so the user does not need to complete all the wizard pages – one example specifies a database connection string and a T4 template for generating stored procedure wrappers; to add a new DAL class, the user runs the recipe and just selects which stored procedure(s) they want generated.

Neither package comes with any Visual Studio solution or project templates, and they do not need to be used to create the original solution. Any existing project can make use of the code generation features by enabling the package(s) through Tools…Guidance Package Manager.

In this post I'll give an overview of using the basic Sixeyed.Guidance.CodeGeneration package, and in future posts I'll add some technical detail and give a walkthrough of the sample project.

Add Generated Items

Run the Add generated items recipe from the Guidance Package Manager, or from the context menu of any project in Solution Explorer. The wizard loads to collect settings - in the first page you select the metadata source type, configure the source and select the metadata provider:

During generation, the provider will load each of the selected metadata items and provide them as a property which can be accessed in the T4 template. For instance if you use the SQL Server Stored Procedure provider, your T4 script will have a populated SqlCommand object available to use.

Provided with the basic Guidance package are the following Sources and Providers:

File System
- File source – for using one or more files as metadata
  - XML File provider – for using XML file contents, exposed to the template as an XmlDocument instance
  - Text File provider – for using text file contents, exposed as a string
  - Assembly File provider – for using a .NET assembly, exposed as an Assembly instance
- Directory source – for using a list of directory contents as metadata
  - File List provider – for using a list of file names, exposed as a List<string> instance
  - Directory provider – for using a directory, exposed as a DirectoryInfo instance
Database
- SQL Server Database
  - Query Result provider – for executing a SQL query and exposing the results in a populated DataSet
  - Table provider – for using a table as metadata, exposed as an empty DataTable with the correct structure
  - Stored Procedure provider – for using stored procedures, exposed as a populated SqlCommand object
WSDL
- SOAP source
  - Web Method provider – for using a Web service method, exposed as a MethodInfo object
  - Schema provider – for using the WSDL of the service, exposed as an XmlSchema object

When you select a provider, it will load a list of all available metadata items, and you select which items you want to run the T4 template against:

The item selection is always a simple list displaying the item name – this will be the name of the file, table, Web method etc (an exception is the QueryResult provider which uses this page to capture the SQL query to be executed).

In the final screen, select the T4 template to use:

The file dialog will default to the "Templates" folder of the Guidance package, but you can navigate to any T4 file. If you want to override the output settings from the T4 file, specifying a different target filename, namespace extension or class name you can do it in the additional properties in this step:

Finish the wizard and the recipe will iterate over each of the selected items, populating a representation of the metadata and passing it to the T4 template property.

T4 Template Properties

In order to access metadata item information and create the output, your T4 script needs to specify two properties which will be populated using the Guidance PropertyProcessor engine:

<#@ property processor="PropertyProcessor" name="MetadataItem" #>

<#@ property processor="PropertyProcessor" name="TemplateConfiguration" #>

The MetadataItem property is an object implementing Sixeyed.CodeGeneration.Metadata.Interfaces.IMetadataItem:

The underlying Item property gives you access to the populated metadata item – the object type will depend on the provider, and will be specified in the ItemType property. The Key for the item (the name shown in the Select Items wizard page) is available, as is the metadata Provider which can be used to navigate up to the source.

The TemplateConfiguration property allows you to control the output of the template, setting default values for the target file name etc. (which can be overridden in the Select Template wizard page). It's an object of type Sixeyed.CodeGeneration.Generation.TemplateConfiguration:

Sample Templates

The CodeGeneration.Sample Guidance package contains a sample template for each of the metadata providers, demonstrating the type of object they expose and how it can be used. The scripts don't do much other than demonstrate usage, but there are fully-fledged scripts for generating wrappers for SQL Server stored procedures, and configuration sections from text files. The full script for the Table provider sample makes straightforward use of the underlying DataTable object:

<#@ template language="C#" #>

<#@ property processor="PropertyProcessor" name="MetadataItem" #>

<#@ property processor="PropertyProcessor" name="TemplateConfiguration" #>

<#@ assembly name="System.dll" #>

<#@ assembly name="System.Data.dll" #>

<#@ assembly name="System.Xml.dll" #>

<#@ assembly name="Sixeyed.CodeGeneration.dll" #>

<#@ import namespace="System.Data" #>

<#@ import namespace="Sixeyed.CodeGeneration.Generation" #>

<# PrepareOutput(); #>

Table name (from metadata): <#= MetadataItem.Key #>

Table name (from table): <#= dataTable.TableName #>

Columns:

<# foreach (DataColumn column in dataTable.Columns)

{

#>Column Name: <#= column.ColumnName #>

Data Type: <#= column.DataType #>

<#} #>

<#+

private DataTable dataTable

{

get{ return MetadataItem.Item as DataTable; }

}

private void PrepareOutput()

{

TemplateConfiguration.ClassName = string.Format("Table_{0}", MemberName.ToPascalCase(MetadataItem.Key, true));

TemplateConfiguration.FileExtension = "cs";

}

(If you don't already have it, the T4 Editor Community Edition from Clarius makes editing templates much easier).

The directives specify the expected properties, and import the relevant reference assemblies and namespaces. The script provides the dataTable property to easily access the metadata item as a typed DataTable object. In the PrepareOutput method (called at the start of the template), the script sets up the target class name and file extension. In this case a target filename is not specified, so the engine will use the class name and file extension for the filename. Note there are some helper methods in Sixeyed.CodeGeneration.Generation.MemberName for preparing valid member names.

Selecting a single table called Manufacturers for this script generates and adds a file called Table_Manufacturers.cs to the selected project, containing the following output:

Table name (from metadata): Manufacturers

Table name (from table): Manufacturers

Columns:

Column Name: ManufacturerId

Data Type: System.Int16

Column Name: ManufacturerName

Data Type: System.String

Column Name: AvailableFromDate

Data Type: System.DateTime

Column Name: AvailableToDate

Data Type: System.DateTime

Usage

For ad-hoc code generation, this basic Guidance package lets you specify metadata to execute against a T4 template. For commonly used scripts and standard patterns you can build a custom Guidance package which contains your solution structure, and specific recipes for generating known types of item – for DAL classes, entities, configuration sections, proxies or anything else that is based on external metadata.

Quick registration of Package in progress… This may take a while

EltonStoneman — Tue, 14 Oct 2008 23:33:47 GMT

[Source: http://geekswithblogs.net/EltonStoneman]

The Guidance Automation Extensions Toolkit (see GAX Toolkit) gives you this lovely message when you use the "Quick Register" action in your GAX package development. It's true that it can take a while, although it's substantially quicker than the full registration action.

When you're in development though, solutions using your GAX package will read the contents from the project's bin\Debug, so you may not need to re-register between builds at all. Experiments with registration types suggest that they need to be used in the following situations:

Full Register – needed the first time you register the package, and may be needed following an Unregister if the package has been corrupted or isn't functioning as expected. Takes several minutes and does a variety of interesting things (check Task Manager while it's running); builds the solution and validates package XML before deploying.
Quick Register – may take a while, but usually in the order of tens of seconds rather than minutes. Also builds the solution and validates the package XML, but doesn't do the full suite of registration tasks. Not necessary in normal use, although if you've modified the XML it's worth having it validated before trying to use it.
No registration – in dev, the package is read from bin\Debug, so if you're adding or modifying templates, you can just rebuild and they'll be immediately available. Similarly if you change or add to the code in the project or dependencies, close any solutions using the GAX package and rebuild and the changes will take effect when you re-open. Interestingly, if you modify the XML – e.g. to add a new action – you can also just rebuild and not register, and the new action will be listed when you open a solution using the package. If not, disable then re-enable the package, and the new action should appear.

Obviously this only applies in dev, and if you deploy your GAX package using the MSI, you'll need to redeploy in full for changes to take effect. Useful to know though, and may mean your GAX development takes less of a while.