Overview of Configuration Files

Today, most non-trivial applications use configuration settings. Commercial software products must be able to run in different environments for different users. At the very least that means being able to run from a folder specified by the user during installation. Non-trivial applications often need dozens of settings, including database connection strings, network locations and credentials. These configuration settings can be stored and accessed in a number of different ways. On the Microsoft Windows platforms, we have used INI files, database tables and registry keys. Applications built using the .NET Framework commonly use XML-based configuration files, such as the one shown below.

App.config

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="MySetting" value="MyValue"/>
  </appSettings>
</configuration>

When building a C# or Visual Basic project that contains this configuration file, Visual Studio will copy it to the output directory and rename to match the name of the executable, such as ConsoleApplication.exe.config. The application can access the settings from this file using ConfigurationManager and other classes in the System.Configuration namespace. Here is an example.

using System;
using System.Configuration;

namespace ConsoleApplication
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine(ConfigurationManager.AppSettings["MySetting"]);
            Console.WriteLine("Press any key to close the application …");
            Console.ReadKey();
        }
    }
}

Managing Configuration Settings

Although applications developed by companies for internal use may not need to be as configurable, mature development teams take advantage of configuration settings to run their applications in different environments for development and production purposes so that the application can be modified and tested without affecting the real users. Because internal applications are typically installed and configured by people with technical background who are comfortable with editing the XML-based configuration files, building a robust GUI for configuration settings does not add much business value. However, the task of configuring the application for a particular environment still remains and falls onto the plate of either developers or administrators. When done manually this process is tedious and error-prone.

Multiple .Config Files

Without resorting to writing an installation program or script, one of the options you have is to maintain a separate copy of the application configuration file for each environment. For example, in addition to the App.config shown above which you would use in development environment, you might also have two more configuration files for your test and production environments.

Test.config

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="MySetting" value="MyTestValue"/>
  </appSettings>
</configuration>

Production.config

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="MySetting" value="MyProductionValue"/>
  </appSettings>
</configuration>

When deploying the application to test environment, you would replace the default ConsoleApplication.exe.config with the Test.config, and for production environment you would use the Production.config. The process is simple enough to perform manually and easy to automate with a simple batch script. However, it only works well when the configuration file is small and contains only environment-specific settings, such as database connection strings. As configuration files become larger maintaining the common settings duplicated in each configuration file becomes more and more difficult.

ConfigSource Attribute

To solve this problem, the .NET Framework 2.0 introduced ConfigSource attribute for all configuration sections. Using this attribute we can extract environment-specific sections from the App.config to a separate file.

App.config

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings configSource="AppSettings.config"/>
</configuration>

AppSettings.config

<?xml version="1.0" encoding="utf-8" ?>
<appSettings>
  <add key="MySetting" value="MyValue"/>
</appSettings>

When a section file, such as AppSettings.config, is copied to the output directory, ConfigurationManager will be able to automatically load settings from it instead of the main configuration file, ConsoleApplication.exe.config in our example. To change this configuration for a particular environment, we now only need to replace the section file, AppSettings.config, and not the entire App.config. Here are the environment-specific versions of the section configuration files for our sample project.

AppSettings.Test.config

<?xml version="1.0" encoding="utf-8" ?>
<appSettings>
  <add key="MySetting" value="MyTestValue"/>
</appSettings>

AppSettings.Production.config

<?xml version="1.0" encoding="utf-8" ?>
<appSettings>
  <add key="MySetting" value="MyProductionValue"/>
</appSettings>

Extracting sections into separate files allows us to manage settings at a more granular level. It works well when environment-specific settings are concentrated in a particular section, such as AppSettings or ConnectionStrings. However, once the number of sections that need to be replaced for different environments begins to grow, the section files become more and more difficult to manage.

Web.config File Transformation

Visual Studio 2010 introduced a new solution for managing environment-specific settings in Web application projects – config file transformation. With this approach, your web.config file stores settings required to run the application in your local development environment.

Web.config

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="MySetting" value="Debug Value"/>
  </appSettings>
</configuration>

On the other hand, all settings specific to a particular shared environment (such as test, staging or production) are stored in a separate transformation file.The example below shows a transformation file for the Release environment that changes MySetting defined in the Web.config.

Web.Release.config

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
  <appSettings>
    <add key="MySetting" value="Release Value"
         xdt:Transform="SetAttributes" xdt:Locator="Match(key)"/>
  </appSettings>
</configuration>

Visual Studio updates Web.Config using the transformation file when packaging or publishing the application. You can perform both of these actions from the project’s context menu in Solution Explorer or using MSBuild to build the Package target of the web application project.

msbuild WebApplication.csproj /target:Package /p:Configuration=Release

New web application projects you create in Visual Studio 2010 will have both Debug and Release transform files created automatically. If you have an existing web application project, perhaps upgraded from Visual Studio 2008, you can add transform files to it by right-clicking the web.config in the Solution Explorer and selecting “Add Config Transforms” from the context menu. However, keep in mind that config transformation does not occur during regular build or debugging of the web application project. If Debug configuration represents local development environment, you may want to remove the Web.Debug.config transformation file to avoid confusion.

Transformation file syntax is based on the standard syntax of configuration files, with addition of the xdt attributes, such as Locator, which specifies how to find a particular setting in the original .config file, and Transform, which specifies how to modify it. In our example, the add element will be found in the appSettings section using its key (MySetting); once the original element is found, all of its attributes will be replaced with those specified in the transformation file (SetAttributes). Here is the resulting Web.config after transformation.

Web.config (transformed)

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <appSettings>
    <add key="MySetting" value="Debug Value"/>
  </appSettings>
</configuration>

Unlike the approach based on ConfigSource attribute and separate section files, you only have a single transform file per environment. And because config transformation is integrated in the web application publishing process and allows you to use standard Visual Studio build configurations, such as Debug for development and Release for production, as well as define custom environments, such as Test, as necessary. Configurations/environments can be switched quickly, without leaving Visual Studio or running external tools.

On the flipside, in order to use config transforms you need to learn a new XML-based language that defines the transformations. However, you will typically use a minimum subset of its capabilities and find that, on most internal application projects, the initial effort will be well justified by the simplicity and reduced cost of ongoing maintenance of the environment-specific settings.

App.config File Transformation

Out of the box, .config file transformation is only available for Web application projects in Visual Studio 2010. Console, WinForms, WPF and other applications projects don’t support this capability out of the box. Luckily, you can add it to any Visual Basic or C# project by manually changing the project source file as shown below.

<!– … –>
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

<UsingTask TaskName="TransformXml"
  AssemblyFile="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v10.0\Web\Microsoft.Web.Publishing.Tasks.dll" />

<Target Name="AfterCompile" Condition="exists(’app.$(Configuration).config’)">
  <!– Generate transformed app config in the intermediate directory –>
  <TransformXml Source="app.config"
    Destination="$(IntermediateOutputPath)$(TargetFileName).config"
    Transform="app.$(Configuration).config" />
  <!– Force build process to use the transformed configuration file from now on. –>
  <ItemGroup>
    <AppConfigWithTargetPath Remove="app.config"/>
    <AppConfigWithTargetPath Include="$(IntermediateOutputPath)$(TargetFileName).config">
      <TargetPath>$(TargetFileName).config</TargetPath>
    </AppConfigWithTargetPath>
  </ItemGroup>
</Target>
<!– … –>

In this MSBuild code snippet, we are using the TransformXml task defined in the Microsoft.Web.Publishing.Tasks.dll. This is the task responsible for transforming Web.config files in Web application projects. It takes parameters that specify names of the original .config file, the transform file and the output (transformed) file. We use TransformXml task to override AfterCompile target if a transform file exist for the current build configuration. For example, if our project contains a file called App.Debug.config and the current project configuration is Debug, the AfterCompile target will be called. Finally, we use ItemGroup element to change the built-in AppConfigWithTargetPath item collection. This is necessary in order for the ClickOnce publishing process and the Visual Studio debugging process (vshost.exe) to discover and use the transformed configuration file instead of the original one.

Unlike with Web application projects, you will need to add the transform files to the project manually, following the naming convention of App.<Configuration Name>.config, such as App.Release.config. Also, the transform files will not be automatically nested under the main App.config. To achieve this effect, you can manually edit the project file and specify the DependentUpon attribute for transform files as shown below.

<!– … –>
<ItemGroup>
  <None Include="App.config" />
  <None Include="App.Release.config">
    <DependentUpon>App.config</DependentUpon>
  </None>
</ItemGroup>
<!– … –>

With these changes made, the App.config file will be transformed at build time, using the configuration-specific transformation file you provided. If the transformation file doesn’t exist, the original App.config file will be used. Unlike web applications, which are compiled at run-time by ASP.NET, regular applications are fully compiled by Visual Studio during project build. This also means that config transformation occurs during development build/debug cycle, so if the Debug project configuration represents local environment on each developer’s machine, you could use config transformation for Debug configuration too. However, for consistency with web projects and to reduce confusion for less experienced developers on your team, it may be best to avoid this.

XML File Transformation

Config transformation is not limited to only .NET configuration files. You can transform any valid XML files in Visual Studio projects based on MSBuild, such as Windows Azure Project. This project type comes with Windows Azure tools for Visual Studio and is used to build service packages that describe one or more virtual machines (called roles) and include the compiled applications that will be running on these machines. Each service package is accompanied by a service configuration file, which is typically used to specify connection strings for SQL Azure databases and storage accounts as well as the number of virtual machine instances required for each role.

ServiceConfiguration.cscfg (Production)

<?xml version="1.0" encoding="utf-8"?>
<ServiceConfiguration serviceName="WindowsAzureProject" osFamily="1" osVersion="*"
  xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration">

  <Role name="WebApplication">
    <Instances count="2" />
    <ConfigurationSettings>
      <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString"
        value="DefaultEndpointsProtocol=https;AccountName=…;AccountKey=…" />
    </ConfigurationSettings>
  </Role>

</ServiceConfiguration>

As you might expect, Visual Studio also provides the ability to debug Windows Azure Projects on your local machine, without uploading the service package to the cloud. When running in local development environment, called Dev Fabric, your service package often needs to have different configuration. For example, instead of connecting to a SQL Azure database it would connect to your local SQL Server instance, instead of cloud-based table storage it would write diagnostic logs to the local storage emulator, instead of having 2 or more role instances required for high-availability it would need to run only one to improve debugging experience, and so on. Here is a development version of the service configuration file you might want to use.

ServiceConfiguration.cscfg (Debug)

<?xml version="1.0" encoding="utf-8"?>
<ServiceConfiguration serviceName="WindowsAzureProject" osFamily="1" osVersion="*"
  xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration">
  <Role name="WebApplication">
    <Instances count="1" />
    <ConfigurationSettings>
      <Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString"
        value="UseDevelopmentStorage=true" />
    </ConfigurationSettings>
  </Role>
</ServiceConfiguration>

With a little customization we can get config transformation work for the Windows Azure Projects too. Since Visual Studio doesn’t support config transformation for this type of projects yet, we again need to modify it manually as shown below.

WindowsAzureProject.ccproj

<!– … –>
<Import Project="$(CloudExtensionsDir)Microsoft.CloudService.targets" />

<UsingTask TaskName="TransformXml"
  AssemblyFile="$(MSBuildExtensionsPath32)\Microsoft\VisualStudio\v10.0\Web\Microsoft.Web.Publishing.Tasks.dll" />

<PropertyGroup>
  <ServiceConfigurationTransform>ServiceConfiguration.$(Configuration).cscfg</ServiceConfigurationTransform>
</PropertyGroup>

<Target Name="TransformServiceConfiguration"
  BeforeTargets="CopyServiceDefinitionAndConfiguration"
  Condition="exists(’$(ServiceConfigurationTransform)’)">

  <!– Generate transformed service config in the intermediate directory –>
  <TransformXml Source="@(ServiceConfiguration)"
    Destination="$(IntermediateOutputPath)%(Filename)%(Extension)"
    Transform="$(ServiceConfigurationTransform)" />

  <!– Force build process to use the transformed configuration file from now on. –>
  <ItemGroup>
    <ServiceConfiguration Remove="ServiceConfiguration.cscfg" />
    <ServiceConfiguration Include="$(IntermediateOutputPath)ServiceConfiguration.cscfg" />
  </ItemGroup>
</Target>
<!– … –>

Just like with the console application we customized previously, we use the TransformXml MSBuild task defined in the Microsoft.Web.Publishing.Tasks.dll to transform the service configuration file in a custom target called TransformServiceConfiguration that will be executed before the built-in CopyServiceDefinitionAndConfiguration. One the transformed configuration file is generated in the intermediate (obj) output directory, we force the build process to use it instead of the original one.

WindowsAzureProject.ccproj

<!– Items for the project –>
<ItemGroup>
  <ServiceDefinition Include="ServiceDefinition.csdef" />
  <ServiceConfiguration Include="ServiceConfiguration.cscfg" />
  <None Include="ServiceConfiguration.Release.cscfg"/>
</ItemGroup>

We also need to add the transform file to our project by manually changing the project file as shown above. Unlike C# and VB projects, Windows Azure Projects in the 1.3 version of the Azure Tools for Visual Studio don’t support the DependentUpon metadata and we can’t make the transform files nested under the configuration file in Solution Explorer. Here is the transformation file that changes our debug version of the service configuration to match the production version shown above.

ServiceConfiguration.Release.cscfg

<?xml version="1.0" encoding="utf-8"?>
<sc:ServiceConfiguration
  xmlns:sc="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceConfiguration"
  xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">

  <sc:Role name="WebApplication" xdt:Locator="Match(name)">
    <sc:Instances count="2" xdt:Transform="SetAttributes"/>
    <sc:ConfigurationSettings>
      <sc:Setting name="Microsoft.WindowsAzure.Plugins.Diagnostics.ConnectionString"
        value="DefaultEndpointsProtocol=https;AccountName=youraccount;AccountKey=yourkey"
        xdt:Transform="SetAttributes" xdt:Locator="Match(name)"/>
    </sc:ConfigurationSettings>
  </sc:Role>
</sc:ServiceConfiguration>

In this file we change the number of instances required for our web application to 2 and replace the diagnostics connection string with a string pointing to a Windows Azure storage account.

Notice that we explicitly qualify the service configuration namespace in this transform file. This is necessary in order for the current version of the TransformXml task to correctly recognize and match elements in the transform file to the elements in the original XML file.

Conclusion

Config file transformation offers an effective solution for managing environment-specific configuration settings for internal applications. Compared to other approaches, such as maintaining environment-specific configuration files and section files, config transformation has the advantage of a single file per environment with minimum duplication of common settings. Although this approach comes at the cost of having to use a new XML-based language to define transformations, its integration into the Visual Studio build process and simplicity of ongoing use make it very attractive for internal application development. Although it is only available in Visual Studio 2010 for Web application projects, other project types can be easily customized to take advantage of this functionality.

Just like its alternatives discussed in this article, config file transformation requires environment-specific configuration information to be stored in source control, with the rest of the application source code. Any sensitive information, such as user names and passwords embedded in connection strings or other settings, will be visible to all developers who have access to the source control repository. In order to avoid putting production systems at risk, your first choice should be to use authentication mechanisms, such as Integrated Windows Authentication, that don’t rely on storing secrets such as passwords in the configuration settings. If this is not an option, the next choice is to encrypt the configuration settings as described here. Editing the configuration files manually on each deployment can also be done as a last resort when the organization’s IT policy prevents developers from accessing production environment and from storing production configuration in source control. In such cases config transformation can still be used for continuous deployment to development and test environments the team has access to.

Because config file transformation occurs at build time, as opposed to installation or run-time, it cannot be used for shrink-wrapped software products that will be installed and configured by end-users. For such applications, having a robust and well documented installation and configuration program is still the best option.

Download

• Source Code

©2012 Oleg Sych. All Rights Reserved.

Overview of Entity Templates

