GodelTech.Microservices.Core 8.1.0

GodelTech.Microservices.Core

Overview

GodelTech.Microservices.Core project contains base components and interfaces of Microservices Framework. Whole idea of framework is based on components called initializers.

Initializer contract is defined as follows:

    public interface IMicroserviceInitializer
    {
        void ConfigureServices(IServiceCollection services);

        void Configure(IApplicationBuilder app, IWebHostEnvironment env);
    }

It's easy to see that contracts mimics signature of typical Startup class. Main purpose of initializer is encapsulation of ASP.NET Core application pipeline configuration. E.g. each aspect of pipeline (REST API, HTTPS, Static Files and etc) is configured by dedicated initializer. As result complex unmaintainable Startup class is splitted into number of initializers which are sequentially executed by subclass of MicroserviceStartup. In order to save few lines of code during initializer development MicroserviceInitializerBase class can be used.

MicroserviceStartup is recommended base class for Startup class. In comparison to ordinary Startup this class just few differences:

1. It accepts IConfiguration as constructor parameter and stores it in property named Configuration.
2. Abstract method CreateInitializers must be created by child classes. This method is responsible for initializer chain creation.
3. Virtual methods ConfigureServices() and Configure() are defined.
4. ConfigureServices() and Configure() invoke corresponding methods of initializers to configure ASP.NET Core application.
5. Few common services are registered by ConfigureServices()

Other than this no other logic is included into MicroserviceStartup class.

Quick Start

In order to use microservice framework few simple steps are required:

1. Create ASP.NET Website application using Visual Studio or dotnet cli.
2. Reference latest version of GodelTech.Microservices.Core nuget package and optionally satellite packages you would like to use.
3. Update your Startup.cs file to create initializers used to configure pipeline.

REST API configuration

Please use the following snippet to configure service which uses REST API only:

    public class Startup : MicroserviceStartup
    {
        public Startup(IConfiguration configuration)
            : base(configuration)
        {

        }

        protected override IEnumerable<IMicroserviceInitializer> CreateInitializers()
        {
            yield return new DeveloperExceptionPageInitializer();
            yield return new ExceptionHandlerInitializer();
            yield return new HstsInitializer();

            yield return new GenericInitializer(null, (app, env) => app.UseRouting());
            yield return new GenericInitializer(null, (app, env) => app.UseAuthentication());

            yield return new ApiInitializer();
        }
    }

Razor Pages Configuration

Please use the following snippet to configure service which use Razon Pages only:

    public class Startup : MicroserviceStartup
    {
        public Startup(IConfiguration configuration)
            : base(configuration)
        {

        }

        protected override IEnumerable<IMicroserviceInitializer> CreateInitializers()
        {
            yield return new DeveloperExceptionPageInitializer();
            yield return new ExceptionHandlerInitializer();
            yield return new HstsInitializer();

            yield return new GenericInitializer(null, (app, env) => app.UseStaticFiles());
            yield return new GenericInitializer(null, (app, env) => app.UseRouting());
            yield return new GenericInitializer(null, (app, env) => app.UseAuthentication());

            yield return new RazorPagesInitializer();
        }
    }

ASP.NET MVC Configuration

Please use the following snippet to configure service which use ASP.NET MVC only (REST API will be impicitly registered too):

    public class Startup : MicroserviceStartup
    {
        public Startup(IConfiguration configuration)
            : base(configuration)
        {

        }

        protected override IEnumerable<IMicroserviceInitializer> CreateInitializers()
        {
            yield return new DeveloperExceptionPageInitializer();
            yield return new ExceptionHandlerInitializer();
            yield return new HstsInitializer();

            yield return new GenericInitializer(null, (app, env) => app.UseStaticFiles());
            yield return new GenericInitializer(null, (app, env) => app.UseRouting());
            yield return new GenericInitializer(null, (app, env) => app.UseAuthentication());

            yield return new MvcInitializer();
        }
    }

Mixed usage

REST API, Razor Pages and ASP.NET MVC initializers can be used inside one application. Please avoid situations when the same url can be handled by different components. If this happens first component specified in initializer list wins.

The following snippet is example of microservice using Razor Pages and REST APIs:

    public class Startup : MicroserviceStartup
    {
        public Startup(IConfiguration configuration)
            : base(configuration)
        {

        }

        protected override IEnumerable<IMicroserviceInitializer> CreateInitializers()
        {
            yield return new DeveloperExceptionPageInitializer();
            yield return new ExceptionHandlerInitializer();
            yield return new HstsInitializer();

            yield return new GenericInitializer(null, (app, env) => app.UseStaticFiles());
            yield return new GenericInitializer(null, (app, env) => app.UseRouting());
            yield return new GenericInitializer(null, (app, env) => app.UseAuthentication());

            yield return new ApiInitializer();
            yield return new RazorPagesInitializer();
        }
    }

Initializers

Framework comes with a number of initializers. Full list of initializers and their description can be found in the following table:

Advanced usage

Third-party DI container and logging mechanism

ASP.NET Core provides good configuration by default. At the same time certain functionality can't be provided by default services (dynamic proxies, interceptors and etc.). In order to starting using third-party DI framework your Program.cs must be updated as follows:

    public sealed class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args)
        {
            return Host.CreateDefaultBuilder(args)
                .UseServiceProviderFactory(new AutofacServiceProviderFactory())
                .ConfigureWebHostDefaults(builder => builder.UseStartup<Startup>());
        }
    }

This code snippet configures Autofac container as service provider used by ASP.NET Core application. In order to register Autofac modules in container the following code must be added to your Startup class:

    public void ConfigureContainer(ContainerBuilder builder)
    {
        builder.RegisterModule(new MyApplicationModule());
    }

You can find detailed information regarding configuration in Autofac documentation.

Third-party logging mechanism

In order to use third-party logging libraries your Program.cs file must be updated as follows:

   public sealed class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args)
        {
            return Host.CreateDefaultBuilder(args)
                .UseSerilog(
                    (context, loggerConfiguration) =>
                    {
                        loggerConfiguration.ReadFrom.Configuration(context.Configuration);
                    }
                )
                .ConfigureWebHostDefaults(builder => builder.UseStartup<Startup>());
        }
    }

This snippet configures Serilog as logging provider for ASP.NET Core application.

Cache in-memory

ApiInitializer, MvcInitializer and RazorPagesInitializer has registration to use in-memory cache via IMemoryCache. More information on how to use it can be found here.

Response cache

ApiInitializer, MvcInitializer and RazorPagesInitializer has registration to use response cache headers. More information on how to use it can be found here.

Links

Microservice framework has number of satellite projects:

• GodelTech.Microservices.EntityFrameworkCore. Project contains implementation of repository pattern and can be used to build application data layer.
• GodelTech.Microservices.Swagger. Project contains components used to initialize Swagger UI and Swagger document.
• GodelTech.Microservices.Security. Package contains security initializer for typical ASP.NET Core applications.
• GodelTech.Microservices.Http. Implemntation of HTTP service client which has convinient methods to collaborate with REST APIs.
• GodelTech.Microservices.SharedServices. Project contains set of unitity components which wrap standard static methods. Available wrappers simplify unit test creation by exposing intefaces which mimic static method signatures.