Summary== Sometimes you have a routine that needs to make multiple calls to a database, which can be a bit of a drain on resources if you're opening/closing connections each time. This can happen when running multiple pass-through queries (UPDATES, INSERTS, DELETES) or if you need multiple different result sets. BatchQuery can help in this regard - allowing you to execute multiple pass-throughs in a single transation or as a single statement. You can also execute SELECTs using multiple result sets. ==Considerations== Sometimes it's not a good idea to return multiple result sets, or to execute multiple queries, using a single connection. This section discusses some things to consider. If you batch together multiple calls into a single SQL statement, you can inadvertantly hold open a connection to your database for longer than you desire. This can end up in optimistic locking problems, or, if you're using something like SQLite, can lockup your entire database, causing issues for your application. Finally, some providers don't allow you to use multiple result sets (called MARS). You should find out from your provider if it supports multiple return sets. In addition, concurrency issues can creep up if the calls are not executed fast enough. Use this feature with caution. ==Creating a Batch Query== To create BatchQueury, you need to create a provider (which is a glorified connection string wrapper) and then a BatchQuery:var provider=ProviderFactory.GetProvider("Northwind"); var batch=new BatchQuery(provider); ==Executing Multiple Selects

Once you have created your BatchQuery, you can now "queue" the queries you want to execute in one call. The BatchQuery will translate each query into a single SQL statement, executed with one command:
var provider=ProviderFactory.GetProvider("Northwind"); var batch=new BatchQuery(provider); var query1=from p in db.Products where p.ProductID

1 select p; batch.Queue(query1); var query2=from p in db.Products where p.ProductID