In version 4.0 of ASP.NET Dynamic Data, entity templates are responsible for displaying data from a single entity (i.e. data row) in a FormView. The screenshots below show the Insert, Edit and Details pages with parts generated by the the entity templates outlined in red.

Here is how the default Details.aspx page template uses the read-only Details entity template.

<asp:FormView runat="server" ID="FormView1"
  DataSourceID="DetailsDataSource">
  <ItemTemplate>
    <table>
      <asp:DynamicEntity runat="server" />
      <tr>
        <td>
          <asp:DynamicHyperLink runat="server"
            Action="Edit" Text="Edit" />
          <asp:LinkButton runat="server"
            CommandName="Delete" Text="Delete"/>
        </td>
      </tr>
    </table>
  </ItemTemplate>
</asp:FormView>

Notice the DynamicEntity control in the middle of the FormView above. During the load stage of the ASP.NET page lifecycle, DynamicEntity control finds the appropriate user control in the EntityTemplates folder of the Dynamic Data application and dynamically creates it to provide entity-specific portion of the page.

Here is how the default entity template (EntityTemplates\Default.ascx) user control is implemented.

<%@ Control Language="C#" CodeBehind="Default.ascx.cs"
  Inherits="DynamicDataDemo.DefaultEntityTemplate" %>
<asp:EntityTemplate runat="server" ID="EntityTemplate1">
  <ItemTemplate>
    <tr>
      <td>
        <asp:Label runat="server" OnInit="Label_Init" />
      </td>
      <td>
        <asp:DynamicControl runat="server"
          OnInit="DynamicControl_Init" />
      </td>
    </tr>
  </ItemTemplate>
</asp:EntityTemplate>

This user control inherits from the EntityTemplateUserControl class provided by Dynamic Data. This base class provides access to several properties worth mentioning, such as Table, which gives you the MetaTable describing the current entity, and Mode, which determines whether the entity should be displayed in edit, insert or read-only mode. The EntityTemplate control, provided by Dynamic Data, is essentially a repeater that our entity template user control uses to generate HTML for each property of the current entity. DynamicControl, also provided by Dynamic Data, dynamically loads a field template appropriate for the current property, based on its type and attributes. All that is needed is a little bit of code (shown below) to wire up the controls.

using System;
using System.Collections.Generic;
using System.Web.DynamicData;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace DynamicDataDemo
{
    public partial class DefaultEntityTemplate
        : EntityTemplateUserControl
    {
        private MetaColumn currentColumn;

        protected override void OnLoad(EventArgs e)
        {
            IEnumerable<MetaColumn> columns =
                this.Table.GetScaffoldColumns(
                    this.Mode, this.ContainerType);

            foreach (MetaColumn column in columns)
            {
                this.currentColumn = column;

                Control item = new _NamingContainer();
                this.entityTemplate.ItemTemplate.InstantiateIn(item);
                this.entityTemplate.Controls.Add(item);
            }
        }

        protected void DynamicControl_Init(object sender, EventArgs e)
        {
            DynamicControl dynamicControl = (DynamicControl)sender;
            dynamicControl.DataField = this.currentColumn.Name;
        }

        protected void Label_Init(object sender, EventArgs e)
        {
            Label label = (Label)sender;
            label.Text = this.currentColumn.DisplayName;
        }

        public class _NamingContainer : Control, INamingContainer { }
    }
}

Most of the magic happens in the OnLoad method of the user control. To determine which controls to display, it calls the GetScaffoldColumns method of the MetaTable class. This method returns a list of MetaColumn objects, each describing a single property of our entity, including property’s Name and DisplayName. Having obtained the list of MetaColumns, the OnLoad method instantiates the EntityTemplate for each column to generate the controls. Essentially, this code implements a form of the templated user control, a well established ASP.NET pattern.

The rest of the magic is done by the DynamicControl instances generated for each column. As you can see in the DynamicControl_Init method, we initialize its DataField property with the name of the current MetaColumn. During the load stage, DynamicControl will automatically find an appropriate field template and include it in the page as described here.

Entity Template Scaffolding

Out of the box, Dynamic Data provides three entity templates called Default, Default_Insert and Default_Edit. The Default entity template is used by the Details page and the Default_Insert and Default_Edit entity templates are used by the Insert and Edit pages respectively.

The entity template user controls follow a specific naming convention:

{Name}.ascx

{Name}_{Mode}.ascx

• Name is the name of a MetaTable or the UIHint that can be specified explicitly on the DynamicEntity control. Typically, this will be the name of a MetaTable, which will match the name of the property generated in your context class you would normally use to access the data, such as Products or Customers. However, if you use inheritance in your data model, table name will match the class name for derived entity types and will typically have singular form, such as Customer.
• Mode can be either Edit or Insert. An entity template that doesn’t include mode in its name is assumed to be a ReadOnly template.

During the load stage of control lifecycle, the DynamicEntity control uses EntityTemplateFactory of the default MetaModel to find and create a matching entity template user control. The factory will first try the most specific name, such as Products_Insert.ascx. If a file with this name does not exist, it will try changing the name and the mode portions of the file name until it locates the first suitable match. The table below shows the order used by the EntityTemplateFactory to find entity templates.

Creating a Custom Entity Template

If you are not satisfied with the single-column layout that default entity templates produce, you can create a custom entity template by creating a special user control with the name that matches your the name of your entity and the mode of your page and placing it in the EntityTemplates folder of your Dynamic Data web project. The screenshot on the right shows output produced by the Details.aspx page using a custom Products.ascx entity template. Again, output of the entity template is outlined in red.

Here is the implementation of the EntityTemplates\Products.ascx (without the formatting attributes, which were removed for clarity).

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="Products.ascx.cs"
Inherits="DynamicDataDemo.DynamicData.EntityTemplates.ProductsEntityTemplate" %>

<tr>
  <td>
    <table>
      <tr>
        <td>Name</td>
        <td>
          <asp:DynamicControl runat="server" DataField="ProductName"
            OnInit="DynamicControl_Init"/>
        </td>
      </tr>
      <tr>
        <td>Category</td>
        <td>
          <asp:DynamicControl runat="server" DataField="Category"
            OnInit="DynamicControl_Init"/>
        </td>
      </tr>
    </table>
  </td>
  <td>
    <table>
      <tr>
        <td>Supplier</td>
        <td>
          <asp:DynamicControl runat="server" DataField="Supplier"
            OnInit="DynamicControl_Init"/>
        </td>
      </tr>
      <tr>
        <td>Units in stock</td>
        <td>
          <asp:DynamicControl runat="server" DataField="UnitsInStock"
            OnInit="DynamicControl_Init"/>
        </td>
      </tr>
    </table>
  </td>
</tr>

Notice that we use DynamicControl instances to dynamically generate appropriate field templates for the properties we want to see – ProductName, Category, Supplier and UnitsInStock. For ProductName, DynamicControl will choose the Text.ascx field template, which will produce plain text output, but for the foreign key columns, Category and Supplier, it will choose the ForeignKey.ascx field template, which will produce hyperlinks to the dynamic Details.aspx pages for the Category and Supplier entities respectively.

Our custom entity template defines the required layout for the Product entity, without re-implementing any of the field presentation logic. This power becomes even more apparent in Insert and Edit pages (shown below). The editable versions of the field templates make extensive use of not only web controls, but also client- and server-side validators. Although this logic would be easy to implement by copy-and-paste initially, consistently maintaining it across different custom pages and controls quickly becomes a serious maintenance challenge. Thanks to the DynamicControl we can maintain this logic in a single place – the field templates and reuse it in the custom entity templates without incurring the penalty of code duplication.

In order to make the field templates work correctly in Edit and Insert mode, we need to dynamically initialize the Mode property for each DynamicControl in the template. This is done in the DynamicControl_Init method defined in the code-behind. During the initialization stage of control lifecycle, DynamicControl passes this value to the FieldTemplateFactory to locate and dynamically create the editable versions of the field templates.

using System;
using System.Web.DynamicData;

namespace DynamicDataDemo.DynamicData.EntityTemplates
{
    public partial class ProductsEntityTemplate : EntityTemplateUserControl
    {
        protected void DynamicControl_Init(object sender, EventArgs e)
        {
            DynamicControl dynamicControl = (DynamicControl)sender;
            dynamicControl.Mode = this.Mode;
        }
    }
}

Improving Default Entity Templates

Unfortunately, our Products.ascx cannot be used by the Edit.aspx page template immediately. In Edit mode, without an entity template called Products_Edit.ascx, the EntityTemplateFactory will try Default_Edit.ascx before it tries the Products.ascx. In order to make a custom entity template for Edit and Insert mode, we would need to save a copy of Products.ascx as Products_Edit.ascx. This last template would be reused by both Edit.aspx and Insert.aspx because the EntityTemplateFactory assumes that edit-mode entity templates can be used in insert mode as well.

Having two identical copies of the same code is not ideal and will quickly get out of hand as the number of custom entity templates grows. Your first attempt to solve the code duplication problem might be to extract this code into a user control, such as ProductsTemplate.ascx, and reuse it in both Products.ascx and Products_Edit.ascx. This approach works, but you end up with even more files in your project, three user controls for each entity that needs a custom template, all in order to work around the logic the EntityTemplateFactory uses to resolve entity templates. There has to be a better way!

Taking a closer look at the Default.aspx, Default_Edit.ascx and Default_Insert.ascx entity templates provided by the Dynamic Data, you will notice that these user controls are very similar. We can easily combine their logic into the Default.ascx and delete the Default_Edit.ascx and Default_Insert.ascx. This will not only eliminate the code duplication in the default entity templates; it will also eliminate the need to duplicate code or create multiple files for custom entity templates as well.

Here is what the new Default.ascx looks like without formatting attributes.

<%@ Control Language="C#" CodeBehind="Default.ascx.cs"
  Inherits="DynamicDataDemo.DefaultEntityTemplate" %>
<asp:EntityTemplate runat="server" ID="entityTemplate">
  <ItemTemplate>
    <tr>
      <td>
        <asp:Label runat="server" OnInit="Label_Init"
          OnPreRender="Label_PreRender" />
      </td>
      <td>
        <asp:DynamicControl ID="dynamicControl"
          runat="server" OnInit="DynamicControl_Init" />
      </td>
    </tr>
  </ItemTemplate>
</asp:EntityTemplate>

Note the addition of the OnPreRender event handler for the Label control. The Label_PreRender method associates the label with the dynamically generated DataControl. Another important difference is how the Mode property of the DynamicControl is initialized. In the templates supplied by Dynamic Data, this is done in the control markup. In our new template this is done dynamically, in the DynamicControl_Init method, which initializes it based on the Mode of the entity template itself.

Here is the new code-behind file, Default.ascx.cs.

using System;
using System.Collections.Generic;
using System.Web.DynamicData;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace DynamicDataDemo
{
    public partial class DefaultEntityTemplate
        : EntityTemplateUserControl
    {
        private MetaColumn currentColumn;

        protected override void OnLoad(EventArgs e)
        {
            IEnumerable<MetaColumn> columns =
                this.Table.GetScaffoldColumns(
                    this.Mode, this.ContainerType);

            foreach (MetaColumn column in columns)
            {
                this.currentColumn = column;

                Control item = new _NamingContainer();
                this.entityTemplate.ItemTemplate.InstantiateIn(item);
                this.entityTemplate.Controls.Add(item);
            }
        }

        protected void DynamicControl_Init(object sender, EventArgs e)
        {
            DynamicControl dynamicControl = (DynamicControl)sender;
            dynamicControl.DataField = this.currentColumn.Name;
            dynamicControl.Mode = this.Mode;
        }

        protected void Label_Init(object sender, EventArgs e)
        {
            Label label = (Label)sender;
            label.Text = this.currentColumn.DisplayName;
        }

        protected void Label_PreRender(object sender, EventArgs e)
        {
            Label label = (Label)sender;

            DynamicControl dynamicControl =
                (DynamicControl)label.FindControl("dynamicControl");

            FieldTemplateUserControl fieldTemplate =
                dynamicControl.FieldTemplate as FieldTemplateUserControl;

            if (fieldTemplate != null && fieldTemplate.DataControl != null)
            {
                label.AssociatedControlID =
                    fieldTemplate.DataControl.GetUniqueIDRelativeTo(label);
            }
        }

        public class _NamingContainer : Control, INamingContainer { }
    }
}

Closing Thoughts

Entity templates are a very powerful addition to the ASP.NET Dynamic Data. A single default entity template user control can define the form layout for all entity types in your model in three different modes – ReadOnly (Details.aspx), Insert (Insert.aspx) and Edit (Edit.aspx). A custom entity template can be quickly created to replace the standard single-column form layout with a required custom layout, which again, can be reused in all three different modes. This power truly shines in Insert and Edit pages, where entity templates give you the ability to modify the form layout logic completely independently from the data entry and validation logic encapsulated by the field templates. While the default entity templates supplied by the Dynamic Data project are mode-specific and encourage code duplication, you can easily combine them into a single entity template and eliminate the need to create mode-specific custom entity templates as well.

Download

Source Code.

©2012 Oleg Sych. All Rights Reserved.

This screen contains controls for all columns of the Order table for which Dynamic Data can generate filter controls. This includes controls for boolean, enumeration and foreign key columns the framework provides out of the box, as well as the custom filter control for DateTime columns we have added to the application. Although in this example we still don’t have filter controls for other common data types, such as string and numeric columns, implementing them is very straightforward and similar to the implementation of our DateTimeFilter. The real limitation here is that we cannot search the Order table using filters based on related tables. For example, what if we need to give the users of our application the ability to search for orders placed by customers in a particular state or zip code? The short answer is that Dynamic Data doesn’t support filtering based on data in related tables. However, it is possible to make it cooperate. Here is the long answer…

The Approach

As usual with Dynamic Data, it is helpful to first work through a particular scenario using the traditional, static code. If we were to build a search screen for the Orders table using regular ASP.NET controls and the ADO.NET Entity Framework, we would create a page with text boxes, drop-down lists and other controls for users to enter search criteria and use LINQ to Entities to filter the query results, like so.

using (NorthwindEntities context = new NorthwindEntities())
{
    var query = from o in context.Orders
                where o.Customer.PostalCode == "33609"
                select o;
    Order[] results = query.ToArray();
}

Of course, this would not work very well if our page allowed a number of different criteria to be specified for the Customer (parent) table as well as for the Order (child) table. Let’s say that we have a dozen different filter controls on our search page for the user to choose from, but they only need to find orders placed by Customers with zip code 33609 and shipped to Ukraine. We would probably change the code to look more like this.

using (NorthwindEntities context = new NorthwindEntities())
{
    IQueryable<Customer> parentQuery = context.Customers;
    if (custZip.Text != string.Empty)
        parentQuery = parentQuery.Where(c => c.PostalCode == custZip.Text);
    if (custCountry.Text != string.Empty)
        parentQuery = parentQuery.Where(c => c.Country == custCountry.Text);

    IQueryable<Order> childQuery = context.Orders;
    if (shipZip.Text != string.Empty)
        childQuery = childQuery.Where(o => o.ShipPostalCode == shipZip.Text);
    if (shipCountry.Text != string.Empty)
        childQuery = childQuery.Where(o => o.ShipCountry == shipCountry.Text);

    var query = from customer in parentQuery
                join order in childQuery
                on customer.CustomerID equals order.CustomerID
                select order;

    Order[] results = query.ToArray();
}

This way we can check each of our filter controls and generate Where calls for the parent, Customers table, and for the child, Orders table, and then join the two queries to get the list of orders that meet the combined criteria. This approach takes advantage of the Where call chaining that ADO.NET Entity Framework and LINQ to SQL convert into individual conditions in the Where clause of SQL Select statement. Here is what the SQL query generated by this code would look like.

select Customers.*
from Customers
inner join Orders
on Orders.CustomerID = Customers.CustomerID
where Customers.PostalCode = ‘33609′
  and Orders.ShipCountry = ‘Ukraine’

