GodelTech.Microservices.Core 8.1.0

dotnet add package GodelTech.Microservices.Core --version 8.1.0                
NuGet\Install-Package GodelTech.Microservices.Core -Version 8.1.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="GodelTech.Microservices.Core" Version="8.1.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add GodelTech.Microservices.Core --version 8.1.0                
#r "nuget: GodelTech.Microservices.Core, 8.1.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install GodelTech.Microservices.Core as a Cake Addin
#addin nuget:?package=GodelTech.Microservices.Core&version=8.1.0

// Install GodelTech.Microservices.Core as a Cake Tool
#tool nuget:?package=GodelTech.Microservices.Core&version=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:

Initializer Description
ApiInitializer Initializer configures REST API controllers and configures set of frequently used action filters and JSON formatting settings.
MvcInitializer Initializer is reponsible for MVC controllers with views configuration. When this controller is used REST API initialization is also performed. Additional use of ApiInitializer is not required.
RazorPagesInitializer Component is reponsible for Razor Pages configuration.
GenericInitializer This initialize accepts lamda function as parameters. These functions are used by ConfigureServices() and Configure() method. This initializer can be used when single line pipeline configuration is performed and creation of dedicated initializer is not reasonable.
DeveloperExceptionPageInitializer Component is reponsible for exception handling pages configuration. If application is executed in Development environment developer exception page is used.
ExceptionHandlerInitializer Component is reponsible for exception handling configuration. If environment differs from Development exception handler is used.
HstsInitializer HTTP configuration is performed by this initializer.
HealthCheckInitializer Health check infrastructure is configured by this initializer.
CommonMiddlewareInitializer This class configures number of frequently used middlewares such as CorrelationIdMiddleware, LogUncaughtErrorsMiddleware and RequestResponseLoggingMiddleware.

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.

Microservice framework has number of satellite projects:

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (7)

Showing the top 5 NuGet packages that depend on GodelTech.Microservices.Core:

Package Downloads
GodelTech.Microservices.Swagger

Library provides initializer which configures Swagger endpoinds and Swagger UI.

GodelTech.Microservices.Security

Library contains initializer responsible for REST API endpoint security configuration.

GodelTech.Microservices.SharedServices

Package Description

GodelTech.Microservices.EntityFrameworkCore

Package Description

GodelTech.Microservices.Data.EntityFrameworkCore

Microservice initializer for GodelTech.Data.EntityFrameworkCore.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
8.1.0 511 7/2/2024
8.0.1 2,632 1/20/2024
8.0.0 236 1/17/2024
3.0.1 2,117 9/17/2023
3.0.0 136 8/25/2023
2.7.0 8,022 11/2/2022
2.6.0 1,294 10/17/2022
2.5.0 5,286 7/31/2022
2.4.2 654 7/31/2022
2.4.1 821 7/27/2022
2.4.0 5,176 7/7/2022
2.3.0 1,260 4/4/2022
2.2.0 921 4/3/2022
2.1.0 991 1/29/2022
2.0.0 803 1/10/2022 2.0.0 is deprecated.
1.4.1 7,964 4/4/2021
1.4.0 14,414 3/15/2021
1.3.1 1,008 1/3/2021
1.3.0 1,671 9/10/2020
1.2.0 791 8/25/2020
1.1.1 1,450 7/25/2020
1.1.0 643 7/19/2020
1.0.8 628 5/13/2020
1.0.7 1,077 5/12/2020
1.0.6 477 5/10/2020
1.0.5 514 5/7/2020
1.0.4 1,775 5/4/2020
1.0.3 629 5/3/2020
1.0.2 1,150 5/3/2020
1.0.1 1,385 5/3/2020
1.0.0 599 5/3/2020
1.0.0-rc.2 292 4/19/2020