Implementing Missing Features in Entity Framework Core – Part 4: Conventions

Conventions

This will be the fourth in a series of posts about bringing the features that were present in Entity Framework pre-Core into EF Core. The others are:

  • Part 1: Introduction, Find, Getting an Entity’s Id Programmatically, Reload, Local, Evict
  • Part 2: Explicit Loading
  • Part 3: Validations

Conventions are a mechanism by which we do not have to configure specific aspects of our mappings over and over again. We just accept how they will be configured, of course, we can override them if we need, but in most cases, we’re safe.

In EF 6.x we had a number of built-in conventions (which we could remove) but we also had the ability to add our own. In Entity Framework Core 1, this capability hasn’t been implemented, or, rather, it is there, but hidden under the surface.

A lot has changed. As of Entity Framework Core, conventions are specific to the provider in use, which makes perfect sense. But then we have several kinds of conventions. Just to give you an idea, the ConventionSet class exposes 15 convention collections! This is the place where we can register our own conventions, but there are two problems:

  • The current ConventionSet instance is not publicly accessible, so we need to use reflection to get hold of it;
  • We don’t want to add a new “blank” instance of ConventionSet because this way we would lose all of the conventions that would have been injected by the provider.

So, the solution I came up with had to use reflection to get the current convention set and allow adding new conventions, which is not ideal. Let’s see the code.

We need an extension method to get hold of the ConventionSet from the ModelBuilder and allow adding a convention, in the form of a IModelConvention:

public static class ModelBuilderExtensions

{

    public static ModelBuilder AddConvention(this ModelBuilder modelBuilder, IModelConvention convention)

    {

        var imb = modelBuilder.GetInfrastructure();

        var cd = imb.Metadata.ConventionDispatcher;

        var cs = cd.GetType().GetField("_conventionSet", BindingFlags.NonPublic | BindingFlags.Instance).GetValue(cd) as ConventionSet;

 

        cs.ModelBuiltConventions.Add(convention);

 

        return modelBuilder;

    }

 

    public static ModelBuilder AddConvention<TConvention>(this ModelBuilder modelBuilder) where TConvention : IModelConvention, new()

    {

        return modelBuilder.AddConvention(new TConvention());

    }

}

Feel free to cache the _conventionSet field somewhere, but that is not the point of this post.

You can see that we are adding the new convention to the ModelBuiltConventions collection, basically, because this is the only collection that Entity Framework Core will go through during the OnModelCreating method, all of the other collections will have been processed before it. We’re cool with that.

Let’s see two examples of sample conventions, first, one to set the maximum length of strings, where it hasn’t been explicitly set:

public sealed class DefaultStringLengthConvention : IModelConvention

{

    internal const int DefaultStringLength = 50;

    internal const string MaxLengthAnnotation = "MaxLength";

 

    private readonly int _defaultStringLength;

 

    public DefaultStringLengthConvention(int defaultStringLength = DefaultStringLength)

    {

        this._defaultStringLength = defaultStringLength;

    }

 

    public InternalModelBuilder Apply(InternalModelBuilder modelBuilder)

    {

        foreach (var entity in modelBuilder.Metadata.GetEntityTypes())

        {

            foreach (var property in entity.GetProperties())

            {

                if (property.ClrType == typeof(string))

                {

                    if (property.FindAnnotation(MaxLengthAnnotation) == null)

                    {

                        property.AddAnnotation(MaxLengthAnnotation, this._defaultStringLength);

                    }

                }

            }

        }

 

        return modelBuilder;

    }

}

Easy, easy, hey? We go through all of the mapped entities, then through all of their properties of type string, check if the maximum length annotation is present, and, if not, add a new one. Only one method, with access to all mapped entities.

Another example, turning off the table pluralization. As you know, as of EF RC2, table names of DbSet properties exposed in the DbContext are pluralized. We can get rid of this behavior if we explicitly set the name to something, in this case, it will be the entity type name:

public sealed class SingularizeTableNameConvention : IModelConvention

{

    public InternalModelBuilder Apply(InternalModelBuilder modelBuilder)

    {

        foreach (var entity in modelBuilder.Metadata.GetEntityTypes())

        {

            if (entity.FindAnnotation(RelationalAnnotationNames.TableName) == null)

            {

                entity.Relational().TableName = entity.Name.Split('.').Last();

            }

        }

 

        return modelBuilder;

    }

}

Now, some new extension methods come handy:

public static ModelBuilder UseDefaultStringLength(this ModelBuilder modelBuilder, int defaultStringLength = DefaultStringLengthConvention.DefaultStringLength)

{

    modelBuilder.AddConvention(new DefaultStringLengthConvention(defaultStringLength));

 

    return modelBuilder;

}

 

public static ModelBuilder UseSingularTableNames(this ModelBuilder modelBuilder)

{

    modelBuilder.AddConvention<SingularizeTableNameConvention>();

 

    return modelBuilder;

}

And that’s it! The way to apply these conventions (one or both) is during OnModelCreating:

protected override void OnModelCreating(ModelBuilder modelBuilder)

{

    modelBuilder

        .UseDefaultStringLength()

        .UseSingularTableNames();

 

    base.OnModelCreating(modelBuilder);

}

You can now reuse these conventions in all of your context classes very easily. Hope you enjoy it! Two final remarks about this solution:

  • The reflection bit is a problem, because things may change in the future. Hopefully Microsoft will give us a workaround;
  • There is no easy way to remove built-in (or provider-injected) conventions, because are applied before OnModelCreating, but I think this is not a big problem, since we can change them afterwards, as we’ve seen.

Stay tuned for more!

Custom Entity Framework Code First Convention for Discriminator Values