Essentially, this is the same way the QueryableFilterRepeater control works in the List.aspx page template. It generates DynamicFilters for all columns that can be filtered in a table and calls their GetQueryable method allowing them to modify the search query based on the values entered in their filter controls.

<asp:QueryableFilterRepeater runat="server" ID="FilterRepeater">
  <ItemTemplate>
    <asp:Label runat="server" Text=’<%# Eval("DisplayName") %>‘
      OnPreRender="Label_PreRender" />
    <asp:DynamicFilter runat="server" ID="DynamicFilter"
      OnFilterChanged="DynamicFilter_FilterChanged" />
    <br />
  </ItemTemplate>
</asp:QueryableFilterRepeater>

What if we simply take this markup and its supporting code, put it in a new filter control, similar to the DateTime.aspx we created previously and implement its GetQueryable method  to do the join? Unfortunately, this straightforward approach doesn’t work in the 4.0 version of ASP.NET Dynamic Data.

The Problem

The reason this approach doesn’t work in the current version of ASP.NET Dynamic Data lies in the implementation of the QueryableFilterRepeater and DynamicFilter classes. The first stumbling block you would hit trying to make this work is how do you tell the QueryableFilterRepeater control that you want it to generate controls for a parent (Customer) table instead of the main (Order) table for which the page is generated? There are no public properties or methods that you could use to specify this information directly on these classes. The only way the framework provides is the DynamicDataManager, which requires you to create a data-bound control, such as a GridView or a FormView; associate it with the data manager; create a data source control, such as an EntityDataSource or a LinqDataSource; associate it with the data-bound control; create a QueryExtender control; associate it with the data source control; finally add a DynamicFilterExpression and associate it with the QueryableFilterRepeater.

Even if you get all this right, this is still not going to work in a filter control. The current implementation of the DynamicDataManager, QueryableFilterRepeater and DynamicFilter classes perform all of their dynamic control generation logic in Page.InitComplete event handlers. Unlike the Control.Init and Control.Load events, the page events are not automatically replayed for controls generated dynamically. When our custom filter control is initialized, the Page.InitComplete event has already fired, so no matter what we do, our DynamicDataManager, QueryableFilterRepeater and DynamicFilter simply will not initialize and will not work.

Why the ASP.NET team chose to use the Page.InitComplete event as opposed to Control.Init or Control.Load to implement filtering capabilities in Dynamic Data is beyond my understanding. If you do, please share your knowledge by posting a comment on this page; otherwise, consider voting on Microsoft connect to have this problem fixed.

The Workaround

Instead of relying on the built-in QueryableFilterRepeater and DynamicFilter controls, we can use the non-dynamic Repeater and PlaceHolder controls and directly access MetaModel.FilterFactory to dynamically create the appropriate QueryableFilterUserControl instances. Here is how the markup for our custom filter control could look.

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="ParentTable.ascx.cs"
  Inherits="DynamicDataDemo.ParentTableFilter" %>
<asp:Repeater ID="repeater" runat="server">
  <ItemTemplate>
    <asp:Label ID="label" runat="server" Text=’<%# Eval("DisplayName") %>‘/>
    <asp:PlaceHolder ID="placeHolder" runat="server"
      OnDataBinding="PlaceHolder_DataBinding"/>
    <br />
  </ItemTemplate>
</asp:Repeater>
<asp:EntityDataSource ID="parentDataSource" runat="server" />

Notice that we have an EntityDataSource control for the parent table. This control will not be used to query the database, only to access the metadata.

In the code-behind, we get the MetaTable instance that describes our parent table (i.e. Customer), initialize the parent data source control and bind the repeater to the list of parent columns that can be filtered. 

protected override void OnInit(EventArgs e)
{
    base.OnInit(e);

    var foreignKeyColumn = (MetaForeignKeyColumn)this.Column;
    MetaTable parentTable = foreignKeyColumn.ParentTable;

    parentDataSource.ContextType = parentTable.DataContextType;
    parentDataSource.EntitySetName = parentTable.DataContextPropertyName;

    this.repeater.DataSource = parentTable.GetFilteredColumns();
    this.repeater.DataBind();

    this.EntityDataSource.ContextCreated += this.EntityDataSource_ContextCreated;
}

The actual code that creates appropriate filter controls is located in the DataBinding event handler of the PlaceHolder control. This is where we use the Dynamic Data FilterFactory to create and initialize a new QueryableFilterUserControl and add it to the place holder.

protected void PlaceHolder_DataBinding(object sender, EventArgs e)
{
    FilterFactory filterFactory = this.Column.Model.FilterFactory;
    MetaColumn filterColumn = (MetaColumn)this.Page.GetDataItem();

    var control = (ExtendedFilterUserControl)filterFactory
        .CreateFilterControl(filterColumn, string.Empty);
    control.Initialize(filterColumn, this.parentDataSource, null);
    control.FilterChanged += delegate { this.OnFilterChanged(); };
    this.filterControls.Add(control);

    PlaceHolder placeHolder = (PlaceHolder)sender;
    placeHolder.Controls.Add(control);

    Label label = (Label)placeHolder.FindControl("label");
    label.Text = filterColumn.DisplayName;
    if (control.FilterControl != null)
    {
        label.AssociatedControlID = control.FilterControl
            .GetUniqueIDRelativeTo(label);
    }
}

If you are reading this code carefully, you will notice that we are actually using a custom class called ExtendedFilterUserControl. That is because QueryableFilterUserControl class does not provide any public means to associate it with a particular column and a data source. To work around this limitation, we need to subclass the QueryableFilterUserControl and make its internal Initialize method publically available. We also need to expose its internal QueryableDataSource property in order to generate LINQ join queries later.

public abstract class ExtendedFilterUserControl : QueryableFilterUserControl
{
    private static readonly MethodInfo initializeMethod =
        typeof(System.Web.DynamicData.QueryableFilterUserControl)
        .GetMethod("Initialize",
            BindingFlags.Instance | BindingFlags.NonPublic);

    private static readonly PropertyInfo dataSourceProperty =
        typeof(System.Web.DynamicData.QueryableFilterUserControl)
        .GetProperty("QueryableDataSource",
            BindingFlags.Instance | BindingFlags.NonPublic);

    protected EntityDataSource EntityDataSource
    {
        get
        {
            return (EntityDataSource)dataSourceProperty.GetValue(this, null);
        }
    }

    public void Initialize(MetaColumn metaColumn,
        IQueryableDataSource dataSource, HttpContextBase httpContext)
    {
        initializeMethod.Invoke(this,
            new object[] { metaColumn, dataSource, httpContext });
    }
}

This code uses reflection to access internal members of the QueryableFilterUserControl base class. This requires for the Dynamic Data application to be deployed with full trust, which increases security vulnerability of the web server and may not be possible in shared hosting environment. In order to take advantage of this new base class, we need to change all filter controls in the DynamicData\Filters folder of our project to inherit from ExtendedFilterUserControl.

Generating Joins Dynamically

If you remember, this is what an example of a static join query looked like with LINQ syntax.

using (NorthwindEntities context = new NorthwindEntities())
{
    IQueryable<Customer> parentQuery = context.Customers;
    // generate where calls for parent query …

    IQueryable<Order> childQuery = context.Orders;
    // generate where calls for child query …

    var query = from customer in parentQuery
                join order in childQuery
                on customer.CustomerID equals order.CustomerID
                select order;

    Order[] results = query.ToArray();
}

However, we will need to generate joins dynamically, using LINQ expressions, which first requires us to understand how to implement joins using LINQ extension methods. Here is the same query implemented using the Join extension method.

using (NorthwindEntities context = new NorthwindEntities())
{
    IQueryable<Customer> parentQuery = context.Customers;
    // generate where calls for parent query …

    IQueryable<Order> childQuery = context.Orders;
    // generate where calls for child query …

    IQueryable<Order> query = parentQuery
        .Join(childQuery,
            customer => customer.CustomerID,
            order => order.CustomerID,
            (customer, order) => order);

    Order[] results = query.ToArray();
}

Note that the on/equals clause of the LINQ join operator generates two lambda expressions called “key selectors”. A key selector takes an entity object, such as Customer, as a parameter and returns a “key value” that will be used to join the tables, such as CustomerID. The select clause of the LINQ join operator generates a lambda expression called “result selector”. A result selector takes two entities returned by the join and returns the entity that will be returned by the query, which in this case is Order.

This Join call is exactly what we need to generate dynamically in the GetQueryable method of our custom filter control.

private ObjectContext objectContext;
private List<ExtendedFilterUserControl> filterControls;

public override IQueryable GetQueryable(IQueryable sourceQuery)
{
    // Generate query against the parent table
    var foreignKeyColumn = (MetaForeignKeyColumn)this.Column;
    MetaTable parentTable = foreignKeyColumn.ParentTable;
    IQueryable parentQuery = parentTable.GetQuery(this.objectContext);
    IQueryable emptyParentQuery = parentQuery;
    foreach (var filterControl in this.filterControls)
    {
        parentQuery = filterControl.GetQueryable(parentQuery);
    }

    if (parentQuery != emptyParentQuery)
    {
        // Join the parent query with the main (child) query
        string primaryKeyColumnName = parentTable.PrimaryKeyColumns[0].Name;
        string foreignKeyColumnName = foreignKeyColumn.ForeignKeyNames[0];

        MethodCallExpression joinCall = Expression.Call(
            typeof(Queryable),
            "Join",
            new Type[] {
                    parentQuery.ElementType,
                    sourceQuery.ElementType,
                    this.Column.Table.GetColumn(foreignKeyColumnName).ColumnType,
                    sourceQuery.ElementType
                },
            new Expression[] {
                    parentQuery.Expression,
                    sourceQuery.Expression,
                    BuildKeySelector(parentQuery, primaryKeyColumnName),
                    BuildKeySelector(sourceQuery, foreignKeyColumnName),
                    BuildResultSelector(parentQuery, sourceQuery)
                }
        );
        sourceQuery = sourceQuery.Provider.CreateQuery(joinCall);
    }

    return sourceQuery;
}

In the GetQueryable method, we use MetaTable class to create an empty parent query; iterate through the list of the filter controls and call their GetQueryable methods to allow them to add their Where calls to the query. We then check the parent query to see if it was modified by any of the filter controls. If none of them modified the original parent query, i.e. if user has not entered any filter criteria for the parent table, we don’t have to do anything with the child (source) query. In fact, we don’t to modify the child query in this case because without parent filter criteria, we would only introduce an unnecessary join and reduce query performance.

Note that we pass an ObjectContext to the GetQuery method of the parent MetaTable. In a LINQ Join, both queries must come from the same ObjectContext (in LINQ to Entities) or DataContext (in LINQ to SQL). We can get the right context using the ContextCreated event of the EntityDataSource or the LinqDataSource control used to perform the query.

private ObjectContext objectContext;

protected override void OnInit(EventArgs e)
{
    base.OnInit(e);

    // …rest of the code… 

    this.EntityDataSource.ContextCreated += this.EntityDataSource_ContextCreated;
}

private void EntityDataSource_ContextCreated(object sender,
    EntityDataSourceContextCreatedEventArgs e)
{
    this.objectContext = e.Context;
}

And that is why we need to expose the internal QueryableDataSource property of QueryableFilterUserControl in our ExtendedFilterUserControl as shown above.

The code for BuildKeySelector and BuildResultSelector is relatively straightforward. The only counter-intuitive part you need to be aware of is that Expression.Lambda takes the body expression as it’s first parameter, followed by the parameter expressions.

private static LambdaExpression BuildKeySelector(IQueryable query,
    string columnName)
{
    var parameter = Expression.Parameter(query.ElementType);
    var property = Expression.Property(parameter, columnName);
    var selector = Expression.Lambda(property, parameter);
    return selector;
}

private static LambdaExpression BuildResultSelector(IQueryable parentQuery,
    IQueryable sourceQuery)
{
    var sourceParameter = Expression.Parameter(sourceQuery.ElementType);
    var parentParameter = Expression.Parameter(parentQuery.ElementType);
    var selector = Expression.Lambda(sourceParameter,
        parentParameter, sourceParameter);
    return selector;
}

The Result

Similar to other filter controls, all we need to do in order to take advantage of the new filter control is to apply a FilterUIHint to the appropriate foreign key columns in the model.

[MetadataType(typeof(OrderDetail.Metadata))]
public partial class OrderDetail
{
    public class Metadata
    {
        [FilterUIHint("ParentTable")]
        public object Order;
    }
}

Here is the search screen generated for the OrderDetail table before (left) and after (right) adding the FilterUIHint to the Order column.

As you can see, instead of a single drop-down list for selecting a single order, we now have a set of filter controls based on the columns of the parent (Order) table, including the custom DateTimeFilter controls we have implemented in the previous article. Obviously, there are several cosmetic problems, such as an orphaned “Order” label and a blank space between the parent table filter controls and the rest of the child table controls. We also don’t have the original ForeignKey filter control that was generated for the Order column before. For smaller reference tables, it may be beneficial to have the original foreign key filter in addition to the new parent filter controls, giving you the best of both worlds.

Fixing these problems is outside of scope of this article and is left as an exercise for the reader (tip: take a look at FilterUIHintAttribute.ControlParameters as one possible solution).

Download

Source Code 
See DynamicData\ExtendedFilterUserControl.cs and DynamicData\Filters\ParentTable.ascx.

©2012 Oleg Sych. All Rights Reserved.

Queryable Data Sources

Dynamic Data relies on LINQ and deferred query execution for filtering. Here is how we might go about filtering the list of orders in the Northwind sample database to return only those placed after a given date using static code and the ADO.NET Entity Framework.

NorthwindEntities context = new NorthwindEntities();
IQueryable<Order> query = context.Orders;
query = query.Where(order => order.OrderDate > new DateTime(1996, 7, 15));
Order[] orders = query.ToArray();

In line two of this example, we create a deferred query object that, when executed, would return all orders from the database. In line three, we replace the original query with a new one, which has a where clause to filter the orders based on the order date. Up until now, the query is stored in a form of a LINQ Expression tree in memory of the executing program. Only in line four the ADO.NET Entity Framework transforms the query into a SQL SELECT statement and sends it to the database for execution. Once the response comes back from the database, the Entity Framework uses the returned data to create an array of Order objects.

Deferred query execution allows us to add practically any number of filters to the original query before it is sent to the database. Dynamic Data takes advantage of this powerful capability using the extensibility mechanisms built into the LINQ-based data source classes of ASP.NET 4.0 – LinqDataSource and EntityDataSource.

Both of these classes implement the IQueryableDataSource interface which exposes the QueryCreated event. A queryable data source object raises this event after it has created the original LINQ query, before sending it to the database. QueryCreated event handlers receive a QueryCreatedEventArgs object which allows you to replace the original the original Query, similar to how the code in line three of our example does.

To allow creating filters declaratively, using page markup, ASP.NET also provides a control called QueryExtender. QueryExtender is typically placed on a page and linked to a data source using TargetControlID property. Under the hood, the control handles the data source’s QueryCreated event and uses its own collection of DataSourceExpression objects to modify the query.

<asp:EntityDataSource ID=”dataSource” runat=”server” />
<asp:QueryExtender TargetControlID=”dataSource” ID=”queryExtender” runat=”server”>
    <asp:DynamicFilterExpression ControlID=”filterRepeater” />
</asp:QueryExtender>

DataSourceExpression defines an abstract method called GetQueryable. QueryExtender passes the original query to GetQueryable of first DataSourceExpression, takes the query it returns and passes it to the second DataSourceExpression, and so on, giving each expression the chance to modify the original query by adding a filter, changing its sort order, etc.

Dynamic Filters

DynamicFilterExpression inherits from the DataSourceExpression and overrides its GetQueryable method to take advantage of rich filter templating capabilities provided by the ASP.NET Dynamic Data. Using ControlID property, DynamicFilterExpression is typically associated with a QueryableFilterRepeater, another Dynamic Data control.

