Extending And Customizing Code First Models – Part 2 of 2

Posted on February 15, 2013. Filed under: Entity Framework, Visual Studio | Tags: Code First, DbContext, Dynamic Model, EF, Entity Framework |

Here is the scenario, your company ships a library or application that contains a Code First model for accessing the database. Your customers want to extend this model to include extra types/properties to meet their specific business needs. These types/properties will be stored in additional tables/columns in the application database.

In Part 1 we looked at how to extend the model, but required the corresponding changes to be manually applied to the database. In the second (and final) part of this series we’ll take a look at how migrations can be used by the team creating the core model, and the team extending the model.

Complete source code is provided for download at the end of this post.

Make sure you have read and understand Part 1 of this series before tackling this post.

Using Migrations in the Core Model

The good news is that the developers of Customer Stalker don’t need to do anything special to use Code First Migrations. They can just use the standard workflow - as shown in this walkthrough.

For example, the Customer Stalker team have added a few properties to track the address of each customer.

using System.Collections.Generic;

namespace CustomerStalker.Core
{
  public class Customer
  {
    public int CustomerId { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }

    public string Address { get; set; }
    public string City { get; set; }
    public string State { get; set; }
    public string Zip { get; set; }

    public List Complaints { get; set; }
  }
}

They’ve used Migrations to apply these changes to the database, here is the resulting Migrations folder in their project.

Allowing Customers Extending the Model to Supply Migrations

To use the code from this section you are going to need EF6 because we are making use of the new Multiple Contexts per Database feature.

The Customer Stalker team  is going to allow the company extending their model to provide some hand coded migrations. The first time the context is used in an application, they’ll ensure all custom migrations have been applied to the database. They’ll also make sure that any migrations the Customer Stalker team has created have also been applied.

Introducing the Extension Points

Customer Stalker start with a base class that custom migrations will derive from. This derives from DbMigration which allows companies extending the model to provide an Up and Down method.

It also implements IMigrationMetadata – something that is usually taken care of by the Migrations power shell commands. This interface is used by migrations to get metadata about ordering and the state of the model when a migration was generated (used to scaffold the next migration).

For ordering, authors of custom migrations provide a simple sequence number. This is then converted into a ordering number that looks somewhat like the numbers Migrations generates.

Unfortunately Migrations requires you to provide a target model - a limitation we’re planning to remove - but for the moment we’ll just put in the string for an empty model. Please don’t dwell on this code… best to move on before your eyes bleed too much :)

using System.Data.Entity.Migrations;
using System.Data.Entity.Migrations.Infrastructure;

