Convention Based Mapping

One of the new features in MicroLite 3.0 is the convention based mapping which allows you to map classes to tables following a set of conventions. MicroLite still defaults to the existing attribute based mapping which allows you to be more explicit, however if you can follow the conventions and the limitations are not a problem, it saves on adding attributes to each class and property.

To configure MicroLite to use it, simply load the extension which is bundled in the main MicroLite assembly:

    .Extensions() // If used, load any logging extension first.
    .WithConventionBasedMapping(new ConventionMappingSettings
        IdentifierStrategy = IdentifierStrategy.DbGenerated, // default is DbGenerated if not specified.
        UsePluralClassNameForTableName = true // default is true if not specified.

Note that you are required to provide a ConventionMappingSettings, this allows you to configure the settings for the convention based mapping.

The conventions are as follows:

  • Only one identifier strategy can be used across all mapped tables and the chosen strategy is specified in the ConventionMappingSettings.
  • You can choose whether your table names are plural versions of your class name (e.g. if true, class Customer -> table Customers).
  • The class must have a property which is either class name + Id or just Id (e.g. class Customer should have a property called CustomerId or Id).
  • All public properties on a class with a get and set will be mapped.
  • Any enums must be mapped to a column which is enum type + Id (e.g. public CustomerStatus Status { get; set; } will be mapped to column CustomerStatusId.
  • If the database supports schemas, all mapped tables are in the default schema (e.g. dbo for MS SQL).

The conversion of singluar class names to plural table names is reasonably smart, for example it would perform the following conversions (English only in 3.0.0):

Class Name Table Name
Customer Customers
Party Parties
Elf Elves
Man Men
Person People
Child Children
Status Statuses
Mouse Mice
Equipment Equipment (there is no plural of equipment)

If you find a conversion it cannot cater for, you have 2 options:

// Use AddInvariantWord to specify words for which there is no plural version.

// Use AddRule to specify or update a regular expression to perform the pluralisation.
MicroLite.Mapping.InflectionService.AddRule(searchPattern: "(.+)", replacementPattern: @"$1s");

The examples shown above are already included in the InflectionService, they are used here as an example and do not need explicitly adding.

If you find any incorrect conversions or missing conversions, please raise an Issue with the details so it can be included in subsequent releases.

There are a number of limitations to using the convention based mapping compared to the standard attribute mapping which are:

  1. All classes must use the same identifier strategy (attribute mapping allows a mixture).
  2. All public properties with a getter and setter will be mapped (attribute mapping is opt-in).
  3. All property names must match the column name with the exception of the identifier property and mapped enum properties (attribute mapping allows any property to be named differently to the column).
  4. All mapped columns except the identifier can be inserted and updated (attribute mapping allows per column configuration of insert or update only columns).

If none of the limitations prevent the conventions from being used in your application or you are creating a new application from scratch and wish to follow the conventions, they can simplify the mapping process.

Note – Since only one mapping convention can be used, you can start on convention mapping and switch to attribute mapping at a later stage if you wish to take advantage of the extra flexibility offered by it.

This article was written for version 3.0.0 of the MicroLite framework.


6 thoughts on “Convention Based Mapping

  1. Pingback: Unit Testing when using the Convention Based Mapping | MicroLite ORM

  2. Pingback: What’s coming after 3.0? | MicroLite ORM

  3. Pingback: MicroLite 4.0 | MicroLite ORM

  4. Pingback: MicroLite 4.0 Released | MicroLite ORM

  5. Pingback: MicroLite 4.0 – Convention Based Mapping Enhancements | MicroLite ORM

  6. Pingback: MicroLite 5.0 – Changes to Convention Mapping | MicroLite ORM

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s