2 select p; batch.Queue(query2); using(var rdr=batch.ExecuteReader()){ if(rdr.Read()){ //query1 results } rdr.MoveNext(); if(rdr.Read()){ //query2 results } } You can queue IQueryable or .

Executing Multiple Pass-through Queries== There are 2 ways to do this - with a transaction or without. ===Using a Transaction=

Probably the best way to execute multiple updates at once is to use a transaction to be sure that every update goes through. To do this, work up your query and use "QueueForTransaction()":
var provider=ProviderFactory.GetProvider("Northwind"); var batch=new BatchQuery(provider); var query1= new SubSonic.Query.Update(provider) .Set(x => x.CategoryID

5) .Set(x => x.UnitPrice == 100) .Where(x => x.ProductID == 1); batch.QueueForTransaction(query1); var query2= new SubSonic.Query.Update(provider) .Set(x => x.CategoryID == 1) .Set(x => x.UnitPrice == 200) .Where(x => x.ProductID == 2); batch.QueueForTransaction(query2); //execute transaction batch.ExecuteTransaction(); ===Using a Single SQL Statement=

You can write the same queries above, however insteading of using "QueueForTransaction" you can just use "Queue" and then when it comes to execution, just use "Execute()". This will produce the following SQL:
UPDATE [dbo].[Products] SET [dbo].[Products].[CategoryID]=5, [dbo].[Products].[UnitPrice ]=100, WHERE [dbo].[Products].[ProductID ]=1; UPDATE [dbo].[Products] SET [dbo].[Products].[CategoryID]=1, [dbo].[Products].[UnitPrice ]=200, WHERE [dbo].[Products].[ProductID ]=2

Distinct is used by appending the "Distinct()" method on a query:[Test] public void SqlQuerywhensettingdistinctitshouldsetIsDistinct() { SubSonic.SqlQuery query= new Select(Product.SupplierIDColumn).From().Distinct(); Assert.IsTrue(query.IsDistinct); } [Test] public void SqlQueryshouldhandledistinct() { ProductCollection select = new Select(Product.SupplierIDColumn).From().Distinct() .ExecuteAsCollection(); Assert.AreEqual(29, select.Count); } [Test] public void SqlQueryGetRecordCountshouldhandledistinct() { int select = new Select(Product.SupplierIDColumn) .From().Distinct() .GetRecordCount(); Assert.AreEqual(29, select); } Hate to say this, but I have seen this misstated MANY times. The SubSonic SqlQuery object does NOT have a Distinct method in it. It NEVER has. Even with the release of 3.x it does not have a Distinct method. The old Query object did but not the SqlQuery object. Unless someone you work with wrote one. Which is easy enough to do. I have done that myself. Download the latest source and you will see, the SqlQuery object does not have this functionality, there are many other short comings of the SqlQuery object that I won't get into, but if you know enough about it, you can write your own methods to overcome its faults.

SubSonic 2.x== Subsonic 2.2 Currently supports 5 main database engines: *SQL Server (2000 through 2008) *MySQL (5.0+) with special support for InnoDB *Oracle - although we've had reports of some issues with Foreign Keys and Stored Procedures *SQL CE (Compact Edition) *SQLite We develop everything using SQL Server 2005, so you might fight an optimal experience using this with SQL. ==SubSonic 3.0== ===Currently supported=

SubSonic supports and has templates for: *SQL Server (2000-2008) *MySQL (5.0 +) *SQLite *Oracle support through ODP.NET is currently in development. You can get the latest version of the SubSonic core from . The templates are also available . Please post details of any issues or questions to the is currently in development. You can get the latest version of the SubSonic core from . The templates are also available . Please post details of any issues or questions to the .

=What about other databases?=

Our goal with SubSonic 3.0 was to unhinge the core from any dependency on a specific engine. We do this by using System.Data.Common - which is part of Microsoft's DataFactory stuff. Most major databases have a provider which works with System.Data.Common - including: *PostGres *SQL CE *VistaDB SubSonic will execute queries against these databases, however we're still working on creating a meaningful set of templates for each. It's important to understand that SubSonic 3.0 talks to the database when creating your Data Access stuff using our , SQL Server will return a completely different result set than MySQL. This is supposed to be a standard - but there are obviously deviations with each provider. Our SQL Server templates query INFORMATION_SCHEMA - an ANSI-standard set of system views that each provider should offer for each database. However MySQL doesn't implement them in the same way SQL Server does - so we can't provide a "single template fits all" scenario. It's our hope that our - so if you take the time to create a nice set of templates - please add to our wiki!

Summary== SubSonic 3.0 is the latest version of SubSonic and was released in June of 2009. Work on SubSonic 3.0 lasted close to a year, and revolved mostly around supporting Language-integrated Query, also known as LINQ. The focus of SubSonic 3.0 is to provide tools, not guidance or an overall mindset/approach. There are a number of things in SubSonic that allow you to move faster while applying whatever patterning floats your boat. We're not as complete as NHibernate, but you'll work faster with less concept count. We're not as deep as Linq to SQL, but you can use our stuff on most databases. ==Linq

SubSonic 3.0 supports Linq with a core Expression Parser that turns System.Linq.Expressions into SQL. In addition, our 2.0 Query Tool (now called can use Lambda expressions to simplify some tasks. All of the templates we use build on top of our core parsers and query tools, and you can of these quite easily.

Simple Query Tool

The " method that will execute a query and load an object for you.

Utilities

SubSonic also comes with a number of utility methods expressed as Extension Methods. This is SubSonic's and has a number of things to save you time, including File IO, string methods, date math, number utilities, and Object parsing.

API Reference

This is a list of all the public assembly. The details have not been written in most cases - feel free to contribute. This is intended as an aid to navigating the documentation and linking code examples together.

Summary== Transactions are a core need for many application developers and involve executing a set of directions in a "all or nothing" manner - meaning that if one instruction fails - the whole thing fails. ==Considerations== The easiest thing to do is to use System.Transactions to wrap a "TransactionScope" around whatever it is you're doing. To make this work, however, you'll need to have the Distributed Transaction Coordinator (DTC) running on your server. You can get around this, however, by "suppressing" the "elevation" to DTC (which ADO will do for you if it's confused as to what's needed) by using our "SharedDbConnectionScope" (see below). ==Example of Using Scope== Executing Transactions using SubSonic is a matter of wrapping a scope around a section of code (using System.Transactions):using (SharedDbConnectionScope sharedConnectionScope = new SharedDbConnectionScope()){ using (TransactionScope ts = new TransactionScope()) { Product p = new Product.SingleOrDefault(x=>x.ProductID==1); p.Title = "new title"; Product p2 = new Product.SingleOrDefault(x=>x.ProductID==2); p.Title = "another new title"; // ... p.Save(); p2.Save(); ts.Complete(); } } ==Using Built-in Methods

There are other ways of working with transactions in SubSonic, and if you're worried about using the DTC then you might want to consider using the built in tools, specifically the .

Summary

For testability, SubSonic 3.0 now includes an IRepository interface that you can extend via T4 Templates. The Repository is pretty straightforward:
public interface IRepository { IQueryable GetAll(); PagedList GetPaged(Expression> orderBy, int pageIndex, int pageSize); IQueryable Find(Expression> expression); void Add(T item); int Update(T item); int Delete(T item); int Delete(object key); int Delete(Expression> expression); T GetByKey(object key); } This interface is implemented in SubSonic.Core.dll. You will find this interface as well as an implementation - SubSonicRepository - in the SubSonic.Repository namespace.

Screencast

Setting up and you're good to go. Here's a walkthrough: SubSonic3_5MinuteDemo.flv

Walkthrough

Setting up in your project is meant to be silly simple. Here are the steps, in order: #Create a new project in Visual Studio 2008 #Add a connection string to your Web/App.config, give it a name, and point it to a valid database #Grab the folder containing the and locate the one that named "_Settings". Open it up in Notepad and set the value for "ConnectionStringName" to the name of the connection string you just made. #Drop the folder with the templates into your project. Visual Studio 2008 will see these and execute the template code, creating your classes #You're done - go have a Kabob.

Summary

is the simplest, easiest way to work with your data and your database. The pattern is that each instance you work with is, literally, a row of data in your database. This means that each object type can be thought of as a table in your database. Many developers don't like to work this "closely" with their database - however others view this kind of thing as absolutely ideal - removing the object-oriented "impedance mismatch" in favor of working with a thin database abstraction. SubSonic's approach to is to give you what you need, then get out of your way. You'll find you have the ability to use Linq and simple, easy code-generation to get your data quick and simple-like.

Setup

Setting up SubSonic's is pretty simple and involves four steps.

=Add a Reference to SubSonic=

Download and extract in a folder like this. Then inside your project right-click the "Reference" folder, and select Add Reference. Browse to find the SubSonic.Core.dll file and include it.

=Add a Connection String=== In order to work with your database you'll need a connection string that is located in your project's app.config or web.config. If you have a seperate project for your data access code, you may need to create a new app.config in the root of the project. If you're working with a provider other than SQL Server (such as SQLite), you'll need to specify which one by changing the "providerName" attribute value: ... ===Set The Connection In The Templates=

Look in the Templates folder in the files extracted earlier. The Templates that create the classes you're going to work with need to know what your connection string is. To set this, open up the file called "Settings.ttinclude". Below the @import statements, you'll see three string values you'll need to change:
const string Namespace = "Northwind.Data"; const string ConnectionStringName = "Northwind"; //This is the name of your database and is used in naming //the repository. By default we set it to the connection string name const string DatabaseName = "Northwind"; "Namespace" refers to the namespace that the generated subsonic code will be placed under.
namespace Northwind.Data { public class YourEntity { ... } } You need to fill out "ConnectionStringName" with the connection string value that you placed in your app.config or web.config file earlier. This tells SubSonic which connection to use in the DB. Change the "DatabaseName" value to the name of the database specified in the connection string. The include directive in all *.tt files need to match your database. The ActiveRecord.tt on GitHub master, as of this writing, points to MySQL.ttinclude.
// other values: MySQL.ttinclude, SQLite.ttinclude <#@ include file="SQLServer.ttinclude" #>

=Add the T4 Templates To Your Project=== After you've set the settings above, just drag into your project. Whenever Visual Studio 2008 sees a "tt" file, it will automatically execute it - so you don't have to do anything, it will just run. List of files to drag: * ActiveRecord.tt * Context.tt * Settings.ttinclude * SQLServer.ttinclude OR MySQL.ttinclude OR SQLite.ttinclude * StoredProcedures.tt - optional, add if you will invoke stored procedures * Structs.tt If you make a change to your database, just right-click the ActiveRecord.tt, Context.tt and Structs.tt files (CTRL+Click to select all *.tt files) and select "Run Custom Tool" and this will execute them again. If you have any errors at this point, you need to check your settings in the prior step. ==Querying

The whole point of using ActiveRecord is to make querying easy. Here are some examples from our unit tests:
//find a single product by ID var product = Product.SingleOrDefault(x => x.ProductID

1); //get a list of products based on some criteria var products = Product.Find(x => x.ProductID <= 10); //get a list of server-side paged products var products = Product.GetPaged(0,10); //query using Linq var products = from p in Product.All() join od in OrderDetail.All() on p.ProductID equals od.ProductID select p; You'll notice that we've departed a bit from the way SubSonic 2.0 works (as well as other ActiveRecord libraries). Most other libraries use the constructor to pass in the key or name/value pair to find a single record. This can lead to some confusion if there is no record as your object will not be null (as it should be). For this reason we use a Factory to get single values - as you can see above. ==Testing

Testing with ActiveRecord can be a major pain because it lives "so close" to your database. Rails uses the concept of a Test Database for this - basically saying "get over it" with respect to involving your DB in your unit tests. This can work fine for you - if you want to use a test database you can and ActiveRecord will work fine. To do this, simply set your connection string in your test project (in the App.config) to point to your test database, and you're good to go. If you want to have speedier tests with less of a chance of failure due to bad data or connection issues - you can work with SubSonic's built-in testing (for ActiveRecord). There's nothing you need to do other than use the connection string "Test" in your test project:
This will tell SubSonic to use a Faked up repository (called TestRepository) which works with a fake set of data. You can set this up as you like using Setup():
//add 100 products to the fake repository Product.Setup(100); //make sure they're there! Assert.Equal(100,Product.All().Count()); You can also send in the list you want to work with if you want to mock up specific objects. See the constructor overloads for an example. You will be working against an in-memory List at this point (based on Setup()), so saving/deleting/editing will add/delete objects in the same way you would see with a database.

Changing generated table class names in SubSonic 3

Subsonic 2.0 had a feature that was modifiable via the webconfig called stripTableText that allowed you to modify the generated class names used by SubSonic. While not instantly obvious doing the same thing is even simpler and more powerful in subsonic 3 simply by editing the Settings.ttinclude file. The standard empty Settings.ttinclude file's CleanUp method: string CleanUp(string tableName){ string result=tableName; //strip blanks result=result.Replace(" ",""); //put your logic here... return result; } An simple example of the file edited to change into

string CleanUp(string tableName){ string result=tableName; //strip blanks result=result.Replace(" ",""); //strip the phrase "tbl" result=result.Replace("tbl",""); return result; } You soon see the simple power for table name manipulation the templates allow.

Summary

Most data access libraries work from "the database outward" - meaning that one way or another your database tables are represented as objects in your application. This can work in many cases, but relational theory does not align with object-oriented programming, and you get into a hole which is commonly referred to as "the impedance mismatch". Many people like to work with classes and don't want to worry about the database implementation - freeing them to work as they want to work without opening up a database designer in order to model their classes. The objects they create a free of base classes and exist on their own, as plain-old CLR objects (also known as POCOs). If you're one of these people and you don't particularly care about the database structure - the is for you.

Screencast== Couldn't help myself... love to make these things... subsonic_migrations.flv ==Setup

Setting up the is part of the fun of using it in that all that's involved is adding SubSonic and a connection string. The focus is getting completely out of your way.

=Add a Reference to SubSonic=== This part is pretty simple: right-click your project, Add Reference, and Browse to find the SubSonic 3.0 dll. ===Add a Connection String=== In order to work with your database you'll need a connection string. If you're working with a provider other than SQL Server (such as SQLite), you'll need to specify which one using "providerName": You're done! ==Auto Migrations

One of the fun things about working with Rails is that you can build your DB from code and focus on your app. Many developers have found this very freeing (myself included). One drawback to it, however, was that you needed to learn the code for the Migration, and you needed to know how it worked. This, to me, was not a show-stopper in the least but I always wished Rails would "just know" and migrate stuff for me. This is what I'm trying to do with Auto Migrations using SubSonic. The goal here is if you set a flag in the SimpleRepository constructor, you can tell it to migrate your model for you - automatically creating and synchronizing your database for you. The key to this is setting the proper options in the constructor:
var repository=new SimpleRepository(SimpleRepositoryOptions.RunMigrations); Setting this to RunMigrations tells SubSonic to migrate your model object to the database whenever you try to access the database or save data.

=Migration Example=

Suppose you have an object called Post: public class Post{ public Guid ID {get; set;} public string Title {get; set;} public string Body{get; set;} } When you use this object with the SimpleRepository, assuming you've set the options to RunMigrations, it will create the tables you need: //create a new repository for BlogDB database, turning migrations on var repo=new SimpleRepository("BlogDB",SimpleRepositoryOptions.RunMigrations); var post=repo.Single(x=>x.Title="My Title"); In this example there is no post with this title, since there is no Posts table. The Single() method, however, will run the migration for you and will create the table - so there will be no error. When run for the first time, the following SQL will be executed prior to the SELECT: CREATE TABLE Posts NOT NULL, [Body] nvarchar(255) NOT NULL, ); ALTER TABLE [Posts] ADD CONSTRAINT PKPostsKey PRIMARY KEY([ID])"; Notice that the table name is pluralized (by convention), the "ID" property is selected as the key (again by convention), and the strings are defaulted to a length of 255. You can change the way SubSonic creates the table by using a small set of attributes - specifically: * : If you call a column “ID” or “Key” or “[ClassName]ID” – no matter it’s type – that will be your Primary Key. If you have other things in mind you can use a primary key attribute (“SubSonicPrimaryKey”) and we’ll use that column. * : There are two ways to tell SubSonic how to handle this – both using attributes. The first is “SubSonicStringLength(int length)” and the second is “SubSonicLongString” which sets to nvarchar(MAX) or LONGTEXT – depending on your provider. * : The default is not null, but you can change this by making your property a nullable type. * : The default is a Precision of 10 and a scale of 2 but you can change that with the “SubSonicNumericPrecision(int precision, int scale)” attribute. * : you can ignore generation of a property by using “SubSonicIgnore” attribute.
Updating Your Model Starting out is the easy part, but as you develop you will be changing and removing properties from your class. SubSonic will do its best to keep up with you. For example, let's say you've added a PublishDate to your Post class: public class Post{ public Guid ID {get; set;} public string Title {get; set;} public string Body{get; set;} public DateTime PublishDate {get;set;} } When you next Save/Find/Get data using the SimpleRepository, the following command will be sent along first:
ALTER TABLE [Posts] ADD DateTime datetime NOT NULL CONSTRAINT DFPostsPublishDate DEFAULT ('01/01/0001'); UPDATE SubSonicTests SET PublishDate ='01/01/0001'; There are a few things happening here. The first is that the column is added for you (with NOT NULL - which you can change by using DateTime?). The second is that a default is put in place for you (using DateTime.MinValue) - a non-null column should have a default value in general (our convention). The UPDATE statement is there to deal with existing records that might be in the database already - setting their value to the default (for other providers like SQLite and MySQL). Continuing on - removing a property will result in the column being dropped from the database.

Querying

You can query your database through the repository quite easily, even using Linq if you like:
var repo=new SimpleRepository(SimpleRepositoryOptions.RunMigrations); //see if a record exists bool exists=repo.Exists(x=>x.Title

"My Title"); //use IQueryable var qry=from p in repo.All() where p.Title=="My Title" select p; //get a post var post=repo.Single(x=>x.Title=="My Title"); var post=repo.Single(key); //a lot of posts var posts=repo.Find(x=>x.Title.StartsWith("M")); //a PagedList of posts - using 10 per page var posts=repo.GetPaged(0,10); //sort by title var posts=repo.GetPaged("Title",0,10); //add a post var newKey=repo.Add(post); //add a lot of posts - using a transaction IEnumerable posts=GetABunchOfNewPosts(); repo.AddMany(posts); //update a post repo.Update(post); //update a bunch of posts in a transaction IEnumerable posts=GetABunchOfNewPosts(); repo.UpdateMany(posts); //delete a post repo.Delete(key); //delete a lot of posts repo. DeleteMany (x=>x.Title.StartsWith("M")); //delete posts using a transaction IEnumerable posts=GetABunchOfNewPosts(); repo.DeleteMany(posts); ==Testing

Testing with SimpleRepository is very simple as it inherits from SubSonic.Repository.IRepository. If you follow an injection pattern whereby you pass in an IRepository, then you can use your favorite mocking tool or create a fake repository to query against.

Summary

This demo shows off ActiveRecord - a very easy way to work with SubSonic. Don't miss the , however! SubSonic is all about helping you do what you need to do with the least amount of friction. No need to overthink things anymore - just build your app. SubSonic3_5MinuteDemo.flv

Summary

T4 stands for "Text Template Transformation Toolkit" and, simply put, is code generation inside Visual Studio. It's very easy to work with if you're familiar with scripting ASP.NET pages - except that it works with a syntax rather than . Another thing to remember is that you're working with Visual Studio - not your project. The templates run in a completely different AppDomain - so you can't use your project's configuration without doing a little gymnastics. To get you started, I made a screencast - complete with some music from Rush: t4.flv

= Troubleshooting =

Having trouble with your t4 templates? Have a look at the to see the most common causes.

Summary== The Concept of "patching" is a little different with Github and Git. If you've never used Git before, you might need to brush up a bit on it. Once you do it, however, it's very, very simple and extremely helpful! ==Getting to Know Github== This screencast will walk you through all you need to know to get working with Github and Git. It lasts about 10 minutes or so and you'll learn a bunch of new stuff! git.flv ==Github Issue Tracker Integration

Additionally, you can follow the convention of appending "Closes #1" (where 1 is the issue number) to your Commit messages. Github will automatically mark that Issue as Resolved!

Summary

There are a few ways to work with SubSonic 3.0. One of them is to tell it to get right out of your way - and that's the point of the . Many times code generation and configuration get in your way. If all you want is a DLL and pot to cook your data in - well this is for you.

Demo

SimpleRepo.flv

Summary

This is for SubSonic 2.x Only Migrations help you design your database using code that you write. It's a Rails thing and a lot of people love it.

Give Shawn Oster Some Love== I laid the groundwork for Migrations a while ago, but didn't have the bandwidth to give it the love it deserved. Frankly I don't know if I was smart enough. I asked Shawn Oster to help out and he took his massive swingin geek smarts and put together a pretty cool set of functionality. So if you see Shawn at the local Denver Gamer Shop, setting up for the Monday Night D&D Showdown (LARP-fest), give him a wizardly high-five! ==Video== subsonic_migrations.flv ==The Code

The Migration system works by basically "sucking" out the Migration classes from your project, reading in the code, and then executing it in a virtual compiler. This may seem complex, but it's actually pretty simple and at it's core is what we do to generate the code files anyway. To create a Migration, you have to follow our Conventional system and create a class file, something like 001Initial.cs ... and place that class file into a folder called "Migrations" off the root of your project (you can override this directory convention - see below). This class file must have one class (call it whatever you like), and it has to inherit from SubSonic.Migration:using System; using System.Collections.Generic; using System.Text; using SubSonic; namespace MigrationSample.Migrations { public class Migration001:Migration { } } Each "Migration" consists of changing from one version to another, either up or down. The code, therefore, follows this logic and offers two methods for you to tell the DB what to look like. For the first example (001Init), this is version one. The Up() method therefore is transitioning the DB from version 0 to version 1, so we need to put in some code to tell it what we want it to do: public override void Up() { //Create the Records Table TableSchema.Table records = CreateTableWithKey("Records"); records.AddColumn("RecordName"); records.AddColumn("GroupID", System.Data.DbType.Int32); records.AddColumn("LabelID", System.Data.DbType.Int32); AddSubSonicStateColumns(records); //Create the Groups Table TableSchema.Table groups = CreateTableWithKey("Groups"); groups.AddColumn("GroupName"); AddSubSonicStateColumns(groups); //Link them CreateForeignKey(groups.GetColumn("id"), records.GetColumn("groupID")); } For the Down() method, we need to reverse, exactly, everything we did with Up(): public override void Down() { TableSchema.Table records = GetTable("records"); TableSchema.Table groups = GetTable("groups"); //drop the FK DropForeignKey(groups.GetColumn("id"), records.GetColumn("groupID")); DropTable("Records"); DropTable("Groups"); } *Note: I'm working on the syntax to drop the FK constraint. I know it's heavy. If you needed to alter a column, you use: AlterColumn("records", "RecordName", System.Data.DbType.String, 800); You can change the column's length, type, name, and nullability if you need to. You can also remove a column from a table: RemoveColumn("records", "groupid");

Iterations

If your client says to you "hey great, you made a Records table - but you forgot Labels! You have labelID, where's labels!" - it's time to write another Migration, and migrate from version 1 to version 2: Following our convention, add another class file to the Migrations folder: 002_AddLabels Next up, add the code to Up/Down our migration:
namespace MigrationSample.Migrations { public class Migration002:Migration { public override void Up() { //add the labels table TableSchema.Table labels = CreateTableWithKey("Labels", "labelID"); labels.AddColumn("LabelName"); AddSubSonicStateColumns(labels); Execute("INSERT INTO Labels(labelname) VALUES('Capitol')"); Execute("INSERT INTO Labels(labelname) VALUES('Arista')"); Execute("INSERT INTO Labels(labelname) VALUES('Virgin')"); TableSchema.Table records = GetTable("records"); CreateForeignKey(labels.GetColumn("labelID"), records.GetColumn("id")); } public override void Down() { TableSchema.Table records = GetTable("records"); TableSchema.Table labels = GetTable("labels"); //drop the FK DropForeignKey(labels.GetColumn("labelID"), records.GetColumn("id")); DropTable("labels"); } } } Yes! Migrations also allow you to add data! I know that inline script is probably not what you had in mind ;) - I'll have this worked out by the time we go final with 2.1 (allowing you to use our query tool) but for now - the ability is there. Now, to execute... sonic.exe /migrate You can set this up like you do with other SubCommander commands - please see the video for how to make this happen!

Comparisons== There are other things out there (like DB projects with VS) and I go into some of this in the video (nudge nudge). This isn't a versioning tool per se - it's a development tool. If you like scripts, more power to ya. Migrations take a little getting used to, that's for sure. ==Caveats

This stuff may still be a tad rough. We've tested it a lot, but whenever you talk about tweaking DB schema and code... well there's a reason there's not many Migration solutions in .NET land right now :). Please be patient and help us to get this up to par.

Summary== This is a walkthrough of how to setup Visual Studio to call our command-line tool, sonic.exe. This tool is designed to help you along in your day and hopefully do the heavy-lifting for you. Please note that with SubSonic 3.0, we're using T4 templates to do most of the code generation stuff here. ==Configuration== SubCommander will always try and find a configuration file in its executing directory (Web.Config or App.Config). If it does, it will look for config information for itself there, and set itself up accordingly. You can override this by using the /config switch, and then telling it where it can find the config file: sonic.exe generate /config "c:\myproject\App.config" If you're working with a project and you want to use our generated code, just add an App.config file to the project, then you can run SubCommander in that directory. ==Manual Configuration== All of the config options can be passed in as switches ("/includeTableList table1, table2, table4" e.g.) to SubCommander. This is handy for when you want to use a BAT file. ==Scripting Schema and Data== You can script out your schema and data (and then version it in your favorite source control system) using SubCommander. Simply use the command "version" and tell SubCommander where to put the data: sonic.exe version /out Scripts This will output a script file (.sql) to the local scripts directory of your project ==Command Reference== Here are the commands you can use currently with SubCommander: *version: Scripts out the schema/data of your db to file *scriptdata: Scripts the data to file for your database *scriptschema: Scripts your Database schema to file *generate: Generates output code for tables, views, and SPs *generatetables: Generates output code for your tables *generateODS: Generates and ObjectDataSource controller for each table *generateviews: Generates output code for your views *generatesps: Generates output code for your SPs ==Screencast

SubCommander.flv

One thing I noticed recently when working with Subsonic 3.0 and the T4 templates was that there was no way to detect if a stored procedure has nullable parameters. After a bit of research I found this msdn article (? .?)\s{1}as\s{1}"; RegexOptions options = RegexOptions.IgnoreCase | RegexOptions.ExplicitCapture; MatchCollection matches = Regex.Matches(procedureText, regex, options); if (matches.Count > 0 && matches[0].Groups["Params"] != null) { Match match = matches[0]; arguments = match.Groups["Params"].ToString(); argumentArray = Regex.Split(arguments, ","); foreach (string sArgument in argumentArray) { MatchCollection paramMatches = Regex.Matches(sArgument, @"(? @\S)", options); MatchCollection nullMatches = Regex.Matches(sArgument, @"(? =\s*)", options); if (paramMatches.Count > 0 && paramMatches[0].Groups["ParamName"] != null) { bool isNullDefault = (nullMatches.Count > 0 && nullMatches[0].Groups["NullString"] != null); parameterNullibility.Add(paramMatches[0].Groups["ParamName"].ToString()); } } } return parameterNullibility; } b. Change SPPArams List GetSPParams(string spName) { var result = new List (); string[] restrictions = new string[3] { null, null, spName }; string procedureText; procedureText = GetStoredProcedureText(spName); List nullableParams = this.GetNullableParams(procedureText); using (SqlConnection conn = new SqlConnection(ConnectionString)) { conn.Open(); var sprocs = conn.GetSchema("ProcedureParameters", restrictions); using (SqlCommand cmd = new SqlCommand(spName, conn)) { cmd.CommandType = CommandType.StoredProcedure; SqlCommandBuilder.DeriveParameters(cmd); } conn.Close(); foreach (DataRow row in sprocs.Select("", "ORDINALPOSITION")) { SPParam p = new SPParam(); p.SysType = GetSysType(row["DATATYPE"].ToString()); p.DbType = GetDbType(row["DATATYPE"].ToString()).ToString(); p.Name = row["PARAMETERNAME"].ToString().Replace("@", ""); p.ParameterMode = GetParamDirection(row["PARAMETERMODE"].ToString()).ToString(); p.CleanName = CleanUp(p.Name); if (nullableParams.Contains(row["PARAMETERNAME"].ToString())) p.Nullable = true; result.Add(p); } } return result; } 2. Inside Setting.ttinclude a. Change SSParam class as follows public class SPParam{ public string Name; public string CleanName; public string SysType; public string DbType; public string ParameterMode; public bool Nullable; } b. Change ArgList property as follows. public string ArgList{ get{ StringBuilder sb=new StringBuilder(); int loopCount=1; foreach(var par in Parameters){ if (par.Nullable) { if ( par.SysType.ToString() != "string" && par.SysType.ToString() != "byte[]") { sb.AppendFormat("{0}{1} {2}", par.SysType, "?", par.CleanName); } else { sb.AppendFormat("{0} {1}", par.SysType, par.CleanName); } } else { sb.AppendFormat("{0} {1}", par.SysType, par.CleanName); } if(loopCount

SubSonic comes with a variety of ways to talk to your database. Originally we had a query tool that was a little verbose and somewhat difficult to use. That has since been refined to use a "fluent interface" - which is the chaining of methods to be, essentially, human-readable. These examples are specific to SubSonic 2 see ; Simple Select with typed columns int records = new Select(Product.ProductIDColumn, Product.ProductNameColumn). From().GetRecordCount(); Assert.IsTrue(records == 77); Returning a Single object Product p = new Select().From(). Where("ProductID").IsEqualTo(1).ExecuteSingle(); Assert.IsNotNull(p); Returning a Single object using generated strongly typed variables Product p = new Select().From(). Where(Product.Columns.ProductID).IsEqualTo(1).ExecuteSingle(); Assert.IsNotNull(p); Returning all columns int records = new Select().From("Products").GetRecordCount(); Assert.IsTrue(records == 77); Simple Where int records = new Select().From("Products"). Where("categoryID").IsEqualTo(5).GetRecordCount(); Assert.AreEqual(7, records); Simple Where with And (as Collection) ProductCollection products = DB.Select().From("Products") .Where("categoryID").IsEqualTo(5) .And("productid").IsGreaterThan(50) .ExecuteAsCollection(); Simple Inner Join SubSonic.SqlQuery q = new Select("productid").From(OrderDetail.Schema) .InnerJoin(Product.Schema) .Where("CategoryID").IsEqualTo(5); Simple Join With Table Enum SubSonic.SqlQuery q = new Select().From(Tables.OrderDetail) .InnerJoin(Tables.Product) .Where("CategoryID").IsEqualTo(5); Multiple Joins As Collection CustomerCollection customersByCategory = new Select() .From(Customer.Schema) .InnerJoin(Order.Schema) .InnerJoin(OrderDetail.OrderIDColumn, Order.OrderIDColumn) .InnerJoin(Product.ProductIDColumn, OrderDetail.ProductIDColumn) .Where("CategoryID").IsEqualTo(5) .ExecuteAsCollection(); Left Outer Join With Generics SubSonic.SqlQuery query = DB.Select(Aggregate.GroupBy("CompanyName")) .From() .LeftOuterJoin(); Left Outer Join With Schema SubSonic.SqlQuery query = DB.Select(Aggregate.GroupBy("CompanyName")) .From(Customer.Schema) .LeftOuterJoin(Order.CustomerIDColumn, Customer.CustomerIDColumn); Left Outer Join With Magic Strings SubSonic.SqlQuery query = DB.Select(Aggregate.GroupBy("CompanyName")) .From("Customers") .LeftOuterJoin("Orders"); Simple Select With Collection Result ProductCollection p = Select.AllColumnsFrom() .ExecuteAsCollection(); Simple Select With LIKE ProductCollection p = DB.Select() .From(Product.Schema) .InnerJoin(Category.Schema) .Where("CategoryName").Like("c%") .ExecuteAsCollection(); Using Nested Where/And/Or ProductCollection products = Select.AllColumnsFrom() .WhereExpression("categoryID").IsEqualTo(5).And("productid").IsGreaterThan(10) .OrExpression("categoryID").IsEqualTo(2).And("productID").IsBetweenAnd(2, 5) .ExecuteAsCollection(); ProductCollection products = Select.AllColumnsFrom() .WhereExpression("categoryID").IsEqualTo(5).And("productid").IsGreaterThan(10) .Or("categoryID").IsEqualTo(2).AndExpression("productID").IsBetweenAnd(2, 5) .ExecuteAsCollection(); OR when the above is done manually (notice manual opening and closing of expressions): ProductCollection products = Select.AllColumnsFrom() .OpenExpression().Where("categoryID").IsEqualTo(5).And("productid").IsGreaterThan(10).CloseExpression() .Or("categoryID").IsEqualTo(2).AndExpression("productID").IsBetweenAnd(2, 5) .ExecuteAsCollection(); Simple Paged Query SubSonic.SqlQuery q = Select.AllColumnsFrom(). Paged(1, 20).Where("productid").IsLessThan(100); Paged Query With Join SubSonic.SqlQuery q = new Select("ProductId", "ProductName", "CategoryName"). From("Products").InnerJoin(Category.Schema).Paged(1, 20); Paged View SubSonic.SqlQuery q = new Select().From(Invoice.Schema).Paged(1, 20); Simple IN Query int records = new Select().From(Product.Schema) .Where("productid").In(1, 2, 3, 4, 5) .GetRecordCount(); Assert.IsTrue(records == 5); Using IN With Nested Select int records = Select.AllColumnsFrom () .Where("productid") .In( new Select("productid").From(Product.Schema) .Where("categoryid").IsEqualTo(5) ) .GetRecordCount(); Using Multiple INs SubSonic.SqlQuery query = new Select() .From(Product.Schema) .Where(Product.CategoryIDColumn).In(2) .And(Product.SupplierIDColumn).In(3);

Screencast== To make things simple, we put together a quick screencast for you: /docs/media/intro.swf ==Walkthrough

Open up the App/Web.config file - we need to do a little surgery. First, declare a config section for SubSonic, right under the .

This here docs site is a Wiki and works based on help by . We'd love your input and feedback - here's some resources for you:

Note== This is a wiki, which is intended to be a resource of information, not a place to ask questions. If you have a question please head over to StackOverflow (click the "Help" link above). ==Style Guide

Please have a read of our , .

Linking== Linking your document will help it be discovered - please make sure to read the help doc and link away! ==Categories== Categories will help us find your page. One category is super-important: New Page. When you create a page for us, please mark it as a New Page (using [[Category:New Page]]) so we can find it! ==Thank you!

Honestly and truly - thank you for your interest in this :)

Philosophy== You hear it a lot: Convention Over Configuration. This is the Ruby On Rails mantra and had a lot of merit. At its core it means that what you do (especially if you've done it a lot) should carry a lot more weight than having to configure (and reconfigure) things over and over. ==General Conventions== *Column names should never contain reserved words (system, string, int, etc) *Column names should not be the same as table names ===Primary Keys=== If you want to use SubSonic to access your table, you need to have a Primary Key defined for your table. This is good practice in every case and we need it to do certain things with your table. If you don't have a Primary Key defined, your class won't be generated. If you don't believe us, or if you think this is a silly convention - SubSonic isn't for you. ===Lookup Tables=

For lookup tables, the key should be the first column and the " the second column. Many of our lookup functions depend on this. Column names such as "ShortDescription" will have labels such as "Short Description" in scaffold.

ActiveRecord Specific Conventions== ===Built-in Auditing=== Every table can have some auditing ability built in, but this is not required. These fields are: *CreatedOn (datetime) *CreatedBy (nvarchar(50)) *ModifiedOn (datetime) *ModifiedBy (nvarchar(50)) ===Logical Deletes=== If you want to use logical deletes, you can by adding a field called "Deleted" or "IsDeleted" ==SimpleRepository Specific Conventions== * Generated table names will be plural ===Primary Keys=== If you call a column “ID” or “Key” or “[ClassName]ID” – no matter it’s type – that will be your Primary Key. If you have other things in mind you can use a primary key attribute [SubSonicPrimaryKey] contained in the SubSonic.SqlGeneration.Schema namespace and we’ll use that column. ===String length=== There are two ways to tell SubSonic how to handle this – both using attributes. The first is [SubSonicStringLength(int] and the second is [SubSonicLongString] which sets to nvarchar(MAX) or LONGTEXT – depending on your provider. ===Nullability=== The default is not null, but you can change this by making your propery a nullable type. ===Numeric Precision=== The default is a Precision of 10 and a scale of 2 but you can change that with the [SubSonicNumericPrecision(int] attribute. ===Ignoring a Property=

You can ignore generation of a property by using [SubSonicIgnore] attribute.