namespace CustomerStalker.Core.Migrations
{
  public abstract class CustomizingMigration : DbMigration, IMigrationMetadata
  {
    private const string _emptyModel =
      "H4sIAAAAAAAEAL1Y23LbNhB970z/gYOn9iGCJEdJ66GSsWW78bSyO6aT1wxErmRMcGEJ0BX7a33oJ/UXuryKF11o2e6bCKx2z1lwD47079//uB/XUjiPEBmu1ZSMBkPigPJ1wNVqSmK7fPMT+fjh++/cy0CunS9l3Ekah99UZkoerA1PKTX+A0hmBpL7kTZ6aQe+lpQFmo6Hw5/paEQBUxDM5TjuXawsl5A94ONMKx9CGzMx1wEIU6zjjpdldW6YBBMyH6Zknpzzv4hzJjjD4h6IJXHCt6efDXg20mrlhcxyJu6TEHB/yYSBAupp+LYv2uE4RUuZUtpiOq2OYksqHsjkEhnbBJlaxhVEGaUpORdMfUsXYW3r4dUXPLBF6CdurI4S4uQbKcGc/6DYudN/Yiven14bLzEW5JTYKN6Qf98L/GhMR8OMvOSrKONuiEPrTGiLSpdliq2JOsf2bhe2d8djazbtV0i2lGnEYNTvkQ4hsskdLAuY8zLhdbAVJz2cojhFRNAjg0sxrrlSZtyGqDhsG+FYEmfO1r+BWtmHKRlPJsS54msIypXijf+sOE4xlNVvYiHYQkC1fxhhC0+d3k44k9H4f4KTCUWJ5Jwrlk5GDQl+3I7k+aXxMYh9W4jhnm6cvE4zygFM626UkuZSWUoq3aGp7pyFIQKtaWyx4ni5wM7eeE9XO5nnoL7ZJ3pVJZQEtoLWbvqOBXDFI2MvmGULlvZiFshOWB/RLEu1tPP1JaghgiWK9HOOJK89SAkO8rhBNemmVPLBftVs1dsc4RV2VYKyWYOh6sUhFe7kyy5eJli0T5NmWsRSHSefu0vUZaZe4UnqupdDLhwN9PnSs9K2RaGev73Xq5BLW4fafsto5zVr3TDtWdh3h7dDquqVnrR0wy1m+LBh6wx1HkIcbMsjD9KBrg+F94eYCY58NwFzpvgSjL3X3wDNZzqFLQN4hDmjxgSih0PralIvm5aN2l6nlrdhSoKFxjskvwC+fq0m6XUl66Uc3WQXtsmLOrpOmac6ui7Opzq6QxmOcnTqkUX+A4u6nq5rCg4COGjYtlbLLNvzqzX8GNZZZJbsB8nWP75E+u2eayuhkyP49LNUXclzaf2XrHsBhq8285P+rlXgp0e+SVrGXKulLkmietTBlCHtFoNlAYrQWWT5kvkWt30wJnOdX5iIMeRSLiC4VrexDWN7ZgzIhUjqVF26v37mG5uY3dswm8uXoIAwOVKAW3UecxFUuK/yU6I9UqR6/AvgejZK6Lox3SqpMt1o1TNR0b4LCEEFeN/cgwwFJjO3ymOPsBvb4R42O+ZecIaTL02RY/P99I8Vmv6z8uE/KRLfnIsRAAA=";

    string IMigrationMetadata.Id
    {
      get { return string.Format("{0}_{1}", SequenceNo.ToString().PadLeft(15, '0'), GetType().Name); }
    }

    string IMigrationMetadata.Source
    {
      get { return null; }
    }

    string IMigrationMetadata.Target
    {
      get { return _emptyModel; }
    }

    public abstract int SequenceNo { get; }
  }
}

Next, the Customer Stalker team is adding some hooks to the ModelCustomizer they created in Part 1. These hooks allow the company extending the model to provide an assembly and namespace that contains their custom migrations.

They’re using DbMigrator to run these migrations from code – for more info on running migrations from code see Running & Scripting Migrations from Code.

They’re also using DbContextInfo to find the provider and connection string for the core context. This allows you to get such info about a context – taking into account all the conventions, connection strings in config files, etc. - without creating an instance of it.

using System;
using System.Collections.Generic;
using System.Data.Entity;
using System.Data.Entity.Infrastructure;
using System.Data.Entity.Migrations;
using System.Reflection;

namespace CustomerStalker.Core
{
  public class ModelCustomizer
  {

    // CODE FROM PART 1 EXCLUDED FOR BREVITY

    private static Assembly _migrationsAssembly;
    private static string _migrationsNamespace;

    public static void RegisterMigrations(Assembly assembly, string migrationsNamespace)
    {
      _migrationsAssembly = assembly;
      _migrationsNamespace = migrationsNamespace;
    }

    internal static void ApplyMigrations()
    {
      if (_migrationsAssembly != null && _migrationsNamespace != null)
      {
        var contextInfo = new DbContextInfo(typeof(CustomerStalkerContext));

        var extendedMigrator = new DbMigrator(new DbMigrationsConfiguration
        {
          ContextKey = "CustomerStalker.Core.Migrations.Extensions",
          ContextType = typeof(BlankContext),
          MigrationsAssembly = _migrationsAssembly,
          MigrationsNamespace = _migrationsNamespace,
          TargetDatabase = new DbConnectionInfo(contextInfo.ConnectionString, contextInfo.ConnectionProviderName)
        });

        extendedMigrator.Update();
      }
    }