<asp:QueryableFilterRepeater runat=”server” ID=”FilterRepeater”>
  <ItemTemplate>
    <asp:Label runat=”server” Text=’<%# Eval(”DisplayName”) %>‘
      OnPreRender=”Label_PreRender” />
    <asp:DynamicFilter runat=”server” ID=”DynamicFilter”
      OnFilterChanged=”DynamicFilter_FilterChanged” />
    <br />
  </ItemTemplate>
</asp:QueryableFilterRepeater>

QueryableFilterRepeater is a templated control, similar to the standard Repeater. It generates a DynamicFilter for each column in the queryable data source that can be filtered by Dynamic Data.

DynamicFilter control uses the filter scaffolding functionality of Dynamic Data to locate and load an appropriate user control from the ~/DynamicData/Filters folder of the web application. These user controls inherit from QueryableFilterUserControl, a base class provided by Dynamic Data and designed for use with DynamicFilter.

Notice that all of the classes in the diagram above – DynamicFilterExpression, QueryableFilterRepeater, DynamicFilter and QueryableFilterUserControl – define a GetQueryable method that takes an IQueryable as a parameter and returns an IQueryable. At run time, the responsibility to modify the underlying LINQ query (an IQueryable instance) is passed from a QueryExtender all the way down the chain to a QueryableFilterUserControl, which was implemented to support filtering for a particular type of column, such as a Boolean or a foreign key.

Filter Controls

Out of the box, ASP.NET Dynamic Data provides filter controls for Boolean, Enumeration and Foreign Key columns. This selection is rather limited, especially when you compare it to the wide range of edit controls available for the various column types. Luckily, creating a new filter template is relatively easy.

In the remainder of this article we will create a template filter for columns of DateTime type. The filter control will allow users to filter date values based on a date value they enter and the operator they select, such as equals, before and after. The completed control will look similar to the picture below.

• Add a new user control, DateTime.ascx, to the ~/DynamicData/Filters folder of your Dynamic Data web application. Name of the ASCX file is important, it will be used to provide a filter hint to Dynamic Data.

<%@ Control Language=”C#” CodeBehind=”DateTime.ascx.cs”
  Inherits=”DynamicDataDemo.DateFilter” %> 

<asp:DropDownList ID=”dropDownList” runat=”server” CssClass=”DDFilter”>
  <asp:ListItem Text=”Equals” Value=”==” />
  <asp:ListItem Text=”Before” Value=”<” />
  <asp:ListItem Text=”After” Value=”>” />
</asp:DropDownList> 

<asp:TextBox ID=”textBox” runat=”server” CssClass=”DDTextBox” Columns=”12″ /> 

<asp:CustomValidator ID=”validator” runat=”server” ControlToValidate=”textBox”
  OnServerValidate=”Validate” Text=”*” CssClass=”DDValidator”/>

In this ASCX, we have a drop-down list that displays a list of date operators the users can select from, and a text box, where they can enter a date value. The custom validator, used for the sake of simplicity, ensures that the value they enter in the text box is a valid date.

• In the code-behind file, change the base class from UserControl to QueryableFilterUserControl. Here is what it will look like at a glance.

• GetQueryable is the main method in our filter control. Defined as abstract in the base class, this method is responsible for adding a filter to the query it receives.

public override IQueryable GetQueryable(IQueryable source)
{
  if (string.IsNullOrEmpty(this.textBox.Text) || !this.validator.IsValid)
  {
    return source;
  } 

  DateTime date = DateTime.Parse(this.textBox.Text);
  ConstantExpression value = Expression.Constant(date); 

  ParameterExpression parameter = Expression.Parameter(source.ElementType);
  MemberExpression property = Expression.Property(parameter, this.Column.Name);
  if (Nullable.GetUnderlyingType(property.Type) != null)
  {
    property = Expression.Property(property, “Value”);
  } 

  BinaryExpression comparison;
  switch (this.dropDownList.SelectedValue)
  {
    case “==”:
      comparison = Expression.Equal(property, value);
      break;
    case “>”:
      comparison = Expression.GreaterThan(property, value);
      break;
    case “<”:
      comparison = Expression.LessThan(property, value);
      break;
    default:
      Debug.Fail(“Unexpected operator”);
      return source;
  } 

  LambdaExpression lambda = Expression.Lambda(comparison, parameter); 

  MethodCallExpression where = Expression.Call(
    typeof(Queryable),
    “Where”,
    new Type[] { source.ElementType },
    new Expression[] { source.Expression, Expression.Quote(lambda) }); 

  return source.Provider.CreateQuery(where);
}

Unfortunately, because this control can be used for any DateTime column of any entity in our model, we cannot use strongly-typed code to implement this method. Instead of IQueryable<Order> we have to write code at the next level up - with the IQueryable interface and build the LINQ expression tree for our filter from the ground up. When expressed with strongly-typed code, the intent of this method could be distilled to the following pseudo-code:

IQueryable<Order> GetQueryable(IQueryable<Order> source)
{
  if (string.IsNullOrEmpty(this.textBox.Text) || !this.validator.IsValid)
  {
    return source;
  } 

  DateTime date = DateTime.Parse(this.textBox.Text); 

  Expression<Func<Order, bool>> lambda = null;
  switch (this.dropDownList.SelectedValue)
  {
    case “==”:
      lambda = order => order.OrderDate == date;
      break;
    case “>”:
      lambda = order => order.OrderDate > date;
      break;
    case “<”:
      lambda = order => order.OrderDate < date;
      break;
    default:
      Debug.Fail(“Unexpected operator”);
      break;
  } 

  return source.Where(lambda);
}

As you can see in the actual implementation above, we have to explicitly perform all tasks the compiler would normally take care for us, such as declaring the parameter of the lambda expression, extracting the underlying value from a nullable property and calling the proper version of the generic Where method based on the entity type. When looking at the actual code above, remember that Where is an extension method defined by the Queryable class, and not by the IQueryable interface.

• FilterControl property returns the control that should receive focus when user selects the Label generated for it by the QueryableFilterRepeater. In our date filter, this can be either the drop-down list or the text box.

public override Control FilterControl
{
  get { return this.textBox; }
}

• The Page_Load event handler performs control initialization tasks that would be typically done declaratively, using markup in a regular filter form where information about columns being filtered is known at design time. In a Dynamic Data filter control, this information is available at run-time through the Column property of the base class, which gives us a MetaColumn object describing the column for which our filter control was generated.

protected void Page_Load(object sender, EventArgs e)
{
  this.textBox.ToolTip = this.Column.Description;
  this.validator.ErrorMessage = “Invalid date specified for ” +
      this.Column.DisplayName;
  this.validator.ToolTip = this.validator.ErrorMessage;
}

• And finally, the Validate method handles the server-side validation event of the CustomValidator our control uses to ensure that a valid date was entered in the text box.

protected void Validate(object sender, ServerValidateEventArgs e)
{
  DateTime value;
  e.IsValid = DateTime.TryParse(e.Value, out value);
}

Filter Scaffolding

Unlike for scaffolding of the data entry controls, ASP.NET Dynamic Data doesn’t use the same convention-based logic for filter controls. In order to instruct the framework to render a custom filter control for the OrderDate of our Order table, we need to mark the OrderDate property in our model with the FilterUIHintAttribute.

• Add a new class to the project that contains your Entity Framework (EDMX) or LINQ to SQL (DBML) file and generated entity classes.

using System.ComponentModel.DataAnnotations; 

namespace DynamicDataDemo
{
    [MetadataType(typeof(Order.Metadata))]
    partial class Order
    {
        public class Metadata
        {
            [FilterUIHint(“DateTime”)]
            public object OrderDate;
        }
    }
}

Taking advantage of the fact that Entity Framework generates entity classes as partial, we can use MetadataTypeAttribute to extend it with a custom metadata class and place an attribute on a property defined in the generated code without modifying generated code directly and risking loosing our changes the next time it is regenerated.

• Place a FilterUIHintAttribute on the property you want to have a filter control. The hint string you specify must match the name of the user control file (DateTime.ascx) without the extension.

Filter Criteria Change Notification

If you are to run your ASP.NET Dynamic Data application now, you should be able to see the new filter for the OrderDate column on the Orders/List.aspx page. However, you will also notice that entering a date in the text box does not filter the results displayed in the grid automatically. This is because our data source control is not aware that filter criteria has changed and that query needs to be executed again. All built-in filter controls are drop-down lists and solve this problem by notifying the data source as soon as the selected value changes. Our custom filter uses a text box and cannot post back to server every time user presses a key when entering a date value. Instead, we will use a Search button to let the user perform the search when they are done with the criteria.

• Modify ~/DynamicData/PageTemplates/List.aspx to add a “Search” button just below the filter criteria.

<asp:QueryableFilterRepeater runat=”server” ID=”FilterRepeater”>
  <ItemTemplate>
    <asp:Label runat=”server” Text=’<%# Eval(”DisplayName”) %>‘
      OnPreRender=”Label_PreRender” />
    <asp:DynamicFilter runat=”server” ID=”DynamicFilter”
      OnFilterChanged=”DynamicFilter_FilterChanged” />
    <br />
  </ItemTemplate>
</asp:QueryableFilterRepeater>
<br />
<asp:Button ID=”searchButton” runat=”server” Text=”Search”
 OnClick=”SearchButton_Click” />

• Implement SearchButton_Click method in the code-behind file.

protected void SearchButton_Click(object sender, EventArgs e)
{
    ((IQueryableDataSource)this.GridDataSource).RaiseViewChanged();
}

In this method, we are calling the RaiseViewChanged method of the IQueryableDataSource interface to let the data source know that it needs to re-execute the query. Unfortunately, EntityDataSource implements this interface explicitly, which requires a type cast before this method can be called.

Here is how the completed Order/List.aspx page looks after the user entered an order date and clicked the Search button. Note that in the entity model, FilterUIHint attributes were specified for OrderDate, RequiredDate and ShippedDate columns of the Orders table.

Conclusion

ASP.NET Dynamic Data provides powerful filtering capabilities that can be extended to fit needs of many data-driven web applications. Although creating dynamic filter controls is significantly more complex than creating statically typed controls, a dynamic filter control developed for a particular data type can be reused for any column of that type by simply applying the FilterUIHintAttribute to the property representing that column in the model. Unfortunately, Dynamic Data does not use the same convention-based logic for scaffolding of filter controls that it uses for scaffolding of data entry controls. This limitation requires you to explicitly place the FilterUIHintAttribute on every column instead of relying on the framework to infer this information based on the column type.

Download

• Sample source code.

©2012 Oleg Sych. All Rights Reserved.

MSDN Radio is a weekly developer talk-show that helps answer your questions about the latest Microsoft news, solutions, and technologies. We dive into the challenges of deciphering today’s technology stack. Click here to listen to the recording.

©2012 Oleg Sych. All Rights Reserved.

Syntax

<#@ parameter name="…" type="…" #>

name

Specifies name of the parameter and must be a valid C# or Visual Basic identifier.

type

Specifies type of the parameter and must include the complete namespace, such as System.String or System.Int32. A custom type can be used as well, as long as the assembly it is defined in is referenced with an assembly directive in the template.

Usage

During template transformation, parameters are available in template code as strongly-typed, read-only properties.

MyTemplate.tt

<#@ template language="C#" #>
<#@ parameter name="MyParameter" type="System.String" #>
Parameter in expression block: <#= MyParameter #>
Parameter in statement block: <# Write(MyParameter) #>

Parameter values can be supplied via remoting CallContext or the template transformation Session. Typically, this would be done in a Visual Studio extension that hosts its own instance of T4 engine or relies on the standard ITextTemplating service. While Visual Studio extensions are a fascinating subject, its discussion is outside of scope of this article. Instead, we will illustrate the technique of passing parameter values using template code itself.

Remoting CallContext

CallContext allows you to define global variables whose scope is limited to a single thread, also known as thread-local variables. While on the surface the CallContext is similar to Thread Local Storage in Windows, when a remoting call is made, whether across the network or simply from one AppDomain to another, the LogicalCallContext travels with the call. In other words, CallContext allows you to define thread-local variables that will work even with remote calls.

In Visual Studio, T4 templates are normally executed in a separate AppDomain, which is periodically unloaded to free memory. Therefore, remoting CallContext is a great way to specify template parameter values. The following example illustrates this can be done for the template shown above.

CallContextTemplate.tt

<#@ template language="C#" hostspecific="true" #>
<#@ output extension=".txt" #>
<#@ import namespace="System.IO" #>
<#@ import namespace="System.Runtime.Remoting.Messaging" #>
<#@ import namespace="Microsoft.VisualStudio.TextTemplating" #>
<#
  string templateFile = this.Host.ResolvePath("MyTemplate.tt");
  string templateContent = File.ReadAllText(templateFile);

  CallContext.LogicalSetData("MyParameter", "CallContextValue");

  Engine engine = new Engine();
  string generatedContent = engine.ProcessTemplate(templateContent, this.Host);

  CallContext.FreeNamedDataSlot("MyParameter");

  this.Write(generatedContent);
#>

Template Transformation Session

In Visual Studio 2010, T4 also allows you to access template transformation Session similar to the Session in ASP.NET. Template transformation session allows you to define variables global for a particular template. Session variables can be passed from the transformation host to the template and can be used to define template parameter values. Here is how this can be done for the template shown above.

SessionTemplate.tt

<#@ template debug="true" hostspecific="true" language="C#" #>
<#@ output extension=".txt" #>
<#@ import namespace="System.IO" #>
<#@ import namespace="Microsoft.VisualStudio.TextTemplating" #>
<#
  string templateFile = this.Host.ResolvePath("MyTemplate.tt");
  string templateContent = File.ReadAllText(templateFile);

  TextTemplatingSession session = new TextTemplatingSession();
  session["MyParameter"] = "SessionValue";

  var sessionHost = (ITextTemplatingSessionHost) this.Host;
  sessionHost.Session = session;

  Engine engine = new Engine();
  string generatedContent = engine.ProcessTemplate(templateContent, this.Host);

  this.Write(generatedContent);
#>

Under the Hood

T4 engine generates a private, read-only property for each parameter directive in your template. In particular, here is how the template shown above is compiled by T4.

public partial class MyTemplate : TextTransformation
{
    private string _MyParameterField;
    private string MyParameter
    {
        get { return this._MyParameterField; }
    }

    public override string TransformText()
    {
        this.GenerationEnvironment = null;
        this.Write("Parameter in expression block: ");
        this.Write(this.ToStringHelper.ToStringWithCulture(MyParameter));

        this.Write("\r\nParameter in statement block: ");
        Write(MyParameter);

        return this.GenerationEnvironment.ToString();
    }

    // …
}

Notice that MyParameter property is backed by a private field. The field is initialized by code in the Initialize method, invoked by T4 before the TransformText method which performs the actual code generation.

public partial class MyTemplate : TextTransformation
{
  // …

  public override void Initialize()
  {
    base.Initialize();
    if (this.Errors.HasErrors == false)
    {
      bool MyParameterValueAcquired = false;
      if (this.Session.ContainsKey("MyParameter"))
      {
        if (typeof(string).IsAssignableFrom(this.Session["MyParameter"].GetType()) == false)
        {
          this.Error("The type \’System.String\’ of the parameter \’MyParameter\’ did not match the type of" +
              " the data passed to the template.");
        }
        else
        {
          this._MyParameterField = (string)this.Session["MyParameter"];
          MyParameterValueAcquired = true;
        }
      }

      if (MyParameterValueAcquired == false)
      {
        object data = CallContext.LogicalGetData("MyParameter");
        if (data != null)
        {
          if (typeof(string).IsAssignableFrom(data.GetType()) == false)
          {
            this.Error("The type \’System.String\’ of the parameter \’MyParameter\’ did not match the type of" +
                " the data passed to the template.");
          }
          else
          {
            this._MyParameterField = (string)data;
          }
        }
      }
    }
  }

  // …
}

As you can see, the template will first try to retrieve the parameter value from its Session, and only if it doesn’t exist there, it will try the remoting CallContext.

