I’ve always been a big fan of SubSonic since its 2.0 version, which I used for a mid-sized e-commerce site. With a totally rewritten core, 3.0 uses LINQ (language integrated query) for all of its data access providing a great alternative to Dblinq for the Mono platform.

SubSonic3 supports ActiveRecord, Repository, and Custom Linq modes, which give you the flexibility to build code-first or database-first.  SubSonic3 is not an ORM (object relational mapping) like NHibernate, but it can behave like one when you use Repository Mode using POCO (plain old CLR object) representations of your tables. SubSonic handles the mapping and database query generation itself based on the database provider configured. Its intention is to allow you to build code-first and let the persistence of the object be non-critical to your application. It can even migrate your class definition changes (table schema) to the database automatically during runtime; however, it still has the flexibility to let you design your database with keys, indexes, and constraints yourself without using the automatic migration. The SubSonic website has a great demo showing this capability.

Database Independence

To make SubSonc3 truly database agnostic, you have to use Repository mode. Active Record and Custom Linq modes DO support multiple database engines, but they all require custom class generation which is hard-wired to those engines. So when you change database types like from MySql to MSSQL or vice-versa, you have to regenerate your classes.

With Repository mode, you simply change your connection string in the app.config. It will use the 2.0 Data Provider model provided by the database engine client and the definition of your POCO classes to determine the SQL syntax and schema to use.  SubSonic is pre-wired with MSSql, SQLite, MySql, and a generic ANSI Sql syntax support. There’s been lots of talk about implementing Oracle and PostgreSql, which may already work in ActiveRecord or LinqTemplates, but are not yet in the Core assembly for use with Repository.

Decoupled – Mocking for Unit Tests and Framework Independence

Another big advantage of Repository is the ability to decouple your data framework from your application completely. Since the POCO objects are not directly tied to SubSonic, they can be re-used with other frameworks like NHibernate or the latest Entity Framework 4 without touching a single line of application code. It also opens the door to mocking and testability. Dependency Injection frameworks like Unity or StructureMap work perfect for this.

So how about a sample?

This is a silly little test application that is neither pretty nor elegant, but it proves that this code will run on Mono 2.6.3 and 2.7 (trunk) with a SQLite database. It also uses Unity for dependency injection much like you would in Asp.NET MVC. Within the project, you’ll find an AppService interface used to provide the definition for simple ‘business’ functionality. This is meant to be generic for the sample; but in a real application, I would breakdown the services by functional purpose. They all can share the same LinqRepository data interface, which provides basic rules for LINQ-based CRUD. SubSonic3 hooks right into that and is nearly transparent to the application with the exception of a few attributes on the domain objects. There are some placeholder Mock classes there and sample mappings in the code just for show.

Download the sample project

You can also get the latest version from IWS Snippets project subversion.

After spending a day drilling into T4 and learning how it works, I have to say that it was definitely time not wasted. I’ve since used it for tons of miscellaneous code generation projects including mostly data layer extensions. And with the help of the data provider specific templates in the SubSonic project, much of the schema extraction code has been provided for us through open source.

I’m a big fan of SubSonic, and I like to push it in all the shops I work with that aren’t already anchored down to another data framework. However, sometimes we still have to fall back to vanilla data layers like Linq to Sql (L2S), Entity Framework (EF), or straight up ADO.Net depending on the shop and its personalities. Having experience using SubSonic opens your eyes to some useful ways you can improve L2S and the others.

Like, for example, updating data… Have you been in a situation (like a web form postback or a web service call) where you’re instantiating a new entity instance whose data already exists in your database and you need to simply update it?  In L2S, this isn’t very straight forward. If you don’t want to mess with detaching and reattaching data entities, you can simple load an instance from the data context and update its fields with the new data; then commit the change back to the data context.

Well that’s great and all, but who’s going to type all the load functions? Not me, I hate typing.   So T4 comes to the rescue.  Here you’ll see a simple script that looks at a database and generates LoadFromExisting() functions for each table into a partial class that extends the original L2S class. Then anytime the schema changes, you simply run the T4 template and it re-executes your generation code.

Using the Generated Code

Here’s an example helper save function using Linq to Sql.  It simply checks for an existing record. If it exists, it updates its fields with the ones you passed in making it dirty to the data context, or it instructs the data context to insert it as a new one.

public void SaveSection(Section section)
{
    var data = this.GetSectionByID(section.ID);

    if (data == null)
    {
        data = section;
        _DB.Sections.InsertOnSubmit(data);
    }
    else
        data.LoadFromExisting(section);

    _DB.SubmitChanges();
}

Here is the corresponding LoadFromExisting() definition. You can see it’s very simple. All I really want to do here is update the values and flag the fields on the instance we pulled from the data context as dirty. The main thing to note here is that the class definition is partial.  It matches the namespace and name of the class generated in our DBML data context file.

public partial class Section
{