    private class BlankContext : DbContext
    {
    }
  }
}

Now it’s time to create database initializer that will apply all the core migrations, and any custom ones, when CustomerStalkerContext is used for the first time in an AppDomain.

You’ll notice they are catching an AutomaticMigrationsDisabledException that may be thrown when applying the core migrations. If a company extends a model then it will no longer match the model when the last migration was created by the Customer Stalker team. This is fine because they assume the customer has written their own migrations to handle the required changes.

using CustomerStalker.Core.Migrations;
using System.Data.Entity;
using System.Data.Entity.Migrations;
using System.Data.Entity.Migrations.Infrastructure;

namespace CustomerStalker.Core
{
  class CustomerStalkerInitializer : IDatabaseInitializer
  {
    public void InitializeDatabase(CustomerStalkerContext context)
    {
      var coreMigrator = new DbMigrator(new Configuration());
      try
      {
        coreMigrator.Update();
      }
      // If the model has been extended it won't match the model recorded in the last migration
      catch (AutomaticMigrationsDisabledException) { }

      ModelCustomizer.ApplyMigrations();
    }
  }
}

Finally, they register this initializer in a static constructor for CustomerStalkerContext, ensuring it is always set before attempting to use the context in the application.

using System.Data.Entity;

namespace CustomerStalker.Core
{
  internal class CustomerStalkerContext : DbContext
  {
    static CustomerStalkerContext()
    {
      Database.SetInitializer(new CustomerStalkerInitializer());
    }

    // EXISTING CODE EXCLUDED FOR BREVITY
  }
}

Using the Extension Points

At the end of Part 1, MyBiz had extended the Customer type. These extensions required a new mybiz.Customers table with a column for the new IsVIP property and a foreign key back to the core dbo.Customers table.

Unfortunately they had to manually make these changes to the database. But now that can just add a custom migration.

using CustomerStalker.Core.Migrations;

namespace MyBiz.Migrations
{
  class AddMyBizCustomer : CustomizingMigration
  {
    public override void Up()
    {
      CreateTable("mybiz.Customers",
          c => new
          {
            CustomerId = c.Int(nullable: false),
            IsVIP = c.Boolean()
          })
          .PrimaryKey(t => t.CustomerId);

      AddForeignKey("mybiz.Customers", "CustomerId", "dbo.Customers", principalColumn: "CustomerId");
    }

    public override void Down()
    {
      DropForeignKey("dbo.MyBizCustomers", "CustomerId", "dbo.Customers");
      DropTable("dbo.MyBizCustomers");
    }

    public override int SequenceNo { get { return 1; } }
  }
}

Now they can update their test code from Part 1 to register their migrations.

ModelCustomizer.RegisterModelCustomization(
    mb =>
    {
      mb.Entity().Property(c => c.FirstName).HasMaxLength(400);
      mb.Entity().Property(c => c.LastName).HasMaxLength(400);

      mb.Entity().ToTable("mybiz.Customers");
    });

ModelCustomizer.RegisterTypeSubstitution<Customer, MyBizCustomer>();

ModelCustomizer.RegisterMigrations(typeof(AddMyBizCustomer).Assembly, typeof(AddMyBizCustomer).Namespace);

var service = new CustomerService();
var customer = new MyBizCustomer { FirstName = "Jane", LastName = "Doe", IsVIP = true };
service.AddCustomer(customer);
service.QuickAddCustomer("John", "Doe");

After running their test code, their changes will be automatically applied to the database. Looking in the __MigrationsHistory table they can see Migrations keeping track of which migrations (both core and custom) have been applied to the database.

Source Code

As promised… you can get the complete Visual Studio 2012 solution here…

Extending and Customizing Code First Models – Part 1 of 2

Posted on February 5, 2013. Filed under: Entity Framework, Visual Studio | Tags: Code First, DbContext, Dynamic Model, EF, Entity Framework |

