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!

First of all, if you haven’t seen Conery’s five minute demo video on repository mode, you should. It’s very cool.  Once you watch it, you’ll get the basics of migration and understand the idea of building the object model first while using the database purely as a storage mechanism. In this case, I built my class, and I’m letting Migration handle all the schema generation for me. It will also create a new database file if one doesn’t already exist. That’s the idea right?

Setup Your Configuration File

For starters, don’t forget to download and install the System.Data.SQLite library first. I ran their Windows installer and it worked just fine. Then add a connection string to your config file. Be sure to set the ProviderName to  System.Data.SQLite. SubSonic uses the 2.0 provider model to determine the types required for the data connection.

<connectionStrings>
    <add name="TrackerConnectionString" connectionString="Data Source=Tracker.db3;" providerName="System.Data.SQLite"/>
</connectionStrings>

Create Your Data Classes

Create your storage classes. If you’re new to ORM/data layers, remember that each class definition represents a row in the database. In this case, I want a table called DSTFileTrackers with three columns: ID, Filename, and Imported. These are simple classes (other than the subsonic string length attribute). They don’t inherit from any other base class. A nice attribute not used here would be the [SubSonicIgnore] attribute. It will allow you to define other properties that you don’t want to store to the database like for example, read only properties.

public class DSTFileTracker
{
    public long ID { get; set; }

    [SubSonic.SqlGeneration.Schema.SubSonicStringLength(100)]
    public string Filename { get; set; }

    public bool Imported { get; set; }
}

Write Your Implementation

Lately, I’ve been playing a lot with ASP.NET MVC, I’ve been creating repository classes for my data objects.  They’re simple subject-matter classes that just handle business/data operations for a set of objects. In this case, I created one called TrackerRepository and implemented most of my SubSonic code there. Later on, I could build an interface for the repository and then set it up for unit testing or make it adaptable to switch to another data layer.

So here’s a sample calling code.

var tracker = _Repo.DSTFiles.Where(o => o.Filename == file.name).FirstOrDefault();
if (tracker == null)
{
    tracker = new DSTFileTracker();
    tracker.Filename = file.name;
    _Repo.SaveDSTFileTracker(tracker);
}

This save function below lives in my repository class. You can see how nice and clean these statements are. There’s a ton of potential here. Repository mode can do a lot of really cool stuff like deleting many records at once by expression or doing partial inserts and updates.

public void SaveDSTFileTracker(DSTFileTracker data)
{
    if (_Repo.Exists<DSTFileTracker>(o => o.ID == data.ID))
        _Repo.Update<DSTFileTracker>(data);
    else
        _Repo.Add<DSTFileTracker>(data);
}

So all in all it was pretty easy to do. You’ll notice I ran an existence check. The SimpleRepository doesn’t have this built into a save function like ActiveRecord, but it’s not a big deal to do manually.

Catching SubSonic Gotchas

This library is new and like all new libraries, you’ll run into a bug here and there. Hopefully as more and more people use it, the SubSonic community will become more aware of the bugs out there and can fix them.  I ran into a few myself just while doing this. These are mostly specific to the SQLite portion of SubSonic. They were all very easy to fix, and it’s very easy to submit your own patches. Checkout their GitHub demo video here.  You can access my branch directly for the fixed code. I've applied for a code pull, but it takes a few days and code review before they plug it into the main.

Update August 16th, 2010

I've recently beeing using SubSonic post 3.0.0.4 version with SQLite and MySql, and most of these issues have been resolved. I pulled down my version of the repository since it's very old. I highly recommened upgrading to the latest one, which should not require any code changes. Check out one of my more recent posts that discusses SubSonic and Mono

Here’s a few of the issues I ran into:

• SQLite’s auto-incrementing integer can only be 64bit [integer] rather than 32bit [int]. SubSonic will go and create the 64bit field during migration though; you just won’t see an error until you try to read it back. So if your ID property is an [int], change it to a [long].
• The default code for [bool] creates a tinyint field in SQLite.  I had to tweak the Subsonic code by changing it to use a bit.  When reading the values, it breaks because tinyint == Byte and SubSonic sets values to data properties by casting them directly to their actual type in the reader.
• When running an Update<T>, I get a NullReferenceException.  This is a bug in SubSonic and already has an issue posted. I submitted a patch for this.  It’s a simple column name mismatch in the update script generator.
• Just like in Linq to Sql when you do custom Lambda expressions with unrelated fields, it could cause problems. I was doing a funky Where(o=>o.Equals(y)) which blew up my stuff because the LINQ predicate expression couldn’t figure out how to parse Equals() and CompareTo() to SQLite syntax.  So keep it simple.