Startup configuration

MongODM make use of several different components, and these have to be initialized. Despite it's always possible to construct them manually, the simpliest way is to make use of dependency injection systems for authomatize these processes. MongODM support native Asp.NET Core dependency injection system out of the box.

Here we assume that we are using Asp.NET Core for our application, and it's so available a Startup class exposing configuration methods.

There are different way for initialize the system, according to the degree of customization that we want to perform. We have four packages, and according to what we have to do, we can choose what to use:

• MongODM.Core implements core business of MongODM, doesn't provide any configuration system
• MongODM.AspNetCore integrate MongODM with Asp.NET Core and its configuration system
• MongODM.Hangfire integrate MongODM with Hangfire and implements a task runner that use it for handle jobs
• MongODM simplify configuration using by default both MongODM.AspNetCore and MongODM.Hangfire

MongODM.Core is always included, others are optional. In this guide we will propose two configuration way, both using Asp.NET Core and Hangfire, but first is the easier, using MongODM package that simplify the process, second instead is implemented with MongODM.AspNetCore and MongODM.Hangfire packages, where Hangfire could be replaced with any other task runner implementation.

Use MongODM package

This is the simplest configuration way, with default environment components.

At begin we have an Asp.NET Core application. First install MongODM package. You can install it with Package Manager Console or with your preferred project editor:

PM> Install-Package MongODM

In application's Startup class we register components to the dependency injection system with the method ConfigureServices(IServiceCollection services). Add this code to the method:

services.AddMongODMWithHangfire<ModelBase>();

This method configure MongODM and Hangfire components with our environemnt. It can take parameters for configure options. Action<HangfireOptions>? configureHangfireOptions permits to configure Hangfire, and Action<MongODMOptions>? configureMongODMOptions permits to configure MongODM. For details on options composition we refer to a next section.

The generic parameter instead represent our lowest model base type in domain. It's needed because of this issue on MongoDB's official drivers CSHARP-3154. Here we assume to have a common base model in domain of type ModelBase.

On how to add configuration for one or more dbContexts we refer to a successive paragraph.

Use MongODM.AspNetCore and MongODM.Hangfire packages

This is the more complex configuration way, that permits to change different environment components.

At begin we have an Asp.NET Core application. First install MongODM.AspNetCore and MongODM.Hangfire packages. You can install them with Package Manager Console or with your preferred project editor:

PM> Install-Package MongODM.AspNetCore
PM> Install-Package MongODM.Hangfire

If we use Hangfire we will need also one more external package. This is not needed if we will use another async task execution engine:

• Hangfire.AspNetCore implements easy configuration methods for Hangfire with Asp.NET Core

PM> Install-Package Hangfire.AspNetCore

In application's Startup class we register components to the dependency injection system with the method ConfigureServices(IServiceCollection services). Add this code to the method:

services.AddMongODM<HangfireTaskRunner, ModelBase>();

This method configure MongODM components with our environment. It can take an optional Action<MongODMOptions>? configureMongODMOptions parameter for configure global MongODM options. For details on options composition we refer to a next section.

There are also two generic parameters passed to it. The first generic parameter represent an implementation of ITaskRunner interface. It is the MongODM reference type for identify how to handle execution of asynchronous tasks. Any implementation of that interface is valid, in this case HangfireTaskRunner implements it for Hangfire.

The second generic parameter represent our lowest model base type in domain. It's needed because of this issue on MongoDB's official drivers CSHARP-3154. Here we assume to have a common base model in domain of type ModelBase.

We also need to configure Hangfire to work with our system. Because we are using MongoDB, automatically we assume that Hangfire will use it also as its own task execution storage. Exists a library that permits this, it's Hangfire.Mongo (GitHub page) and it's automatically included with MongODM.Hangfire.

Add this code to the same ConfigureServices(IServiceCollection services) method:

services.AddHangfire(options =>
{
    options.UseMongODM();
    options.UseMongoStorage(hangfireConnectionString, new MongoStorageOptions
    {
        MigrationOptions = new MongoMigrationOptions
        {
            MigrationStrategy = new MigrateMongoMigrationStrategy(),
            BackupStrategy = new CollectionMongoBackupStrategy()
        }
    });
});

Details on this configuration are demanded to official Hangfire documentation, and to Hangfire.Mongo GitHub page.

On how to add configuration for one or more dbContexts we refer to a successive paragraph.

Add DbContexts

With MongODM we can organize information in database contexts, builded on concept of application domains. Actually currently only one database context is supported at time (MODM-18), but in future we will be able to configure more than one per application.

With this sample we assume to have a DbContext called SampleDbContext that implements ISampleDbContext interface. The interface is optional, but its use can simplify testing operations with dependency injection.

Registration of domain contexts are performed with cascade style on MongODM configuration. In ConfigureServices(IServiceCollection services) method identify where we have configured MongODM, for example using AddMongODMWithHangfire, and add this code:

services.AddMongODMWithHangfire<ModelBase>()
    .AddDbContext<ISampleDbContext, SampleDbContext>();

The method AddDbContext<ISampleDbContext, SampleDbContext>() register our database context and its interface into the dependency injection system. Also its variant without interface is available AddDbContext<SampleDbContext>(). It takes also an optional parameter:

• Action<DbContextOptions<SampleDbContext>> dbContextConfig: this action permits to configure options specific to this DbContext of type SampleDbContext

Options

HangfireOptions

This class is a wrapper for Hangfire.Mongo package configuration options. These are the exposed properties:

• string ConnectionString: connection string for Hangfire on MongoDB instance
• MongoStorageOptions StorageOptions: storage options for Hangfire on MongoDB

By default it uses a local running instance of MongoDB.

MongODMOptions

Options for MongODM configure global settings for the full running instance. It exposes these properties:

• string DbMaintenanceQueueName: name of queue used by task runner for execute db maintenance tasks. By default it's configured to "default"

DbContextOptions

Options of database contexts are specific of each one, and are identified with its generic argument that is configured with type of database context implementation. Inside of options we can find these properties:

• SemanticVersion ApplicationVersion { get; set; }
  The application version, identified with semantic versioning (SemVer specific)
• string ConnectionString { get; set; }
  The connection string to MongoDB database instance
• string DbName { get; }
  A readonly property that read database name from provided connection string
• string DbOperationsCollectionName { get; set; }
  Internal collection name, used for keep track of operations performed by MongODM on database
• string Identifier { get; set; }
  Database context internal identifier. Used for keep track of performed operations

Hangfire configuration

If we use Hangfire, we have to enable at least an Hangfire Server for perform execution of scheduled tasks. We will run it locally inside the same application, but this is not the only available configuration. For more info please look at official Hangfire documentation.

Into Startup class find the method Configure(IApplicationBuilder app) (it could have more parameters), and add this code:

app.UseHangfireServer();

It can be added at top of method, or after other calls. With simple applications it should be not a problem, but in general with this method the invoke order is important. For more information on how to configure it, look at Asp.NET Core documentation

Admin dashboard configuration

For instructions on how to configure the admin dashboard, look at its dedicated page: Admin dashboard.