Here is the scenario, your company ships a library or application that contains a Code First model for accessing the database. Your customers want to extend this model to include extra types/properties to meet their specific business needs. These types/properties will be stored in additional tables/columns in the application database.

In this post I’ll walk through an example using a company that delivers a CRM product called Customer Stalker. The company provides a library for Customer Stalker that includes a Code First model with some hooks to allow each business that uses Customer Stalker to customize the model. We’ll see how a company called MyBiz uses these hooks to extend the model. MyBiz will use inheritance to add extra properties to existing classes/tables that are part of the Customer Stalker model.

I’m just going to show one possible way you can combine the building blocks to solve this problem. There are plenty of different ways to architect a solution and you can take the principles I show to come up with a way that suits you. This is by no means production quality or well architected code, just a rough sample… take it for what it is

We’ll build on the example as we go, adding more and more functionality. Here are the main stages I’ll cover:

• Part 1 (this post)
  In Part 1 we’ll assume that Customer Stalker does *not* use Code First Migrations to create/upgrade the database and MyBiz will manually add their additional tables/columns to the database. In Part 2 we’ll enable migrations.
  • The Code Before Enabling Customization – Before allowing any customization of the model, we’ll take a quick look at code from the Customer Stalker library and code written by MyBiz.
  • Basic Extension – We’ll start with the very basics that allow MyBiz code to provide instances of a custom derived type to the Customer Stalker library.
  • Substituting Custom Derived Types – Once MyBiz has added a derived type, they probably want the Customer Stalker library to always create their derived type, rather than the original base type. This means that all data in the database will have the custom properties – not just the instances created by MyBiz code.
  • Avoiding Modification of the Core Tables – Next, we’ll look at how MyBiz can add their customizations in a way that does not alter the tables that are created by the Customer Stalker library.
  • Customizing the Core Tables – Finally, we’ll show how MyBiz could customize tables/columns that are part of the core Customer Stalker model.
• Part 2 (coming soon)
  • Adding Code First Migrations – We’ll allow Customer Stalker to use migrations to create/upgrade the database. We’ll also provide some hooks so that MyBiz can add their own migrations to apply their customizations.
  • Source Code Download – I’ll provide a Visual Studio solution that shows the complete Customer Stalker and MyBiz code bases.

The Code Before Enabling Customization

The Customer Stalker Code

Before we add any hooks here is the model that the Customer Stalker library is using. They have a couple of domain classes to track Customers and any Complaints they make.

using System;
using System.Collections.Generic;

namespace CustomerStalker.Core
{
  public class Customer
  {
    public int CustomerId { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }

    public List<Complaint> Complaints { get; set; }
  }

  public class Complaint
  {
    public int ComplaintId { get; set; }
    public DateTime DateRecieved { get; set; }
    public string Details { get; set; }
    public bool IsResovled { get; set; }

    public int CustomerId { get; set; }
    public Customer Customer { get; set; }
  }
}

Customer Stalker uses a derived DbContext to turn these classes in a Code First model. They are using the Fluent API to configure the model – in this case just the maximum length of the name properties.

using System.Data.Entity;

namespace CustomerStalker.Core
{
  internal class CustomerStalkerContext : DbContext
  {
    public DbSet Customers { get; set; }
    public DbSet Complaints { get; set; }

    protected override void OnModelCreating(DbModelBuilder modelBuilder)
    {
      modelBuilder.Entity()
        .Property(c => c.FirstName)
        .HasMaxLength(200);

      modelBuilder.Entity()
        .Property(c => c.LastName)
        .HasMaxLength(200);
    }
  }
}

You may have noticed that that the context is internal. The Customer Stalker library exposes an API surface that restricts how businesses such as MyBiz interact with their library. Here is one of the services they expose.

namespace CustomerStalker.Core
{
  public class CustomerService
  {
    public void AddCustomer(Customer customer)
    {
      using (var db = new CustomerStalkerContext())
      {
        db.Customers.Add(customer);
        db.SaveChanges();
      }
    }