    public Section LoadFromExisting(Model.Section data)
    {
        this.ID = data.ID;
        this.DefaultContentID = data.DefaultContentID;
        this.Description = data.Description;
        return this;
    }

}

Now for Actually Generating Code with T4

To briefly explain T4, it’s basically a .net virtual machine hosted by visual studio. The code files appear a lot like classic ASP and MVC where you have rendered sections and functional sections. In T4, the token used to start and end a code section is: <# #>.  Like asp, you can include other files to re-use code files. Those files in this example have the ttinclude extension. Normal T4 scripts must end with the “.tt” extension.

Since we’re using what has already been setup for us by the SubSonic templates, we’re re-using their shared files: Settings.ttinclude and SqlServer.ttinclude. The settings.ttinclude file has all your basic shared settings like the global directives, includes, references, and supporting object model for the database structures. The SqlServer.ttinclude file contains the Sql Server specific schema extraction functions.

Add both these files to your project, and then add a new text file with extension “.tt” to your project.  Copy the content from template.tt into your new tt file. The template content simply includes the shared files for you. Notice every time you save this file, it re-runs itself; so be very aware when you’re saving to avoid running the code accidentally.

Here’s the full script for the partial extension:

<#@ template language="C#v3.5" debug="True" hostspecific="True" #>
<#@ include file="SQLServer.ttinclude" #>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Data;
using System.Linq.Expressions;
using System.Collections;
using System.ComponentModel;
using System.Data.Common;

namespace <#=Namespace #>
{
<#

    var tables = LoadTables();

    foreach(Table tbl in tables)
    {
        if(!ExcludeTables.Contains(tbl.Name) && !tbl.Name.StartsWith("aspnet"))
        {
#>

    /// <summary>
    /// A class which represents the <#=tbl.Name #> table in the <#=DatabaseName#> Database.
    /// </summary>
    public partial class <#=tbl.ClassName#>
    {

            public <#=tbl.ClassName #> LoadFromExisting(Model.<#=tbl.ClassName #> data)
            {
<#
            foreach(Column col in tbl.Columns)
            {

                if (tbl.ClassName == col.CleanName)
                {
                    col.CleanName += "X";
                }
#>
                this.<#=col.CleanName #> = data.<#=col.CleanName #>;
<#
            }
#>
                return this;
            }

        }
<#
   }
  }
#>
}

So as  you can see, it’s very straight forward.  Here, we’re loading up all the tables, spinning through each one and then writing a function that spins its columns to generate assignment expressions.  (this.<#=col.CleanName #> = data.<#=col.CleanName #>; )  You’ll notice a few variable names being used like “Namespace” or ExcludeTables, etc.  With T4, you have to pretend that anything defined in a global scope is really just a member of this virtual class we created as our script. Those names were actually defined earlier in the Settings.ttinclude.  That is also where we’re setting our connection string name for the connection info. It uses the app.config in current project so you don’t have to save it statically in the file, which is another perk of these SubSonic templates.

For partial classes to work, you have to match the namespace and class name in your partial file. This is extremely useful, because I can generate code all day long with this file and then create yet another partial extension for the the more functional fine detail extensions.

Enum Generator

Here’s a nice little enum generator I wrote the other day. We typically use lookup tables in a lot of our projects whose names and values match what we have in our tables. This script uses a global list of table names in the Settings.ttinclude file and selects their data to generate enum code with values. The table structure is: (ID int, Name varchar(50), Description varchar(100)). You’ll need to create the table and fill it with your enumeration data first. Then run this script.

<#@ template language="C#v3.5" debug="True" hostspecific="True" #>
<#@ include file="SQLServer.ttinclude" #>
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Data;
using System.Linq.Expressions;
using System.Collections;
using System.ComponentModel;
using System.Data.Common;

namespace <#=EnumNamespace #>
{
<#
            var list = GetEnums();
            foreach (KeyValuePair<string, List<EnumValue>> pair in list)
            {

            #>

        /// <summary>
        /// An enumeration that represents the table <#= pair.Key #> in database: <#= DatabaseName #>
        /// </summary>
        public enum <#=pair.Key#>
        {
<#            int counter = 0;
            foreach(var value in pair.Value)
            {
                counter++;
                if (!string.IsNullOrEmpty(value.Description)) {#>
            /// <summary>
            /// <#= value.Description #>
            /// </summary>
<# } #>            <#= value.Name #> = <#= value.Value #><#if (counter < pair.Value.Count) {#>,<#}#>

<#            }#>
        }

<#            }#>
}

In my case, I dropped these enumerations into a custom namespace since the names were shared with the entities representing the tables.  If you wanted to, you could easily drop these into a class as well.

Download

Here’s the zip file containing the four scripts.

Disclaimer/Licensing: All code provided here was derived using some of the code in SubSonic templates; hence, this code is open source under the same license. New BSD, which I’ve included in the downloadable archive.

Enjoy!