Since version 6, Entity Framework Code First allows the injection of custom conventions. These conventions define rules that will be applied by default to all mapped entities and properties, unless explicitly changed.

The conventions API includes a couple of interfaces: IConvention (marker only, should always be included), IConceptualModelConvention<T> (for the conceptual space of the model) and IStoreModelConvention<T> (for the store, or physical, side of the model). Worthy of mention, there is also a convenience class, Convention, that allows access to all mapped types and properties and doesn’t override any of the other conventions, and also TypeAttributeConfigurationConvention<T>, for tying a convention to a custom attribute. Some of the included attributes leverage these interfaces to configure some aspects of the mappings at design time, other configuration needs to be done explicitly in an override of OnModelCreating.

Entity Framework permits using a column for distinguishing between different types, when the Table Per Class Hierarchy / Single Table Inheritance pattern (please see Entity Framework Code First Inheritance for more information) is used for mapping a hierarchy of classes to a single table, as part of “soft delete” solutions, or, less known, for differentiating between multiple tenants. This column is called a discriminator.

In order to configure an entity to use a discriminator column, there is no out of the box attribute, so we must resort to code configuration:

   1: protected override void OnModelCreating(DbModelBuilder modelBuilder)

   2: {

   3:     modelBuilder.Entity<MyMultiTenantEntity>().Map(m => m.Requires("tenant_id").HasValue("first_tenant"));

   4:  

   5:     base.OnModelCreating(modelBuilder);

   6: }

Because there’s really no need to keep repeating this code, let’s implement an attribute for indicating a discriminator column in an entity:

   1: [Serializable]

   2: [AttributeUsage(AttributeTargets.Class, AllowMultiple = false, Inherited = true)]

   3: public sealed class DiscriminatorAttribute : Attribute

   4: {

   5:     public DiscriminatorAttribute(String columnName, Object discriminatorValue)

   6:     {

   7:         this.ColumnName = columnName;

   8:         this.DiscriminatorValue = discriminatorValue;

   9:     }

  10:  

  11:     public String ColumnName { get; private set; }

  12:  

  13:     public Object DiscriminatorValue { get; private set; }

  14:  

  15:     public override Boolean Equals(Object obj)

  16:     {

  17:         var other = obj as DiscriminatorAttribute;

  18:  

  19:         if (other == null)

  20:         {

  21:             return (false);

  22:         }

  23:  

  24:         return ((this.ColumnName == other.ColumnName) && (Object.Equals(this.DiscriminatorValue, other.DiscriminatorValue) == true));

  25:     }

  26:  

  27:     public override Int32 GetHashCode()

  28:     {

  29:         return (String.Concat(this.ColumnName, ":", this.DiscriminatorValue).GetHashCode());

  30:     }

  31: }

As you can see, the DiscriminatorAttribute attribute can only be applied to a class, at most once. This makes sense, because most likely you will only have a single discriminator column per entity:

   1: [Discriminator("tenant_id", "first_tenant")]

   2: public class MyMultiTenantEntity

   3: {

   4:     //...

   5: }

You need to specify both a column name and a discriminator value, which can be of any type, usually, a string or an integer.

Now, let’s write a custom convention that knows how to handle our custom attribute and perform the mapping:

WARNING! DYNAMICS AND REFLECTION AHEAD!

PROCEED WITH CAUTION!

   1: public sealed class DiscriminatorConvention : TypeAttributeConfigurationConvention<DiscriminatorAttribute>

   2: {

   3:     private static readonly MethodInfo entityMethod = typeof(DbModelBuilder).GetMethod("Entity");

   4:     private static readonly MethodInfo hasValueMethod = typeof(ValueConditionConfiguration).GetMethods().Single(m => (m.Name == "HasValue") && (m.IsGenericMethod == false));

   5:  

   6:     private readonly DbModelBuilder modelBuilder;

   7:     private readonly ISet<Type> types = new HashSet<Type>();

   8:  

   9:     public DiscriminatorConvention(DbModelBuilder modelBuilder)

  10:     {

  11:         this.modelBuilder = modelBuilder;

  12:     }

  13:  

  14:     public override void Apply(ConventionTypeConfiguration configuration, DiscriminatorAttribute attribute)

  15:     {

  16:         if (this.types.Contains(configuration.ClrType) == true)

  17:         {

  18:             //if the type has already been processed, bail out

  19:             return;

  20:         }

  21:  

  22:         //add the type to the list of processed types

  23:         this.types.Add(configuration.ClrType);

  24:  

  25:         dynamic entity = entityMethod.MakeGenericMethod(configuration.ClrType).Invoke(modelBuilder, null);

  26:  

  27:         Action<dynamic> action = arg =>

  28:         {

  29:             var valueConditionConfiguration = arg.Requires(attribute.ColumnName);

  30:             hasValueMethod.Invoke(valueConditionConfiguration, new Object[] { attribute.DiscriminatorValue });

  31:         };

  32:  

  33:         entity.Map(action);

  34:     }

  35: }

This class uses a bit of dynamics and reflection because types are not known at compile time, and hence we cannot use generics directly. Because the Apply method will be called multiple times, we need to keep track of which entities have already been processed by this convention, so as to avoid reprocessing them. We need to pass it the instance of DbModelBuilder, because otherwise our custom convention would have no way to apply the mapping, but I think it is a reasonable trade off.

Et voilà! In order to make use of it, we need to register the convention in OnModelCreating:

   1: protected override void OnModelCreating(DbModelBuilder modelBuilder)

   2: {

   3:     modelBuilder.Conventions.Add(new DiscriminatorConvention(modelBuilder));

   4:  

   5:     base.OnModelCreating(modelBuilder);

   6: }

And that’s it! Happy conventions! Winking smile