    public Customer QuickAddCustomer(string firstName, string lastName)
    {
      var customer = new Customer();
      customer.FirstName = firstName;
      customer.LastName = lastName;

      using (var db = new CustomerStalkerContext())
      {
        db.Customers.Add(customer);
        db.SaveChanges();
      }

      return customer;
    }
  }
}

MyBiz Code

MyBiz is getting familiar with the Customer Stalker library and has written the following code to test it out.

var service = new CustomerService();
var customer = new Customer {FirstName = "Jane", LastName = "Doe" };
service.AddCustomer(customer);
service.QuickAddCustomer("John", "Doe");

Here is what the Customer Stalker database would look like at MyBiz – this is the default Customer Stalker database with no customization.

Basic Extension

Introducing the Extension Points

The Customer Stalker team is introducing a new ModelCustomizer class into their library. At the moment they just allow businesses to register some custom logic to further configure the Customer Stalker Code First model. They’ve also included an internal method to apply this customization to a model.

using System;
using System.Collections.Generic;
using System.Data.Entity;

namespace CustomerStalker.Core
{
  public class ModelCustomizer
  {
    private static Action<DbModelBuilder> _modelCustomization;

    public static void RegisterModelCustomization(Action<DbModelBuilder> modelCustomization)
    {
      _modelCustomization = modelCustomization;
    }

    internal static void ApplyCustomization(DbModelBuilder modelBuilder)
    {
      if (_modelCustomization != null)
      {
        _modelCustomization(modelBuilder);
      }
    }
  }
}

They’ve also updated their context to apply any customization after they’ve finished configuring their model in the OnModelCreating method.

protected override void OnModelCreating(DbModelBuilder modelBuilder)
{
  modelBuilder.Entity<Customer>()
    .Property(c => c.FirstName)
    .HasMaxLength(200);

  modelBuilder.Entity<Customer>()
    .Property(c => c.LastName)
    .HasMaxLength(200);

  ModelCustomizer.ApplyCustomization(modelBuilder);
}

Using the Extension Points

Let’s see how MyBiz can use these extension points to store some extra information about Customers.

First up, MyBiz defines a domain class that derives from an existing class and adds any properties that MyBiz wants to track.

using CustomerStalker.Core;

namespace MyBiz.ExtendedModel
{
  public class MyBizCustomer : Customer
  {
    public bool IsVIP { get; set; }
  }
}

MyBiz also needs to modify their Customer Stalker database to include the new column - we’ll look at using Code First Migrations to do this in Part 2 (coming soon).

By default Code First uses the TPH pattern to store an inheritance hierarchy, hence the new Discriminator column in the Customers table. This allows Entity Framework to differentiate between Customers and MyBizCustomers. Later in this post we’ll take a look at how to introduce a derived type without modifying the existing table.

Now MyBiz can use the hooks provided by Customer Stalker to add their new type to the model. Then they can insert MyBizCustomers using the Customer Stalker library.

ModelCustomizer.RegisterModelCustomization(
    mb =>
    {
      mb.Entity<MyBizCustomer>();
    });

var service = new CustomerService();
var customer = new MyBizCustomer { FirstName = "Jane", LastName = "Doe", IsVIP = true };
service.AddCustomer(customer);
service.QuickAddCustomer("John", "Doe");

When MyBiz runs the above code, they’ll see the following data in the Customers table in their database.

As expected, MyBiz can use the hooks to register their own derived type with extended properties and persist it to the database.

Substituting Custom Derived Types

One limitation of our solution thus far is that QuickAddCustomer doesn’t reason about the derived MyBizCustomer type and is just creating an instance of the base Customer type. This may not be ideal, because MyBiz may want all customers to have their extended properties, including those created internally by Customer Stalker.

Introducing the Extension Points

The Customer Stalker team is adding a RegisterTypeSubstitution method which allows a business to register a derived type to be used in place of a type from the base Customer Stalker model. There is also a Create method that internal Customer Stalker code can use to create types based on what substitutions have been applied.