Closing Thoughts

Parameter directive closes an important gap in the integration story of T4. In the past, most notably in ASP.NET MVC, this gap lead the tool developers using T4 down the wrong path of creating a custom ITextTemplatingEngineHost just to be able to pass parameters from the tool to the template. Although the remoting CallContext was available before and template parameters are just a thin wrapper around it, this new mechanism will be difficult to miss now that it is a part of the template syntax. Unfortunately, this may have come too late for MVC, which is bound by backward compatibility chains to the old custom host, making it impossible to use any but the limited, MVC-specific templates with this tool.

References

• T4 Templates Natively Support Parameters by Kathleen Dollard
• What’s new in T4 in Visual Studio 2010 by Gareth Jones

©2012 Oleg Sych. All Rights Reserved.

Contents

• Overview
• Configuring project for build-time template transformation
• Under the hood
• Project and Source Control Integration
• Configuring transformation environment
  • $(IncludeFolders) property
  • @(T4ReferencePath) items
  • @(DirectiveProcessor) items
  • @(T4ParameterValues) items
  • .OutputFilePath metadata
  • .OutputFileName metadata
  • $(IncludeDslT4Settings) property
• Controlling transformation process
  • $(TransformOnBuild) property
  • $(TransformOutOfDateOnly) property
  • $(TrackFileAccess) property
  • $(OverwriteReadOnlyOutputFiles) property
  • $(BeforeTransform) property
  • $(AfterTransform) property
  • @(GeneratedFiles) items
  • @(NonGeneratedFiles) items
• Transforming templates by calling MSBuild explicitly
  • TransformAll target
  • Transform target
• Conclusion
• Download

Overview

Since its initial release, T4 has followed a well-established pattern of integrating code generators in Visual Studio and providing two different ways to generate code. The first and primary method of triggering template transformation process is at design time, by saving the template file. When a template (.tt) file is added to a C# or Visual Basic project, it is automatically associated with a custom tool called TextTemplatingFileGenerator. Visual Studio invokes the custom tool whenever the associated file is saved, causing the output file to be regenerated whenever the template file is modified. The second and alternative method of triggering template transformation process is at build time, with a command line utility called TextTransform. In order to generate code at build time, a developer needs to modify the MSBuild definition of a Visual Studio project and invoke this command utility for each of the template files that need to be transformed.

The main benefits of design-time code generation are its simplicity and automatic addition of the generated files in Visual Studio projects and source control. This approach works well when template files are self contained. However, when templates include other files or use external sources of metadata, such as model files or databases, the generated files may become out of date even if their templates don’t change. Build-time code generation ensures that output files are always current and makes sense in complex scenarios when keeping track of multiple templates becomes error prone. The main drawbacks of build-time code generation are the additional effort required to implement it, and more importantly, the set of challenges it presents around integration with Visual Studio projects and source control.

Visual Studio 2010 offers a new option for generating code from text templates at build time. This capability is implemented as a set of MSBuild tasks and targets that come with the Visual Studio Modeling and Visualization SDK. Here is where the files are located.

C:\>dir "C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\TextTemplating\v10.0" /b
Microsoft.TextTemplating.Build.Tasks.dll
Microsoft.TextTemplating.targets
Microsoft.VisualStudio.TextTemplating.Sdk.Host.10.0.dll

The new MSBuild integration feature of T4 significantly reduces the effort required to implement and maintain build-time code generation and solves some of the challenges around integration with Visual Studio projects and source control.

Configuring project for build-time template transformation

In order to configure a Visual Studio project for build-time template transformation, you have to manually modify the MSBuild definition in the project file. At a minimum, you need to import Microsoft.TextTemplating.targets file and set TransformOnBuild property to true. Here is an extract from a C# project file that was modified this way.

<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
<PropertyGroup>
  <TransformOnBuild>true</TransformOnBuild>
</PropertyGroup>
<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\TextTemplating\v10.0\Microsoft.TextTemplating.targets" />

Note that Microsoft.TextTemplating.targets file has to be imported after the standard import – Microsoft.CSharp.targets for C# or Microsoft.VisualBasic.targets for Visual Basic projects. The TransformOnBuild variable can be defined anywhere in the file, such as in the main PropertyGroup of the project.

Here is a typical output you will see when building a customized project.

------ Build started: Project: T4MSBuild, Configuration: Debug x86 ------
Build started 4/10/2010 1:30:38 PM.
ExecuteTransformations:
  Performing incremental T4 transformation
  Calculating whether transformed output is out of date...
  Transforming template Template.tt...
  Performing incremental T4 preprocessing
  Calculating whether preprocessed output is out of date...
  Preprocessing template PreprocessedTemplate.tt...
GenerateTargetFrameworkMonikerAttribute:
Skipping target "GenerateTargetFrameworkMonikerAttribute" because all output files are up-to-date with respect to the input files.
CoreCompile:
  C:\Windows\Microsoft.NET\Framework\v4.0.30319\Csc.exe /noconfig /nowarn:1701,1702 /nostdlib+ /platform:x86 /reference:"C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0\mscorlib.dll" /reference:"C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0\System.Core.dll" /reference:"C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework\.NETFramework\v4.0\System.dll" /debug+ /out:obj\x86\Debug\T4MSBuild.dll /target:library PreprocessedTemplate.cs Template.cs "C:\Users\osych\AppData\Local\Temp\.NETFramework,Version=v4.0.AssemblyAttributes.cs"
CopyFilesToOutputDirectory:
  Copying file from "obj\x86\Debug\T4MSBuild.dll" to "bin\Debug\T4MSBuild.dll".
  T4MSBuild -> C:\T4MSBuild\T4MSBuild\bin\Debug\T4MSBuild.dll
  Copying file from "obj\x86\Debug\T4MSBuild.pdb" to "bin\Debug\T4MSBuild.pdb".

Build succeeded.

Time Elapsed 00:00:00.55
========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ==========

In this sample output, note that a file called Template.tt was transformed and another file called PreprocessedTemplate.tt was preprocessed. In other words, the MSBuild functionality fully supports the preprocessed templates introduced in Visual Studio 2010.

Under the hood

When imported, Microsoft.TextTemplating.targets file modifies the normal project build process defined in Microsoft.Common.targets by inserting the following steps (targets) in the beginning of the build sequence.

• Create a list of candidate files for transformation
• Execute user-defined target before transformation
• Select template files for processing
• Transform and/or preprocess templates
• Execute user-defined target after transformation

T4 creates a list of candidate files for transformation by selecting all files in the project that have build action of None, Compile, Content or EmbeddedResource. Normally, .tt files have build action of None and get included automatically.

After the initial list of candidate files has been created, T4 invokes a user-defined target specified in the $(BeforeTransform) property. You can assign this property and provide a custom target if you need to perform any actions before the templates are processed.

After executing the user-defined BeforeTransform target, T4 will use the initial candidate list of files to select those associated with the TextTemplatingFileGenerator custom tool to be transformed in a set of items called @(T4TransformInputs) and those associated with the TextTemplatingFilePreprocessor custom tool to be pre-processed in a set of items called @(T4PreprocessInputs). It is important to remember that template files are selected for processing based on their association with one of the T4’s custom tools; the file extension or build action have no effect in this process.

After determining the actual lists of templates, T4 transforms and pre-processes them. This is done by the MSBuild tasks called TransformTemplates and PreprocessTemplates implemented in Microsoft.TextTemplating.Build.Tasks.dll. These tasks use a custom T4 host implemented in Microsoft.VisualStudio.TextTemplating.Sdk.Host.10.0.dll.

In T4 architecture,  the host plays a very important role in the template transformation process. It provides the compilation and run-time environment for the code generation and determines how the included files are located, how the assembly references are resolved, how directive processors are selected and more. Each of the existing T4 hosts is implemented and configured differently, which can make them incompatible with templates that take advantage of the unique functionality of a particular host. For example, T4 templates in ASP.NET MVC and T4 Toolbox rely on the unique features of the MVC and Visual Studio hosts respectively. They are currently incompatible with the MSBuild host described here.

Even templates that don’t have hard-coded dependencies on a particular host will often require additional steps to configure the transformation environment before they can be processed by the MSBuild host. Detailed description of the configuration options is available later in this article.

After transforming and preprocessing templates, T4 invokes a second user-defined target specified in the $(AfterTransform) property. You can assign this variable and provide a custom target if you need to perform any actions when the templates are transformed but before the build starts.

Project and Source Control Integration

Unlike the standard Visual Studio host of T4, the MSBuild host described here does not integrate generated files with Visual Studio projects or source control. In particular, the generated files are not added to the project and source control automatically; the regenerated files are not checked out from source control automatically. This integration functionality relies on services provided by Visual Studio, which is not available in the MSBuild host.

Luckily, a limited awareness of source control exists in the MSBuild host of T4. By default, it will issue a warning for each read-only output file that could not be regenerated and an error, making sure that build will fail if one or more files could not be regenerated.

In order to resolve these errors, you can either locate and check out all required files manually, or transform all templates from the toolbar in Solution Explorer, which will process them using the Visual Studio host and check out all files automatically. Once the files have been regenerated, you will typically want to check them back in source control.

You can also instruct T4 to automatically overwrite read-only files during code generation by setting the $(OverwriteReadOnlyOutputFiles) property to true.

<PropertyGroup>
  <TransformOnBuild>true</TransformOnBuild>
  <OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>
</PropertyGroup>
<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\TextTemplating\v10.0\Microsoft.TextTemplating.targets" />

This setting eliminates build errors, but introduces discrepancies between the code checked in the source control repository and the actual code compiled during the build. With this approach you can no longer rely on the source control repository alone to recreate a particular labeled build. If you want to debug or troubleshoot a particular build of the application later, you will have to save the complete source code in addition to the binary and symbol files produced by each build. This is necessary for all but trivial scenarios, and especially for packaged commercial software products and enterprise applications.

Configuring transformation environment

MSBuild functionality of T4 relies on a new engine host, which is different from both the default host used by the T4 custom tools in Visual Studio and the command line host used by TextTransform.exe. It relies on MSBuild items and properties to configure normal settings such as include search path, directive processors and assembly references, as well as settings unique to the MSBuild host.

$(IncludeFolders) property

Specifies a coma-separated list of directories that T4 will search to resolve files referenced by include directives. This property is empty by default.

<PropertyGroup>
  <IncludeFolders>$(MSBuildProjectDirectory)\Include</IncludeFolders>
</PropertyGroup>

$(IncludeFolders) property is an equivalent of the –I parameter of the command-line host and the HKLM\Software\Microsoft\VisualStudio\10.0\TextTemplating\IncludeFolders registry setting of the Visual Studio host of T4.

@(T4ReferencePath) items

Specify individual folders where T4 will search to resolve assemblies referenced by assembly directives and custom directive processors. This item list is empty by default.

<ItemGroup>
  <T4ReferencePath Include="$(VsInstallDir)PublicAssemblies\" />
</ItemGroup>

@(T4ReferencePath) items are an equivalent of the –P parameter of the command-line host and have no direct equivalent in the Visual Studio host of T4, which uses global assembly cache, assemblies referenced by the project and some hard-coded search paths.

@(DirectiveProcessor) items

Specify definitions of the directive processors T4 will use when processing custom directives. This item list is empty by default.

<ItemGroup>
  <DirectiveProcessor Include="T4Toolbox.XsdProcessor" >
    <Class>T4Toolbox.XsdProcessor</Class>
    <CodeBase>C:\Program Files (x86)\T4 Toolbox\Bin\T4Toolbox.10.0.dll</CodeBase>
  </DirectiveProcessor>
</ItemGroup>

Assembly location can be specified using either CodeBase or Assembly metadata item which allows you to reference the assembly from disk or from global assembly cache respectively.

<ItemGroup>
  <DirectiveProcessor Include="T4Toolbox.XsdProcessor" >
    <Class>T4Toolbox.XsdProcessor</Class>
    <Assembly>T4Toolbox.10.0, Version=10.3.7.1, Culture=neutral, PublicKeyToken=7e313accbcce84dc</Assembly>
  </DirectiveProcessor>
</ItemGroup>

@(DirectiveProcessor) items are an equivalent of the –db option of the command-line host and the HKLM\Software\Microsoft\VisualStudio\10.0\TextTemplating\DirectiveProcessors registry setting of the Visual Studio host of T4.

@(T4ParameterValues) items

Specify parameters that custom directive processors and templates themselves can query using ResolveParameterValue method. This item list is empty by default.

<ItemGroup>
  <T4ParameterValues Include="ParameterName">
    <Value>ParameterValue</Value>
  </T4ParameterValues>
</ItemGroup>

@(T4ParameterValues) items are an equivalent of the –a option of the command-line host and have no direct equivalent in the Visual Studio host of T4.

.OutputFilePath metadata

Specifies the directory where template’s output file will be generated. This metadata item is empty by default.

<ItemGroup>
  <None Include="Template.tt">
    <Generator>TextTemplatingFileGenerator</Generator>
    <OutputFilePath>$(IntermediateOutputPath)</OutputFilePath>
    <LastGenOutput>Template.cs</LastGenOutput>
  </None>
</ItemGroup>

By default, T4 will place generated output file in the same directory with the template file. You can set this property to redirect generated output files to a different directory during build-time code generation. This property has no effect on design-time code generation performed by the TextTemplatingFileGenerator or TextTemplatingFilePreprocessor when the template file is saved in Visual Studio editor. Setting this property will result in different behavior in code generation at design time vs. build time.

.OutputFilePath metadata is an equivalent of the –out option of the command-line host and has no direct equivalent in the Visual Studio host of T4.

.OutputFileName metadata

Specifies the name of the generated output file. This metadata item is empty by default.

<ItemGroup>
  <None Include="Template.tt">
    <Generator>TextTemplatingFileGenerator</Generator>
    <OutputFileName>Generated.cs</OutputFileName>
    <LastGenOutput>Template.cs</LastGenOutput>
  </None>
</ItemGroup>

By default, T4 will name generated output file with the name of the template file and the extension specified in the output directive in the template. You can set this property to change the default file name during build-time code generation. This property has no effect on design-time code generation performed by the TextTemplatingFileGenerator or TextTemplatingFilePreprocessor when the template file is saved in Visual Studio editor. Setting this property will result in different behavior in code generation at design time vs. build time.

.OutputFileName metadata is an equivalent of the –out option of the command-line host and has no direct equivalent in the Visual Studio host of T4.

$(IncludeDslT4Settings) property

Determines whether DSL-specific settings should be turned on. This property can be set to true or false and has a default value of false.

<PropertyGroup>
  <IncludeDslT4Settings>true</IncludeDslT4Settings>
</PropertyGroup>

This is a convenience property that configures various settings required for performing build-time template transformation in DSL projects.

Controlling transformation process

This section lists the various configuration settings that can be used to control the T4 template transformation process in MSBuild project files.

$(TransformOnBuild) property

Determines whether templates will be transformed at build-time automatically. This property can be set to true or false and has a default value of false. When $(TransformOnBuild) is false, templates will be transformed at design-time in Visual Studio and can also be transformed by calling MSBuild explicitly.

<PropertyGroup>
  <TransformOnBuild>true</TransformOnBuild>
</PropertyGroup>

$(TransformOutOfDateOnly) property

Controls incremental template transformation and indicates whether only out of date or all templates should be processed. This property can be set to true or false and has a default value of true.

<PropertyGroup>
  <TransformOutOfDateOnly>false</TransformOutOfDateOnly>
</PropertyGroup>

An out-of-date file is one where any of the input files used to generated the file were modified more recently than the file itself. The input files are the included template files and the files referenced by custom directive processors. In addition, a file that contains only “ErrorGeneratingOutput” written to it when the last transformation failed is also treated as being out of date.

T4 relies on the file tracking feature in MSBuild by logging all of the file read / write operations as they occur when generating an output file. If the tracking logs do not exist for a project, T4 assumes that the template is out of date and transforms it.

$(TrackFileAccess) property

