Skip to content
Craig Fowler edited this page Feb 25, 2020 · 8 revisions

API for ORMs

This repository contains projects and NuGet packages relating to the usage of Object-relational mapping (ORM) systems in .NET (framework and dotnet core). They are primarily aimed at users of NHibernate.

The intent behind these packages is to provide an API which may be consumed directly from domain/business logic code for the majority of day-to-day usage of the ORM. This comes with a few benefits:

  • Domain logic does not require a direct dependency upon NHibernate
  • No need to write boilerplate repository-style logic to encapsulate the majority of data access
  • In unit testing/prototyping the ORM may be swapped-out for an in-memory collection of objects

Using these packages

Optional: Use the entities package

You may use the IEntity interface or the Entity<T> base class for your domain entities. This offers a concise and consistent way to express entity identity and compare for equality. These types are provided by the NuGet package CSF.Entities.

Use the ORM abstractions in your business logic

Your domain logic/business logic projects should not depend upon the ORM/NHibernate directly. Instead depend upon the package CSF.ORM.

If you chose to use the IEntity interface for your entities (above) then you may also use the package CSF.ORM.Entities for some added convenience.

Your business logic should perform most of its data access using either a combination of the interfaces IQuery & IPersister, or via the IEntityData interface if you are using the IEntity interface.

Dependency-inject production implementations

Your application should make use of dependency injection, through the dotnet core built-in dependency injection and/or one of the many frameworks available.

In production, the injected APIs listed above should be provided using a production ORM. This repository has two NuGet packages for this purpose:

  • CSF.ORM.NHibernate4 for apps which use NHibernate version 4.x
  • CSF.ORM.NHibernate5 for apps which use NHibernate version 5.x

Use in-memory implementations for unit testing

When unit testing, or perhaps for rapid prototyping, use an in-memory implementation which does not use a real ORM stack. There is a naïve in-memory implementation available in the CSF.ORM NuGet package in the InMemory namespace. This should be sufficient for unit testing.

Test your ORM config with the persistence tester

The package CSF.PersistenceTester is not intended for your production logic. Rather it is a utility which helps write automated tests for your ORM configuration, such as mappings.