using System;
using System.Collections.Generic;
using System.Data.Entity;

namespace CustomerStalker.Core
{
  public class ModelCustomizer
  {
    private static Action<DbModelBuilder> _modelCustomization;
    private static Dictionary<Type, Type> _replacedTypes = new Dictionary<Type, Type>();

    public static void RegisterModelCustomization(Action<DbModelBuilder> modelCustomization)
    {
      _modelCustomization = modelCustomization;
    }

    internal static void ApplyCustomization(DbModelBuilder modelBuilder)
    {
      if (_modelCustomization != null)
      {
        _modelCustomization(modelBuilder);
      }
    }

    public static void RegisterTypeSubstitution<TOld, TNew>()
      where TOld : class
      where TNew : TOld
    {
      _replacedTypes.Add(typeof(TOld), typeof(TNew));
    }

    internal static TType Create<TType>()
    {
      if (_replacedTypes.ContainsKey(typeof(TType)))
      {
        return (TType)Activator.CreateInstance(_replacedTypes[typeof(TType)]);
      }

      return Activator.CreateInstance<TType>();
    }
  }
}

The QuickAddCustomer method is then updated to take type substitution into account.

public Customer QuickAddCustomer(string firstName, string lastName)
{
  var customer = ModelCustomizer.Create<Customer>();
  customer.FirstName = firstName;
  customer.LastName = lastName;

  using (var db = new CustomerStalkerContext())
  {
    db.Customers.Add(customer);
    db.SaveChanges();
  }

  return customer;
}

Using the Extension Points

MyBiz adds in a call to RegisterTypeSubstitution to their test code to register the MyBizCustomer to be used in place of Customer.

ModelCustomizer.RegisterModelCustomization(
    mb =>
    {
      mb.Entity<MyBizCustomer>();
    });

ModelCustomizer.RegisterTypeSubstitution<Customer, MyBizCustomer>();

var service = new CustomerService();
var customer = new MyBizCustomer { FirstName = "Jane", LastName = "Doe", IsVIP = true };
service.AddCustomer(customer);
service.QuickAddCustomer("John", "Doe");

And now Customer Stalker is able to create instances of the custom derived type so that all instances include the extended properties.

Avoiding Modification of the Core Tables

So far, the extra properties defined on a derived type have been stored in the core table that is created by Customer Stalker. In some scenarios this may not be acceptable. For example, Customer Stalker may not provide MyBiz with support for their product if they modify the core tables.

Fortunately Code First supports the TPT inheritance mapping pattern, which allows us to store the extended properties from a derived type in a separate table. We don’t need any additional hooks in the Customer Stalker library, just some different configuration when MyBiz customizes the model.

This new configuration will put all the extended properties of MyBizCustomer in a Customers table in the mybiz schema.

ModelCustomizer.RegisterModelCustomization(
    mb =>
    {
      mb.Entity<MyBizCustomer>().ToTable("mybiz.Customers");
    });

Here is what the modified database should look like. Notice that the extended tables primary key is also a foreign key that points to the row in the core table.

When MyBiz runs their test code here is what gets inserted into the database.

Customizing the Core Tables

In addition to adding and configuring new types, the model customization hook allows MyBiz to customize the tables/columns of the core Customer Stalker model.

For example, MyBiz may operate in a part of the world where people have very long names. The maximum length of 200 that Customer Stalker configures for first and last name may not be enough. The following code allows MyBiz to override this with a maximum length of 400.

ModelCustomizer.RegisterModelCustomization(
    mb =>
    {
      mb.Entity<Customer>().Property(c => c.FirstName).HasMaxLength(400);
      mb.Entity<Customer>().Property(c => c.LastName).HasMaxLength(400);

      mb.Entity<MyBizCustomer>().ToTable("mybiz.Customers");
    });

Remember that MyBiz would also need to make this change to the database schema. In Part 2 (coming soon) we’ll look at allowing MyBiz to make this change with Code First Migrations.