Determines whether T4 will log file read / write operations to allow subsequent incremental template transformations. This property can be set to true or false and has a default value of true.

<PropertyGroup>
  <TrackFileAccess>false</TrackFileAccess>
</PropertyGroup>

If you don’t rely on incremental template transformations, you may want to set this property to false to reduce the amount of space taken by the log files in the intermediate output directory (obj\Debug).

$(OverwriteReadOnlyOutputFiles) property

Indicates whether read-only output files will be overwritten during template transformation. This property can be set to true or false and has a default value of false.

<PropertyGroup>
  <OverwriteReadOnlyOutputFiles>true</OverwriteReadOnlyOutputFiles>
</PropertyGroup>

When $(OverwriteReadOnlyOutputFiles) is false, T4 issues a warning for each output file that could not be regenerated because it is read-only and the build will fail. When $(OverwriteReadOnlyOutputFiles) is true, T4 will overwrite read-only files and report a warning for each overwritten file. These warnings are not considered to be compiler warnings for the purpose of the “Treat warnings as errors” project setting.

$(BeforeTransform) property

Specifies a user-defined MSBuild target that will be executed before template transformation. This property is empty by default.

<PropertyGroup>
  <TransformOnBuild>true</TransformOnBuild>
  <BeforeTransform>OnBeforeTransform</BeforeTransform>
</PropertyGroup>
<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\TextTemplating\v10.0\Microsoft.TextTemplating.targets" />
<Target Name="OnBeforeTransform">
  <Message Text="This executes before templates are transformed" Importance="high"/>
</Target>

$(AfterTransform) property

Specifies a user-defined MSBuild target that will be executed before template transformation. This property is empty by default.

<PropertyGroup>
  <TransformOnBuild>true</TransformOnBuild>
  <AfterTransform>OnAfterTransform</AfterTransform>
</PropertyGroup>
<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\TextTemplating\v10.0\Microsoft.TextTemplating.targets" />
<Target Name="OnAfterTransform">
  <Message Text="This executes after templates are transformed" Importance="high"/>
</Target>

@(GeneratedFiles) items

Are produced by by the TransformTemplates and PreprocessTemplates to indicate output files that were successfully generated. @(GeneratedFiles) have .ReadOnlyFileOverwritten metadata item set to true when $(OverwriteReadOnlyOutputFiles) property is set to true and a particular read-only output file was overwritten during code generation. @(GeneratedFiles) items can be used in the user-defined AfterTransform target.

@(NonGeneratedFiles) items

Are produced by by the TransformTemplates and PreprocessTemplates to indicate output files that could not be regenerated. The list of @(NonGeneratedFiles) can be examined in the user-defined AfterTransform target.

Transforming templates by calling MSBuild explicitly

In addition to automatically transforming templates at build time, T4 provides two targets you can call explicitly to transform or preprocess templates in a particular project by invoking MSBuild from command line.

TransformAll target

Calling the TransformAll target will transform all files associated with TextTemplatingFileGenerator and TextTemplatingFilePreprocessor in the specified project. It is an equivalent of setting $(TransformOnBuild) to true and performing template transformation at build time.

Syntax

msbuild t4msbuild.csproj /t:TransformAll

Sample Output

Transform target

Transform target allows you to specify which file or files have to be transformed. It expects you to provide a value for TransformFile property, which accepts individual file names as well as MSBuild wildcards.

Syntax

msbuild t4msbuild.csproj /t:Transform /p:TransformFile=*.tt

Sample Output

Conclusion

Visual Studio 2010 introduced a new capability based on MSBuild extensions for transforming and preprocessing text templates at build time. The new capability comes with a set of distinct advantages and drawbacks. Compared to the existing command line tool, TextTransform, it makes implementation and maintenance of build-time template transformation easier. However, compared to the existing Visual Studio tools, it does not support project and source control integration. The MSBuild extensions also rely on a brand-new T4 engine host, with a unique compilation and run-time environment for text templates. Templates that take advantage of specific capabilities provided by a particular host (such as ASP.NET MVC and T4 Toolbox templates) are not be compatible with the new MSBuild host. Templates designed to be host-agnostic, may require you to configure the MSBuild host before they can be processed correctly. In particular, locations of the included files, .NET assemblies and definitions of custom directive processors have to be supplied explicitly.

Download

• Visual Studio 2010 SDK (pre-requisite)
• Visual Studio 2010 Modeling and Visualization SDK (pre-requisite)

©2012 Oleg Sych. All Rights Reserved.

Output Integration Capabilities of T4 Toolbox

T4 Toolbox offers rich capabilities for integrating generated output files in Visual Studio projects, including automatically adding generated files to multiple projects, specifying project item attributes, adding assembly references to target projects and more. The framework allows specifying these integration details declaratively, takes care of the plumbing and helps developers to concentrate on the code generation itself.

Integration capabilities are exposed through the Output property of Template class in T4 Toolbox. As you remember, Template class represents a single logical unit of code generation. For example, you might create a template that generates a single .NET class or a SQL stored procedure. Here is what it might look like.

C#

<#+
public class TableTemplate : Template
{
    public override string TransformText()
    {
#>
CREATE TABLE [dbo].[TableCs]
(
    column_1 int NOT NULL,
    column_2 int NULL
)
<#+
        return this.GenerationEnvironment.ToString();
    }
}
#>

VB

<#+
Public Class TableTemplate
    Inherits Template

    Public Overrides Function TransformText() As String
#>
CREATE TABLE [dbo].[TableVb]
(
    column_1 int NOT NULL,
    column_2 int NULL
)
<#+
        Return Me.GenerationEnvironment.ToString()
    End Function

End Class
#>

Having defined the template, we can use it to generate code like so.

C#

<#@ template language="C#" hostspecific="True" debug="True" #>
<#@ output extension="sql" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="TableTemplate.tt" #>
<#
    TableTemplate t = new TableTemplate();
    t.Render();
#>

VB

<#@ template language="VB" hostspecific="True" debug="True" #>
<#@ output extension="sql" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="TableTemplate.tt" #>
<#
    Dim t as TableTemplate = New TableTemplate()
    t.Render()
#>

Output

CREATE TABLE [dbo].[TableCs]
(
    column_1 int NOT NULL,
    column_2 int NULL
)

Template.Output property returns an instance of OutputInfo class which you can use to declaratively specify how output generated by the template will be integrated by the T4 Toolbox framework.

Output.File property

File property of the OutputInfo class specifies name of the file where generated output will be saved. By default, it is empty, meaning that generated output will be added to the standard output file generated for the root .tt file by Visual Studio. Here is an example of setting this property to save generated output in a separate file.

C#

<#
  TableTemplate t = new TableTemplate();
  t.Output.File = "Table.sql";
  t.Render();
#>

VB

<#
    Dim t as TableTemplate = New TableTemplate()
    t.Output.File = "Table.sql"
    t.Render()
#>

Output.File property value can also include file path. When it does, T4 Toolbox will save the file in the specified folder. When the generated file is not located in the same folder with the root .tt template, T4 Toolbox will also create a code generation log file (Script.tt.log in this example) for keeping track of the generated file, which is now stored away from the root .tt file. T4 Toolbox keeps track of all generated files in order to automatically remove them when they are no longer regenerated.

C#

<#
  TableTemplate t = new TableTemplate();
  t.Output.File = @"SQL Scripts\Table.sql";
  t.Render();
#>

VB

<#
    Dim t as TableTemplate = New TableTemplate()
    t.Output.File = "SQL Scripts\Table.sql"
    t.Render()
#>

Output of multiple templates can be combined in a single file. When the File property is empty for multiple templates, their outputs are combined in the standard output file of the root .tt file. Similarly, when the File property of several templates is set to the same file name, their outputs will be combined in the specified, separate file. This capability allows you to design a code generator to be granular by default, but allow combining the outputs when managing a single generated file is desired. The following example illustrates a code generator that combines generated table and stored procedure in a single SQL script.

C#

<#
  var t = new TableTemplate();
  t.Output.File = "Database.sql";
  t.Render();

  var p = new ProcedureTemplate();
  p.Output.File = "Database.sql";
  p.Render();
#>

VB

<#
  Dim t as New TableTemplate()
  t.Output.File = "Database.sql"
  t.Render()

  Dim p as New ProcedureTemplate()
  p.Output.File = "Database.sql"
  p.Render()
#>

Output

CREATE TABLE [dbo].[TableCs]
(
    column_1 int NOT NULL,
    column_2 int NULL
);
CREATE PROCEDURE [dbo].[ProcedureCs]
    @param1 int = 0,
    @param2 int
AS
    SELECT @param1, @param2
RETURN 0;

Output.Encoding property

Encoding property of the OutputInfo class specifies the Encoding that will be used to save the output file. This property is an equivalent of the encoding attribute in the standard output directive in T4. It is set to ANSI by default. One of examples of when you may want to explicitly specify encoding of the output file is when your template generates XML and specifies encoding in the file content, which needs to match.

C#

<#@ import namespace="System.Text" #>
<#
  var t = new XmlTemplate();
  t.Output.File = "File.xml";
  t.Output.Encoding = Encoding.UTF8;
  t.Render();
#>

VB

<#@ import namespace="System.Text" #>
<#
  Dim t as New XmlTemplate()
  t.Output.File = "File.xml"
  t.Output.Encoding = Encoding.UTF8
  t.Render()
#>

Output.Project property

Project property of the OutputInfo class specifies the project file to which the output file will be added. You will usually set this property to a path relative from the .tt file to the target project file. In addition, you will also typically set the File property to specify name and location of the output file within the target project. There is an important different between the File and Project properties in the way they treat relative paths. Project property always assumes that path is relative to the location of the root .tt file, whereas File property assumes that path is relative to the location of the target project file when the Project property is specified.

C#

<#
  TableTemplate t = new TableTemplate();
  t.Output.Project = @"..\Database\Database.dbproj";
  t.Output.File = @"Schema Objects\Schemas\dbo\Tables\TableCs.table.sql";
  t.Render();
#>

VB

<#
  Dim t as TableTemplate = New TableTemplate()
  t.Output.Project = "..\Database\Database.dbproj"
  t.Output.File = "Schema Objects\Schemas\dbo\Tables\TableVb.table.sql"
  t.Render()
#>

Output.BuildAction property

BuildAction property of the OutputInfo class specifies the build action that will be assigned for the output file in the target project. By default, this property is not assigned, allowing Visual Studio to pick the build action appropriate for the file type. Because build actions can be customized by importing MSBuild target files, the type of BuildAction property is not an enumeration, but a string. Common build actions, such as Content, Compile and EmbeddedResource are available as constants in a static class called BuildAction.

C#

<#
  TableTemplate t = new TableTemplate();
  t.Output.File = "TableCs.sql";
  t.Output.BuildAction = BuildAction.Content;
  t.Render();
#>

VB

<#
  Dim t as TableTemplate = New TableTemplate()
  t.Output.File = "TableVb.sql"
  t.Output.BuildAction = BuildAction.Content
  t.Render()
#>

Output.CopyToOutputDirectory property

CopyToOutputDirectory property of the OutputInfo class specifies the value that will be assigned to “Copy to Output Directory” attribute of the output file in the target project. The type of CopyToOutputDirectory property is an enumeration also called CopyToOutputDirectory, with items like CopyAlways, CopyIfNewer and DoNotCopy (default).

C#

<#
  TableTemplate t = new TableTemplate();
  t.Output.File = "TableCs.sql";
  t.Output.CopyToOutputDirectory = CopyToOutputDirectory.CopyAlways;
  t.Render();
#>

VB

<#
  Dim t as TableTemplate = New TableTemplate()
  t.Output.File = "TableVb.sql"
  t.Output.CopyToOutputDirectory = CopyToOutputDirectory.CopyAlways
  t.Render()
#>

Output.CustomTool and Output.CustomToolNamespace properties

CustomTool and CustomToolNamespace properties of the OutputInfo class specify the value that will be assigned to the “Custom Tool” and “Custom Tool Namespace” attributes of the output file. These properties are of type string. They are null by default, which leaves Visual Studio to pick appropriate defaults based the file type. The following example illustrates generating a resource file, assigning ResXFileCodeGenerator to automatically generate a strongly-typed .NET wrapper for the resource in a particular namespace.

C#

<#
  var t = new ResourceTemplate();
  t.Output.File = "Resource.resx";
  t.Output.CustomTool = "ResXFileCodeGenerator";
  t.Output.CustomToolNamespace = "CustomNamespace";
  t.Render();
#>

VB

<#
  Dim t as New ResourceTemplate()
  t.Output.File = "Resource.resx"
  t.Output.CustomTool = "ResXFileCodeGenerator"
  t.Output.CustomToolNamespace = "CustomNamespace"
  t.Render()
#>

Output.BuildProperties property

For some types of files, such as resource files, not all project item attributes are exposed in Visual Studio user interface. In particular, resource files have a LogicalName attribute that determines the name under which the resource will be embedded in a .NET assembly. BuildProperties property of the OutputInfo class allows you to specify this and other MSBuild properties for the output file. BuildProperties is a string dictionary, you will need to know names of the properties you want to set.

C#

<#
  var t = new ResourceTemplate();
  t.Output.File = "Resource.resx";
  t.Output.BuildProperties["LogicalName"] = "MyResource";
  t.Render();
#>

VB

<#
  Dim t as New ResourceTemplate()
  t.Output.File = "Resource.resx"
  t.Output.BuildProperties("LogicalName") = "MyResource"
  t.Render()
#>

Output.References property

References property of the OutputInfo class specifies the assembly references that needed for the generated file to compile. References is a collection of strings, empty by default. The following example illustrates a scenario where the generated output uses Oracle client and needs a reference to System.Data.OracleClient assembly to compile. When the template is rendered, T4 Toolbox will automatically add the specified reference(s) to the target project.

C#

<#
  var t = new OracleTemplate();
  t.Output.File = "OracleCode.cs";
  t.Output.References.Add("System.Data.OracleClient");
  t.Render();
#>

VB

<#
  Dim t as New OracleTemplate()
  t.Output.File = "OracleCode.vb"
  t.Output.References.Add("System.Data.OracleClient")
  t.Render()
#>

Output.PreserveExistingFile property

PreserveExistingFile is a boolean property of the OutputInfo class. It is false by default, which means that T4 Toolbox will treat the output file as automatically generated, under full control of the generator. When PreserveExistingFile is true, T4 Toolbox will treat the output file as optionally generated, under full control of the developer. If the file already exists before code generation, the framework will assume that developer created it manually and will not overwrite it. When the file is no longer generated, the framework will again assume that developer modified it and will not delete the file. This logic is designed to preserve code written by hand.

Setting this property to true allows you to generate scaffolding code - code meant to serve as a sample or starting point for a developer to complete manually, such as partial classes or stubs.

C#

<#
  var t = new SampleTemplate();
  t.Output.File = "Sample.cs";
  t.Output.PreserveExistingFile = true;
  t.Render();
#>

VB

<#
  Dim t as New SampleTemplate()
  t.Output.File = "Sample.vb"
  t.Output.PreserveExistingFile = True
  t.Render()
#>

Download

Source code, C# and Visual Basic.

©2012 Oleg Sych. All Rights Reserved.

This article is based on Beta 2 of Visual Studio 2010 Ultimate Edition. To follow the code example you may also want to install T4 Editor which provides color syntax highlighting and IntelliSense for text templates in Visual Studio.

UML Modeling in Visual Studio

Visual Studio 2010 Ultimate Edition includes a fully-featured UML (Unified Modeling Language) support, integrated into the IDE. You can create Use Case diagrams to summarize who uses your application or system, and what they can do with it, Class diagrams to describe logical aspects of data types and their relationships, Sequence diagrams to display interaction between classes, components and actors, Activity diagrams to document flow of an algorithm or a business process and Component diagrams to show structure of a system, and how it can be deployed to a logical environment.

In order to start using UML diagrams in Visual Studio 2010, you first need to create a Modeling Project.

