NCommon

A light weight framework for building applications in .Net

Getting started guide.

Introduction

NCommon is a light weight framework that provides implementations of various concepts and patterns commonly used when building .Net applications and websites. NCommon also provides a foundation for building applications using a domain driven design approach by providing implementations of common patterns in Domain Driven Design such as Unit Of Work and Repositories.

One of the key features on NCommon is a ORM agnostic repository implementation. What this means is NCommon provides the ability to abstract away your data access framework of choice, be it NHibernate, Entity Framework or Linq-To-SQL, it allows you to focus on the concept of working with your domain models and LINQ queries and abstracts away any knowledge of the underlying data access infrastructure from your application.

Building NCommon from source

Source for NCommon is maintained at GitHub." For downloading and building NCommon from source, see the Building from source section in the main page.

Referencing NuGet packages

NCommon binaries are split into three categories:

NCommon core is contained in the NCommon.dll assembly. This assembly contains the configuration API to configure and bootstrap NCommon in your application.

NCommon depends on Dependency Injection and a IoC container heavily. If you are unfamiliar with Dependency Injection or IoC containers it's highly advisable you take some time to read through these two topics before going forward. Since there are many IoC container frameworks, and everyone has their own favorite one, NCommon provides adapters for various IoC container implementations so that it can work with your IoC container choice. Out of the box, NCommon provides implementations for the following container adapters (in no order of preference). To make NCommon work with the container of your choice, reference the appropriate assembly in your project.

NCommon provides a way to abstract your data access infrastructure by providing implementations of Unit Of Work and Repository pattern that work in a ORM agnostic manner. Out of the box, NCommon provides data access adapters for the following ORM frameworks:

Reference the appropriate data adapter assembly in your project to allow NCommon to work with your ORM / Data Access framework of choice.

NCommon assemblies are provided as NuGet packages. You can use the NuGet package manager to install the appropriate NuGet packages. Below is an example that installs the required NCommon packages for StructureMap and NHibernate data adapter. 

                Install-Package -Id NCommon.ContainerAdapter.StructureMap -ProjectName MyProject
                Install-Package -Id NCommon.NHibernate -ProjectName MyProject

NCommon configuration basics

NCommon provides a fluent configuration API to boot strap and configure NCommon in your application. Once you have referenced the appropriate NCommon assemblies listed above, you can use this fluent API to configure NCommon.

Below is a sample sample configuration using defaults. The snippet below is using Castle Windsor and NHibernate as it's container and data adapter respectively, but the same can be used for any container adapter and data adapter. 

                    var adapter = new WindsorContainerAdapter(_container);
                    NCommon.Configure.Using(adapter)
                        .ConfigureState<DefaultStateConfiguration>()
                        .ConfigureData<NHConfiguration>(config => config.WithSessionFactory(() => _sessionFactory))
                        .ConfigureUnitOfWork<DefaultUnitOfWorkConfiguration>(config => config.AutoCompleteScope());

NCommon provides a single static class Configure that provides the main entry point to the configuration API and contains one single static method Using which takes in the container adapter that NCommon will use to boot strap itself.

There are three main configuration parts of NCommon; State, Data Adapter and Unit Of Work configuration. Each part is configured using a configurator implementation and NCommon provides default configurators but you can create your own.

State Configuration

NCommon provides a set of helpers that allow storing and retrieving state informaiton in at the Local, Session, Cache or Application level. To register the default state storage implementations provided by NCommon you can use the DefaultStateConfiguration type, shown below. 

                    var adapter = new WindsorContainerAdapter(_container);
                    NCommon.Configure.Using(adapter)
                        .ConfigureState<DefaultStateConfiguration>();

The DefaultStateConfiguration registers internal implementations of Local, Session, Cache and Application storage. If you would like to use a custom state storage, for example use a MemcacheD cache storage provider, the DefaultStateConfiguration allows overriding individual storage implementations. Below is an example where custom storage providers are used for Local, Session, Cache, and Application storage. 

                var container = new Container();
                NCommon.Configure.Using(new StructureMapContainerAdapter(container))
                       .ConfigureState<DefaultStateConfiguration>(config =>
                                   config.UseCustomCacheOf<MyCustomCache>()
                                         .UseCustomLocalStateOf<MyLocalState>()
                                         .UseCustomSessionStateOf<MySessionState>()
                                         .UseCustomApplicationStateOf<MyAppState>()
                                );

Data Adapter Configuration

NCommon provides implementations of Unit of Work and Repository patterns that work with a large set of ORM providers, such as NHibernate and Entity Framework. To use NCommon's implementations of Unit of Work and Repositories you nee to configure the appropriate data provider. NCommon providers configurations that work with NHibernate, Entity Framework, Linq To Sql and Db4o. The example below configures NCommon to work with NHibernate. Note: The example assumes that a SessionFactory is configured and created during application initializtion. 

                    var adapter = new WindsorContainerAdapter(_container);
                    NCommon.Configure.Using(adapter)
                        .ConfigureState<DefaultStateConfiguration>()
                        .ConfigureData<NHConfiguration>(config => config.WithSessionFactory(() => _sessionFactory))

View the documentation section for more information.