Conforming to Your Database

So first off: naming. SubSonic3 repository assumes that all your tables are pascal-cased and pluralized. So if you use a vanilla domain class against your database, it will only work with tables matching that naming pattern. Be aware that these attributes help determine the database properties; not the .NET runtime behavior of your application.  For example, a StringLength attribute will instruct SubSonic to setup a varchar column with a defined length, but your .NET runtime will still use a String type and will still accept values longer than the associated database column.  Here are the attributes you can use to tailor your classes to your database.

SubSonic.SqlGeneration.Schema including:

• [SubSonicDefaultSetting] – set a default value
• [SubSonicIgnore] – Ignore a property or field
• [SubSonicLongString] – ntext or text field
• [SubSonicNullString] – Nullable varchar or text
• [SubSonicNumericPrecision] – decimal with specific precision
• [SubSonicPrimaryKey] – override primary key (use for primary key properties not named “Id”)
• [SubSonicStringLength] – varchar custom length (use when length is not 50)
• [SubSonicTableNameOverride] – override table name mapping for class
• [SubSonicToManyRelation] – for one to many foreign key property mappings
• [SubSonicToOneRelation] – for one to one foreign key property mappings

For the most part, you will use the TableNameOverride attribute to make your classes work with their corresponding tables. However, at times you will need to use the PrimaryKey if you don’t use “ID” as your primary key. The rest are extremely handy as well especially when it comes to null strings, text fields, and properties you want to ignore completely from the SQL translation to your database. Here is a sample class from an existing application:

[SubSonicTableNameOverride("effect")]
public partial class Effect
{
    public int Id { get; set; }
    public int SiteId { get; set; }
    public int? EffectTypeId { get; set; }
    public bool ApplyDefault { get; set; }
    [SubSonicNullString]
    [SubSonicStringLength(100)]
    public string Name { get; set; }
    [SubSonicNullString]
    [SubSonicStringLength(500)]
    public string Description { get; set; }
}

Here, I use Id for my primary key, so it is not necessary to add the PrimaryKey attribute.  I did use a NullString operator for a couple fields here that don’t require values. On a side-note, one of the philosophies behind requiring the NullString attribute and not simply assuming all strings are nullable is that the authors believe it’s more useful to use empty strings in place of null values because it alleviates many other issues down the road.  While I don’t disagree, I still tend to use nullable strings out of habit. You can read more about their conventions from the SubSonic Tome

Domain Class Generator

To get up and running quick, I built a simple domain class generator with T4 that writes out basic structures from an existing database repository-mode-friendly format. To run it, copy the files: Settings.ttinclude, SqlServer.ttinclude (or db specific ttinclude), and this Entities_Intial.tt file into your project folder. (Don’t add them to your visual studio project just yet).  Edit the Settings.ttinclude file and customize your namespace, connection string, and database name fields. 

Then include the Entities_Initial.tt file to your project. When you include this file, it will automatically attempt to run with your settings. It should separate each class into its own file. It will also generate a file for the core Entities_Initial that you can safely delete.  (NOTE: To re-run the generation after including it to your project, right-click the Entities_Initial.tt file and select “Run Custom Tool”).

Copy these files to another folder in your project to prevent them from being accidentally overwritten with another generation. Unlike the generated partial classes of ActiveRecord and LinqTemplates where you maintain a partial extension, you want to maintain these domain classes directly because they truly should stand alone from the framework you’re using.  Managing them like this gives you direct control over the properties and attributes in your domain model.  You should also be able to use these classes with other IOC frameworks like NHibernate. (Granted… To drop the SubSonic reference, you will need to drop all the attributes at the same time).

Entities_Intial.tt

<#@ template language="C#v3.5" debug="True" hostspecific="True" #>
<#@ include file="SQLServer.ttinclude" #>
<#
    var list = LoadTables();
    foreach (Table table in list)
    {
#>
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;
using SubSonic.SqlGeneration.Schema;

namespace <#=Namespace #>
{
    [SubSonicTableNameOverride("<#=table.Name#>")]
    public partial class <#=table.CleanName#>
    {
<#
        foreach(Column col in table.Columns)
        {
            if (col.IsPK && col.CleanName.ToLower() != "id")
            {
#>        [SubSonicPrimaryKey]
<#            }

            var nullableNonString = string.Empty;
            var nullableString = string.Empty;
            if (col.IsNullable && col.SysType != "string")
            {
                nullableNonString = "?";
            }
            if (col.SysType == "string"){
                if (col.IsNullable)
                {
#>        [SubSonicNullString]
<#                }
                if (col.DataType == "text")
                {
#>        [SubSonicLongString]
<#                }
                else
                {
#>        [SubSonicStringLength(<#=col.MaxLength#>)]
<#                }
            }
#>        public <#=col.SysType#><#=nullableNonString#> <#=col.CleanName#> { get; set; }
<#
        }
#>
    }
}
<#    SaveOutput(table.CleanName + ".cs");
    }
#>
}

You can download the original script and its references directly or get the latest version from my snippets project on GitHub. I used the base elements of the T4 scripts from the SubSonic-Templates project for this. Currently, they only support MySql, Sql Server, and Sqlite databases.

Enjoy!

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!