Once you have the project created, you can add new diagrams to it.

Here is an example of class diagram you can create.

Model elements can be added to the diagram from Toolbox and configured using Properties window.

You may have noticed that these diagrams are very similar to the sample diagrams that were included with the DSL (Domain-Specific Language) Toolkit in Visual Studio 2008. While little has changed on the surface, DSL diagrams had a major limitation before Visual Studio 2010. Model information was stored with each diagram, limiting you to a single diagram per model. Needless to say, this limitation made it impossible to use DSL diagrams for all but simplest models.

In Visual Studio 2010, definitions of model elements are stored in a centralized repository as part of your Modeling Project; they can be displayed on multiple diagrams. You can browse contents of the repository using UML Model Explorer and add existing elements to new diagrams by dragging them from this window onto the design surface.

UML Profiles

While UML works well for conceptual analysis, the standard models are often too abstract to be useful for logical and physical design. UML Profiles can be used to extend the standard models and adapt them for a particular purpose.

In Visual Studio 2010, a UML Profile is a collection of stereotypes that can be applied to individual model elements. Each stereotype defines a set of attributes that extend definition of the model element it is applied to. For example, Visual Studio includes C# Profile that can be used to extend UML classes with attributes specific to C#.

In order to use stereotypes from a particular profile, first you need to select a package in the UML Model Explorer and apply the profile in the Properties window.

Once a profile has been specified for the package, you can apply the stereotypes defined by the profile to the elements within the package. Example below shows the C# Class stereotype applied to a UML class, extending it with C#-specific attributes, such as Is Partial and Is Static.

Custom UML Profiles

You may want to consider creating a custom UML profile if you rely heavily on modeling in your software development project. Database modeling in particular has been widely adopted by the IT industry, with most of the new projects using database models in some shape or fashion. Unfortunately, no standard UML profile is available for database modeling at the time of this writing. However, the process of creating such a profile in Visual Studio 2010 is relatively straightforward.

Visual Studio 2010 UML profiles are defined in XML files with .profile extension.

The profile definition consists of three sections: metaclasses, propertyTypes and stereotypes.

The metaclasses section lists all UML meta-classes that are extended by stereotypes in the profile. In practical terms, meta-class is a type of model element, such as Package, Class or Association. Meta-classes are identified using fully-qualified type names of the interfaces used in Visual Studio implementation. For example, IAssociation interface represents UML meta-class Association.

The propertyTypes section lists all types used by properties in stereotypes defined by the profile. Standard types, such as System.String can be specified using externalType element. You can also use enumerationType elements to define enumerated types, such as ForeignKeyRule.

<enumerationType name=“ForeignKeyRule“>
  <enumerationLiterals>
    <enumerationLiteral name=“NoAction” displayName=“No Action“/>
    <enumerationLiteral name=“Cascade” displayName=“Cascade“/>
    <enumerationLiteral name=“SetNull” displayName=“Set Null“/>
    <enumerationLiteral name=“SetDefault” displayName=“Set Default“/>
  </enumerationLiterals>
</enumerationType>

Finally, the stereotypes section contains the actual stereotype definitions. Each stereotype contains a metaclasses element, which specifies the UML meta-class this stereotype extends, and a properties element, which lists the properties that will be added to the target model element when the stereotype is applied to it. 

<stereotype name=“ForeignKey” displayName=“Foreign Key“>
  <metaclasses>
    <metaclassMoniker name=“/Sql2008DatabaseProfile/Microsoft.VisualStudio.Uml.Classes.IAssociation” />
  </metaclasses>
  <properties>
    <property name=“DeleteRule” displayName=“Delete Rule” defaultValue=“NoAction“>
      <propertyType>
        <enumerationTypeMoniker name=“/Sql2008DatabaseProfile/ForeignKeyRule“/>
      </propertyType>
    </property>
    <property name=“UpdateRule” displayName=“Update Rule” defaultValue=“NoAction“>
      <propertyType>
        <enumerationTypeMoniker name=“/Sql2008DatabaseProfile/ForeignKeyRule“/>
      </propertyType>
    </property>
  </properties>
</stereotype>

As you can see, the ForeignKey stereotype shown above can be applied to Associations in a UML model. This stereotype defines two properties – DeleteRule and UpdateRule, both of which use the ForeignKeyRule enumerated type defined in the propertyTypes section of our profile.

Notice that various elements in the profile definition have attributes called name and displayName. As you might expect, name specifies internal identifier you can use to access values programmatically, and displayName specifies human-readable text displayed by Visual Studio to the developer.

Sample Database Profile

A sample UML profile for database modeling is available for download at the end of this article. It allows you to extend UML class diagrams with stereotypes for modeling database schemas, tables, columns, primary and foreign keys in SQL Server 2008. Here is what a database diagram developed with this profile might look like.

The sample database profile contains the following stereotypes.

Profile Installation

The intended way to install custom UML Profiles is with the help of Visual Studio Extensions, new to Visual Studio 2010. The process is well documented on MSDN, simple and easy to follow. Unfortunately, as of Visual Studio 2010 Beta 2, VSIX deployment of custom profiles appears to be broken. In order to install the sample database profile, I had to resort to manually copying the .profile file to the following directory on a 64-bit Windows 7 installation:

C:\Program Files (x86)\Microsoft Visual Studio 10.0\Common7\IDE\Extensions\Microsoft\Team Architecture\UmlProfiles

and modifying extension.vsixmanifest file located in this directory to look like this.

<?xml version=“1.0” encoding=“utf-8“?>
<Vsix Version=“1.0.0” xmlns=“http://schemas.microsoft.com/developer/vsx-schema/2010“>
  <Identifier Id=“Microsoft.VisualStudio.TeamArchitect.ProfileExtension“>
    <Name>Team Architecture Profile Extension</Name>
    <Author>Microsoft</Author>
    <Version>10.0</Version>
    <Description>Microsoft Visual Studio Team Architecture Profile Extension</Description>
    <Locale>1033</Locale>
    <SupportedProducts>
      <VisualStudio Version=“10.0“>
        <Edition>VSTS</Edition>
      </VisualStudio>
    </SupportedProducts>
    <SupportedFrameworkRuntimeEdition MinVersion=“4.0” MaxVersion=“4.0” />
    <SystemComponent>true</SystemComponent>
  </Identifier>
  <References />
  <Content>
    <CustomExtension Type=“Microsoft.VisualStudio.UmlProfile“>CSharp.Profile</CustomExtension>
    <CustomExtension Type=“Microsoft.VisualStudio.UmlProfile“>StandardProfileL2.Profile</CustomExtension>
    <CustomExtension Type=“Microsoft.VisualStudio.UmlProfile“>StandardProfileL3.Profile</CustomExtension>
    <CustomExtension Type=“Microsoft.VisualStudio.UmlProfile“>Sql2008Database.profile</CustomExtension>
  </Content>
</Vsix>

Notice the CustomExtension added in the end of the file, specifying Sql2008Database.profile as an extension of Microsoft.VisualStudio.UmlProfile type.

Code Generation

The simplest way to generate code from a UML model is with the help of T4 text templates. Text template is a simple code generator that can be added to any C# and Visual Basic project.

Here is the code you need to have in your template to load metadata from a UML model.

<#@ template debug=“true“ hostspecific=“true“ language=“C#“ #>
<#@ output extension=“.sql“ #>
<#@ assembly name=“Microsoft.VisualStudio.Uml.Interfaces.dll“ #>
<#@ assembly name=“Microsoft.VisualStudio.Uml.Extensions.dll“ #>
<#@ import namespace=“Microsoft.VisualStudio.Uml.Classes“ #>
<#@ import namespace=“Microsoft.VisualStudio.Uml.Extensions“ #>
<#
    string projectPath = Host.ResolvePath(@”..\ModelingProject\ModelingProject.modelproj”);
    IModelingProject project = ModelingProject.Load(projectPath);
#>

Notice the use of assembly and import directives to reference the Visual Studio assemblies and namespaces that provide API for accessing information in UML models. ResolvePath method of the Host object is used to determine absolute path to the modeling project and Load method of the ModelingProject class is used to open the UML repository.

Here is a complete template that generates SQL scripts for creating tables based on the UML class model extended by our database profile.

<#@ template debug=“true“ hostspecific=“true“ language=“C#“ #>
<#@ output extension=“.sql“ #>
<#@ assembly name=“System.Core“ #>
<#@ assembly name=“Microsoft.VisualStudio.Uml.Interfaces.dll“ #>
<#@ assembly name=“Microsoft.VisualStudio.Uml.Extensions.dll“ #>
<#@ import namespace=“System.Linq“ #>
<#@ import namespace=“Microsoft.VisualStudio.Uml.Classes“ #>
<#@ import namespace=“Microsoft.VisualStudio.Uml.Extensions“ #>
<#
    string projectPath = this.Host.ResolvePath(@”..\ModelingProject\ModelingProject.modelproj”);
    IModelingProject project = ModelingProject.Load(projectPath);
    foreach (IType t in project.Store.Root.OwnedTypes)
    {
        IClass c = t as IClass;
        if (c == null) continue;
#>
create table <#= GetSchema(project.Store.Root) #>.<#= c.Name #>
(
<#
        this.PushIndent(“\t”);
        foreach (IProperty p in c.OwnedAttributes)
        {
            IStereotypeInstance column = p.AppliedStereotypes.Where(s => s.Name == “Column”).First();
            this.WriteLine(p.Name + ” “ + GetDataType(column) + GetNull(column) + GetIdentity(column) + “,”);
        }
        this.PopIndent();
#>
);
<#
    }
#>
<#+
    private string GetSchema(IPackage package)
    {
        IStereotypeInstance schema = package.AppliedStereotypes.Where(s => s.Name == “Schema”).First();
        IStereotypePropertyInstance schemaName = schema.PropertyInstances.Where(p => p.Name == “Name”).First();
        return schemaName.Value;
    } 

    private string GetDataType(IStereotypeInstance column)
    {
        IStereotypePropertyInstance dataType = column.PropertyInstances.Where(p => p.Name == “DataType”).First();
        return dataType.Value;
    } 

    private string GetNull(IStereotypeInstance column)
    {
        IStereotypePropertyInstance allowNulls = column.PropertyInstances.Where(p => p.Name == “AllowNulls”).First();
        return bool.Parse(allowNulls.Value) == true ? string.Empty : ” not null”;
    } 

    private string GetIdentity(IStereotypeInstance column)
    {
        IStereotypePropertyInstance isIdentity = column.PropertyInstances.Where(p => p.Name == “IsIdentity”).First();
        return bool.Parse(isIdentity.Value) == true ? ” identity” : string.Empty;
    }
#>

This code uses a foreach loop to iterate through the list of types owned by the Root model in our project and generates a create table script for each class. Notice the helper methods, such as GetSchema and GetDataType. They use AppliedStereotypes property of the model element to find the stereotype defined in our database profile, such as Schema or Column. Having found the stereotype instance, its properties properties are accessed through the PropertyInstances collection.

Here is the code generated by this text template from our UML model.

create table dbo.Customer
(
    FirstName nvarchar,
    LastName nvarchar,
    StreetAddress nvarchar,
    City nvarchar,
    State nvarchar,
    PostalCode nvarchar,
    Id int not null identity,
);
create table dbo.Product
(
    Name nvarchar,
    Price nvarchar,
    Id int not null identity,
);
create table dbo.Order
(
    Date nvarchar,
    TotalAmount nvarchar,
    Id int not null identity,
    CustomerId int,
);
create table dbo.OrderItem
(
    Id int not null identity,
    OrderId int,
    ProductId int,
);

UML vs. DSL

UML models are high-level abstractions, typically representing systems at conceptual or logical levels. This is an intentional, desired aspect, as it allows you to model a wide variety of of systems without tying the design to any particular platform or implementation. While high-level models serve as an excellent communication tool during envisioning and design phases, during implementation high-level models quickly become outdated, causing confusion. While automated code generation and reverse engineering of models is possible, the process is complex, fragile and requires additional effort.

Comprehensive support for UML is a significant change in direction of Microsoft’s approach to modeling. You may remember that when Domain-Specific Language tools were announced a few years ago, the emphasis was on practical application of modeling throughout the software development lifecycle. It was suggested that models should be considered equal to other source code artifacts, such as .cs/.vb files and .aspx pages. Typical DSL models are lower-level abstractions, representing a system at logical or physical levels. They are predominantly used for code generation and rely on partial classes and inheritance to avoid reverse engineering model information from code back to the model. Examples of DSL models in Visual Studio include LINQ to SQL and Entity Framework designers.

While these approaches to modeling appear to be different, in reality they complement each other, providing us with a full range of modeling capabilities from conceptual and logical, down to physical level. UML models are useful during early stages of a software development project and DSL models work best during implementation and maintenance of the system. It is interesting to note that UML models are actually implemented using DSL tools, so from Visual Studio prospective, UML is simply a DSL for the “unified modeling” domain.

Conclusion

As you can see, Visual Studio 2010 Ultimate Edition provides powerful UML modeling tools that can be used for conceptual and logical analysis during software development. UML Profiles can be used to extend standard models and allow modeling information systems at physical level. A limited number of UML profiles is expected to ship with Visual Studio 2010. Custom profiles can be developed to tailor UML models to the needs of individual projects. Combined with T4 Text Templates, this gives developers a powerful tools for model-driven development of information systems, where large portions of the system can be modeled in UML and generated with T4. 

References

• MSDN, Developing Models for Software Design
• Cameron Skinner, UML Profiles and Visual Studio 2010 Ultimate: Part One
• Istvan Novak, Deploying Visual Studio 2010 Extensions, Part 1
• Tim Fischer, How To: Generate Code from Team System UML Diagrams in VS 2010 Beta 2 
• Oleg Sych, Text Template Transformation Toolkit

Download

Source code

©2012 Oleg Sych. All Rights Reserved.

Design of Entity Framework has been inspired by the traditional methodology of relational database design which suggests creating a conceptual (class) model, transforming it into logical (relational) model and finally into physical database model. While these activities are typically performed during design and initial implementation of the information system, the Entity Framework implements the physical model, makes the conceptual model a first-class citizen and explicitly defines the mapping model.

• Conceptual model defines entities and their relationships from the application point of view. This model is defined using Conceptual Schema Definition Language (CSDL) and stored in a separate .csdl file or as part of a combined .edmx file in your project.
• Storage model defines entities and their relationships from the database point of view. This model is defined using Store Schema Definition Language (SSDL) and stored in a separate .ssdl file or as part of a combined .edmx file in your project.
• Mapping model defines how conceptual model translates into storage model. It is defined using Mapping Specification Language (MSL) and stored in a separate .msl file or as part of a combined .edmx file in your project.

The Entity Framework uses these XML-based models to transform create, read, update, and delete operations against entities and relationships in the conceptual model to equivalent operations in the data source. The storage and mapping models can change as needed without requiring changes to the conceptual model, data classes, or application code. Because storage models are provider-specific, you can work with a consistent conceptual model across various data sources. The Entity Data Model even supports mapping entities in the conceptual model to stored procedures in the data source.

What is wrong with this picture?

Entity Framework was designed to overcome the object-relational impedance mismatch and allow you to hide a difficult-to-use legacy database schema behind a modern, object-oriented entity model and make developers more productive. This description almost sounds to good to be true. Unfortunately, just like other frameworks designed to solve complex problems, the Entity Framework tends to make simple things difficult.

Having three separate database layers (or models) in the Entity Data Model means having each entity represented three times, each from a different point of view. Every time you need to make a change in your database model, which also needs to be implemented in the application, you have to make it three times. Take adding a new column to a table as an example. No matter in which order you do it, you still have to add a new property to the conceptual model, a new column to the storage model and a new mapping from one to the other. This task is tedious and error prone even with the best modeling tools imaginable. Unfortunately, Entity Framework designer limits you to a single diagram, which gradually becomes more difficult to use as the number of entities increases, becoming virtually useless when it exceeds 50.

