Datelite.Mvc.Shared 1.0.1

DATelite MVC shared utilities

A set of best practices and time-proven .NET MVC patterns used by DATelite in form of extensions, utility classes and functions. Since all these scaffolding and bootstrapping utilities helped us creating maintainable and reliable MVC components much faster, we wanted to share as much as we could.

Features

Repository interface

The interface definition Datelite.Mvc.Shared.Data.IRepository provides a minimal set of methods frequently used in a repository pattern. It can be extended or used as an example for a custom interface. Applications must implement this interface and provide the implementation themselves as services. The interface uses Datelite.Mvc.Shared.Entities.BaseEntity as its base entity class.

Entity-model mapping

An obscenely simple auto-mapper implementation is provided, capable of automatically mapping entities to models and models to entities without any configuration and without asking questions.

The base entity class representing entity objects is Datelite.Mvc.Shared.Entities.BaseEntity.

The base model class representing boundary objects is Datelite.Mvc.Shared.Models.BaseEntityModel.

The mapper between entitiy objects and boundary objects is defined as a set of extension methods of BaseEntity and BaseModel classes. The extensions are in Datelite.Mvc.Shared.Extensions.EntityModelExtensions. The mapper makes assumptions on timestamp format on entity models, see the code documentation for more information.

Properties which should be ignored by the mapper can be marked with MapIgnore, which is a decorator provided in Datelite.Mvc.Shared.Models.MapIgnoreAttribute.

using Datelite.Mvc.Shared.Extensions.EntityModelExtensions;

// [...]

// Entity class, usually comes from a service.
MyEntity entity = new();

// Map it to a model.
MyModel model = entity.ToModel<MyModel>();

// Map it back.
MyEntity mappedEntity = model.ToEntity<MyEntity>();

String extensions

This library provides a pascal-case to snake-case converter as a string extension. The extension is in Datelite.Mvc.Shared.Extensions.StringExtensions. It converts pascal-cased symbols to snake-cased ones using regular expressions for file naming and database naming conventions.

Logging

A console JSON logger is provided with all required infrastructural scaffolding in the Datelite.Mvc.Shared.Infrastructure.Logging namespace. Those classes (ConsoleJsonLogger, ConsoleJsonLoggerProvider, LoggingContextProvider) should not be called or instantiated on their own.

Instead, Datelite.Mvc.Shared.Infrastructure.Extensions.CommonStartupLoaders contains two ILoggingBuilder extension methods, which should be called in the Program or the Startup class of the application during bootstrapping:

1. AddLoggers adds the console JSON logger as a standard .NET ILogger<> implementation.

2. AddApplicationContext can be used to define a query function injecting arbitrary application context into log messages.

// Program.cs

using Datelite.Mvc.Shared.Infrastructure.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddLoggers();

builder.Logging.AddApplicationContext(() =>
{
    // You can use any service here by requesting it from DependencyResolver.
    return new Dictionary<string, object?>
    {
        { "MyProp", "ContextValue" }
    };
});

Since the logger is an ILogger<> implementation, it can be injected into any DI-enabled class constructor as ILogger<TClass>, where TClass is the current class' type.

Console JSON logger is using the model class Datelite.Mvc.Shared.Models.Logging.ConsoleLogModel to assemble log messages before serializing them into JSON format. The messages are output to the standard output channel or the standard error channel (errors and critical errors only).

DI helpers

The library provides facilities for automatic dependency registration in the user application. Attributes RegisterSingleton, RegisterScoped, and RegisterTransient can be used to decorate DI-enabled classes, which will be registered automatically by themselves and by their interfaces as well, if any. These attributes are defined in Datelite.Mvc.Shared.Infrastructure.DependencyRegistrationAttribute.

NOTE: if the decorated class implements multiple interfaces, only the first one will be used for dependency registration.

Dependencies are registered during initial startup and bootstrapping, if the RegisterServices method is called from Datelite.Mvc.Shared.Infrastructure.Extensions.CommonStartupLoaders usually with the main assembly as its argument. The extension method only registers decorated classes from the provided assembly and its referenced assemblies.

The static class Datelite.Mvc.Shared.Infrastructure.DependencyResolver can be used to access DI-enabled classes during runtime, without injecting them in constructors. To initialize this class, the ExportServiceProvider method must be called during startup from Datelite.Mvc.Shared.Infrastructure.Extensions.CommonStartupLoaders after registering every service.

// Program.cs

using Datelite.Mvc.Shared.Infrastructure.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.RegisterServices(Assembly.GetExecutingAssembly());

// [...]

var app = builder.Build();

app.ExportServiceProvider();

Configuration

If you are okay with using a standard configuration structure, you can call the LoadConfiguration method in Datelite.Mvc.Shared.Infrastructure.Extensions.CommonStartupLoaders. The configuration sources and their order is documented on the method. If not, you can use it as an example for loading your own configuration structure.

To easily bind configuration to strongly-typed models, the library provides a ConfigurationModel decorator in Datelite.Mvc.Shared.Models.ConfigurationModelAttribute. The decorator can be applied to classes representing configuration sections.

Binding is done on initial startup and bootstrapping, if the RegisterConfigurationModels method is called from Datelite.Mvc.Shared.Infrastructure.Extensions.CommonStartupLoaders usually with the main assembly as its argument. The extension method only binds decorated classes from the provided assembly and its referenced assemblies.

// Program.cs

using Datelite.Mvc.Shared.Infrastructure.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Needs environment to load the correct env-specific app configuration.
builder.Configuration.LoadConfiguration(builder.Environment);

builder.RegisterConfigurationModels(Assembly.GetExecutingAssembly());

Bound configuration models can be accessed by injecting an IOptionsSnapshot<TModel> type in constructors, where TModel is a class decorated with ConfigurationModel.

Snapshots provide the actual state of a configuration section. If the configuration changes during runtime, the application does not have to be restarted.

Exception class

The exception class Datelite.Mvc.Shared.DateliteException is used by the library to throw its own exceptions. You can catch it selectively, if you need to.

Support

DATelite cannot officially support public requests at this point.

We can promise that:

• We will use semantic versioning consistently.
• We won't remove any features silently.
• We won't bloat this library with irrelevant features.

License

Our shared .NET MVC utilities package is licensed under the MIT license. Take it, as it is free, but also take care, as everything in this package is provided as-is.