In simplistic terms, this all means that Entity Data Model is three times as complex as a traditional database model. To implement all but trivial logic, either one developer has to understand all three models or you have to have two or more people involved in implementing it. In the end, you have to spend three times more effort to develop and maintain the EDM, you are three times more likely to make mistakes, i.e. the cost of having the EDM in your solutions is three times higher than the cost of a solution that uses a single hypothetical data model.

What is the alternative?

Majority of information systems in existence today are built using relational databases and data-oriented code. A tremendous amount of tooling, knowledge and experience has been developed over the past two decades by the industry, making low-cost development resources readily available. Although solving the object-relational impedance mismatch sounds very good in theory, in practice, the overall cost of such a solution is typically higher, in part due to additional effort required to maintain three separate database models and in part due to additional knowledge and experience required from developers.

However, the existing as well as new information systems could benefit tremendously from having a modern, strongly-typed, LINQ-enabled, automatically generated data access layer (DAL). Such a DAL would allow to significantly reduce the amount of plumbing code developers have to write today with DbConnection, DbDataReader and DataSet classes without requiring significant changes to the application architecture. In other words, as long as the effort required to maintain such a DAL is less than the effort required to maintain the data access code manually, we can take advantage of the language and data access enhancements offered by the current version of the .NET framework while reducing the overall cost of the information systems.

Entity Framework DAL generator in T4 Toolbox

In order to implement an automatically generated DAL based on Entity Framework today, you would have to use EdmGen. Unfortunately, it does not give you access to some of the options supported by the framework. The new version of T4 Toolbox includes a code generator that encapsulates the functionality built into Entity Framework and makes it available in T4-based code generation scripts. This code generator is based on the idea of using database modeling tools built into Visual Studio, which are easier to use and unlike Entity Framework’s own designer, are proven to work on the number of tables typically found in real-world databases. In the rest of this article we will review the process of using this code generator to illustrate its pros and cons.

Getting Started

In order to follow this sample, you need to have Visual Studio 2008 or 2010, Standard Edition or higher, SQL Server Express 2005 or later, T4 Toolbox and T4 Editor installed on your computer.

• Create a new C# or Visual Basic console application project.
• Add a new item to your project and select the Code Generation->Entity Framework Database template in the Add New Item dialog.

• Enter the desired database name and click Add.

This template adds a new, empty SQL Express database to your project. Unfortunately, Visual Studio automatically displays the the Data Source Configuration Wizard whenever you add a .mdf file to a project. Normally, you would use it to create a data access layer with built-in visual designers. In this case, we have the entire data access layer generated automatically for us.

• Click Cancel in the Data Source Configuration Wizard.

Notice that a number of files have been added to your project, including a .mdf file (SQL database), a .ldf file (SQL log), a .tt file (code generator), a .cs/.vb file (entity classes and object context), a .Views.cs/.vb file (precompiled entity views), a .csdl file (conceptual model), a .ssdl file (storage model) and a .msl file (mapping model). If you are using Visual Basic, you will need to click "Show All Files” button in solution explorer in order to see the files nested under .mdf and .tt.

Database Modeling

Visual Studio includes a subset of database modeling functionality from SQL Server Management Studio, including database diagrams, table designers, key and relationship designers.

• Double-click the .mdf file in Solution Explorer (shown above). This will cause the database to be opened in Server Explorer (shown on the left).
• Right-click Database Diagrams in Server Explorer and select Add New Diagram from the context menu.
• The first time you add a diagram to a database, Visual Studio will prompts you to create database objects required for diagramming. Click Yes when prompted.

Use the diagram to create a new database model.

Database diagrams allow you to quickly model tables and their relationships. You can use the Properties Window of Visual Studio to configure individual tables and columns selected on the design surface. The toolbar and context menu provide access to commands that allow you to model keys, relationships, indexes, unique and check constraints, as well as customize the look of your diagram for display and print, add text annotations and more. Also, unlike with Entity Framework designer, you can create additional diagrams when the number of tables is too big to fit on a single diagram. This seemingly trivial feature is crucial for large database models.

Having the model database included in your project has several important benefits. It is placed under source control with the rest of the files in your project, giving you the ability to go back to previous versions when necessary. Although it may seem excessive to check in an entire database in source control, the size of a .mdf file is comparable to the size of a similar database model stored in a Visio .vsd file or an Enterprise Architect .eap file. You can also use the database file itself to store any seed data you need and with “Copy to Output Directory” option turned on, the database deployment becomes a simple xcopy on greenfield projects.

• Make sure to save changes you make in any database diagram or designers you open before you proceed to the next step of generating code.

Code Generation

• Double-click the .tt file in Solution Explorer (shown above) to open it in the T4 Editor.

C#

<#@ template language="C#" hostspecific="True" #>
<#@ output extension="cs" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="T4Toolbox\EntityFramework.tt" #>
<#
    var generator = new EntityFrameworkGenerator();
    generator.DatabaseFile = "Database1.mdf";
    generator.Run();
#>

VB

<#@ template language="VB" hostspecific="True" #>
<#@ output extension="vb" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="T4Toolbox\EntityFramework.tt" #>
<#
    Dim generator As New EntityFrameworkGenerator()
    generator.DatabaseFile = "Database1.mdf"
    generator.LanguageOption = LanguageOption.GenerateVBCode
    generator.Run()
#>

This is a T4 code generation script that creates a new instance of EntityFrameworkGenerator, configures its properties and uses it to generate all model and code files required for a ready-to-use data access layer based on Entity Framework. Note that this script is not directly associated with the database file in the Visual Studio project and has to be run manually.

• Right-click the .tt file in Solution Explorer and select Run Custom Tool from its context menu to trigger the code generation.
• Double-click the  generated .cs/.vb file in Solution Explorer to open it in the Visual Studio editor. If you are using Visual Basic, you will need to click “Show All Files” in the toolbar of Solution Explorer in order to see this file.

C#

VB

This generated file contains definitions of both entity classes and object context required to access the database using LINQ to Entities.

Also note the other generated code file, in our example Database1.Views.cs/.vb. This file contains pre-generated views, which significantly improve reduce the amount of time required to connect to a database using an Entity Framework object context for the first time. This can take tens of seconds even on a medium-size database with a hundred of tables. While this performance hit does not have a meaningful effect on applications in production due to Entity Framework caching the views on per-AppDomain basis, this delay is a significant problem for developers who need to recompile and restart the application frequently. The Entity Framework designer does not generate views automatically, causing much frustration for developers and, perhaps, being the main reason for Entity Frameworks reputation of having poor performance.

Coding

At this point, you have everything you need to start coding against your new database using LINQ to Entities.

• Double-click Program.cs or Module.vb in Solution Explorer.
• Enter the following code in the editor.

C#

using System;
using System.Linq; 

namespace EfDalSampleCS
{
  class Program
  {
    static void Main(string[] args)
    {
      var context = new Database1Entities();
      context.AddToProducts(new Product() { ProductName = "Internet Explorer", UnitPrice = 0 });
      context.AddToProducts(new Product() { ProductName = "Windows 7 Ultimate", UnitPrice = 319.99M });
      context.SaveChanges(); 

      var products = from p in context.Products select p;
      foreach (var product in products)
      {
          Console.WriteLine("{0} ({1})", product.ProductName, product.UnitPrice);
      }
    }
  }
}  

VB

Imports System
Imports System.Linq
Imports EfDalSampleVB.EfDalSampleVB 

Module Module1
    Sub Main()
        Dim context As New Database1Entities
        context.AddToProducts(New Product() With {.ProductName = "Internet Explorer", .UnitPrice = 0})
        context.AddToProducts(New Product() With {.ProductName = "Windows 7 Ultimate", .UnitPrice = 319.99})
        context.SaveChanges() 

        Dim products = From p In context.Products Select p
        For Each product In products
            Console.WriteLine("{0} ({1})", product.ProductName, product.UnitPrice)
        Next
    End Sub
End Module 

 

• Press F5 to run the program. You may want to set a breakpoint and observe execution of the program in Visual Studio debugger.

A couple of things are worth explaining. How does this code know which database to connect to? The answer lies in the default constructor of Database1Entities class, which is generated to use a connection string with the same name. This connection string was automatically added to the configuration file when we added Database1.mdf to our project.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="Database1Entities"
      connectionString=
      "
        metadata=res://*/Database1.csdl
                |res://*/Database1.ssdl
                |res://*/Database1.msl;
        provider=System.Data.SqlClient;
        provider connection string=
        ‘
          Data Source=.\SQLEXPRESS;
          AttachDbFilename=|DataDirectory|\Database1.mdf;
          Integrated Security=True;
          User Instance=True
        ‘
      "
      providerName="System.Data.EntityClient" />
  </connectionStrings>
</configuration>

Metadata section of the connection string specifies that .csdl, .ssdl and .msl files are embedded as resources in the executable. Provider section of the connection string instructs Entity Framework to use ADO.NET SQL Client to connect to the database. The provider connection string section contains the traditional connection string and indicates that SQL Server Express edition will be used to automatically attach the database file located in DataDirectory. For windows applications (such as the console app we have here), DataDirectory token refers to the directory where the  executable is located. Our database file is copied to the output directory because the “Copy to Output Directory” option was set to “Copy Always” for the .mdf file in our project.

Customizing the list of database objects exposed by DAL

You may have noticed that among the generated entity classes, we also have sysdiagrams, which was actually the table created by SQL Server when we added the first diagram to our database. Unless you are planning to access this table from your application, it would be best to remove it from the data access layer. You can can do that by adding a filter to the code generator.

• Add the following code to the .tt file before generator.Run() method is called.

C#

  generator.Filters.Add(
    new EntityStoreSchemaFilterEntry(
      null,   // catalog
      null,   // schema
      "sys%", // name
      EntityStoreSchemaFilterObjectTypes.Table,
      EntityStoreSchemaFilterEffect.Exclude));

VB

  generator.Filters.Add( _
    New EntityStoreSchemaFilterEntry( _
      Nothing, _
      Nothing, _
      "sys%",  _
      EntityStoreSchemaFilterObjectTypes.Table, _
      EntityStoreSchemaFilterEffect.Exclude))

This code creates a filter entry object that indicates that all tables whose name starts with “sys” should be excluded from the generated DAL. EntityFrameworkGenerator class contains a property called Filters to which you can add one or more filter entries and make sure that only appropriate database objects are accessible through the DAL. For complete details, please refer to EntityStoreSchemaFilterEntry, EntityStoreSchemaFilterObjectTypes and EntityStoreSchemaFilterEffect on MSDN.

Unfortunately, not all of the possible combinations of object types and filter effects are supported by the underlying Entity Framework generator. For example, creating a filter entry to include functions in the DAL has no effect because the functions are only automatically generated in the storage model (.ssdl) and not in the conceptual model (.csdl). In other words, you cannot access stored procedures using the DAL produced by this code generator in its current version.

Customizing pluralization of entity class names and set names

Entity Framework 4.0 in Visual Studio 2010 provides an option to automatically convert table names to singular form in names of entity classes and to plural form in names of entity set properties. Without this automatic conversion, both entity name and set name would be either in plural form or singular form, depending on the naming convention you use in your database model. This poses a significant limitation in Entity Framework 3.5 in Visual Studio 2008, making the resulting DAL more confusing. A complete discussion of pluralization by the Entity Framework team is available on their blog.

The code generator in T4 Toolbox has the pluralization turned on by default in Visual Studio 2010. If you need to generate the DAL without pluralization, perhaps for compatibility reasons, you can turn this option off by adding the following line to the .tt file before generator.Run() method is called.

C#

  generator.Pluralize = false;

VB

  generator.Pluralize = False

This option is not available in Visual Studio 2008 because the underlying code generator in Entity Framework does not support it.

Customizing generation of foreign key properties

Entity Framework 4.0 in Visual Studio 2010 also provides an option to generate and use foreign key properties (such as Order.ProductId) in addition to navigation properties (such as Order.Product). Detailed discussion of foreign key properties is also available on the Entity Framework team blog.

The code generator in T4 Toolbox offers an option to generate foreign key properties, however you need to turn it on explicitly, by adding the following line to the .tt file before generator.Run() method is called.

C#

  generator.GenerateForeignKeyProperties = true;

VB

  generator.GenerateForeignKeyProperties = True

This option is not available in Visual Studio 2008 because the underlying code generator in Entity Framework does not support it.

Customizing location of the model database

When storing the model database under source control is not desirable on your project, you can change the code generator to use a standalone database as the model.

• Change the .tt file to specify a connection string instead of the database file.

C#

<#@ template language="C#" hostspecific="True" #>
<#@ output extension="cs" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="T4Toolbox\EntityFramework.tt" #>
<#
  EntityFrameworkGenerator generator = new EntityFrameworkGenerator();
  generator.ConnectionString = "Server=.;Database=Northwind;Integrated Security=True";
  generator.Run();
#>

VB

<#@ template language="VB" hostspecific="True" #>
<#@ output extension="vb" #>
<#@ include file="T4Toolbox.tt" #>
<#@ include file="T4Toolbox\EntityFramework.tt" #>
<#
  Dim generator As New EntityFrameworkGenerator()
  generator.ConnectionString = "Server=.;Database=Northwind;Integrated Security=True"
  generator.LanguageOption = LanguageOption.GenerateVBCode
  generator.Run()
#>

When you save the modified .tt file, the DAL will be regenerated based on the metadata in the database you specified in the connection string. By default, database name determines the name of the generated object context class. Changing the name of the database from Database1 to Northwind will change the name of the context class from Database1Entities to NorthwindEntities.

• Rename the .tt file to match the name of the database (Northwind.tt in our example).

Although this is not required, renaming the code generation script will make the names of the generated .csdl, .ssdl and .msl files match the name of the database and make the solution easier to understand.

• Update the configuration file to match the changes made in generated code.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <connectionStrings>
    <add name="NorthwindEntities"
      connectionString=
      "
        metadata=res://*/Northwind.csdl
                |res://*/Northwind.ssdl
                |res://*/Northwind.msl;
        provider=System.Data.SqlClient;
        provider connection string=
        ‘
          Server=.;
          Database=Northwind;
          Integrated Security=True;
        ‘
      "
      providerName="System.Data.EntityClient" />
  </connectionStrings>
</configuration>

In particular, the name of the connection string has to match the new name of the object context class (NorthwindEntities in this example); file names in the metadata section of the connection string have to match the names of the generated model files (Northwind.csdl, Northwind.ssdl and Northwind.msl in this example); and finally, the provider connection string section of the connection string has to point to the actual database in your current environment.

Note that database connection string is present in both .tt and .config files. In this example, the same Northwind database on local SQL server is used during both code generation and execution. You may want to use different databases for these purposes, perhaps an empty local database for code generation and a shared database for development and testing. In that case, make sure to use appropriate connection strings in the .tt and .config files.

Other customization options

Additional details about customization options are available in the T4 Toolbox documentation installed as part of the Visual Studio 2008 help collection. If you have it installed, you can click here to open the list of properties available for you to use in the code generation script.

Conclusion

ADO.NET Entity Framework allows you to access database in object-oriented manner at the cost of additional effort required to maintain conceptual, storage and mapping model. While sounding good in theory, solving the object-relational impedance mismatch in practice typically increases the cost of information systems due to additional knowledge, experience and effort it requires with tools available today. By implementing an automatically-generated, modern, strongly-typed, LINQ-enabled data access layer based on Entity Framework, we can improve developer productivity and reduce the system development cost without introducing the overhead and complexity of fully featured object-relational mapping. Unlike the tools built into Entity Framework, the database modeling functionality in Visual Studio and the code generator described in this article allow you to use Entity Framework effectively with more than just a few dozen tables. Unfortunately, due to limitations in the current version of Entity Framework, the solution described in this article does not allow accessing stored procedures and functions through the automatically generated DAL, making it inferior compared to a similar DAL based on LINQ to SQL today.

Download

Sample source code

©2012 Oleg Sych. All Rights Reserved.