Dependency Injection ==================== | **Namespace**: `Ocelot.DependencyInjection `_ | **Source code**: `DependencyInjection `_ Overview -------- Dependency Injection feature in Ocelot is designed to extend and/or control building of Ocelot core as ASP.NET MVC pipeline services. The main methods are `AddOcelot <#the-addocelot-method>`_ and `AddOcelotUsingBuilder <#the-addocelotusingbuilder-method>`_ of the ``ServiceCollectionExtensions`` class. Use them in **Program.cs** and **Startup.cs** of your ASP.NET MVC gateway app (minimal web app) to enable and build Ocelot pipeline. And of course, the `OcelotBuilder <#the-ocelotbuilder-class>`_ class is the core of Ocelot. IServiceCollection extensions ----------------------------- **Class**: `Ocelot.DependencyInjection.ServiceCollectionExtensions `_ Based on the current implementations for the ``OcelotBuilder`` class, the ``AddOcelot`` method adds default ASP.NET services to DI container. You could call another more extended ``AddOcelotUsingBuilder`` method while configuring services to build and use custom builder via an ``IMvcCoreBuilder`` interface object. The AddOcelot method ^^^^^^^^^^^^^^^^^^^^ **Signatures**: * ``IOcelotBuilder AddOcelot(this IServiceCollection services)`` * ``IOcelotBuilder AddOcelot(this IServiceCollection services, IConfiguration configuration)`` This ``IServiceCollection`` extension method adds default ASP.NET services and Ocelot application services with configuration injected implicitly or explicitly. Note! The method adds **default** ASP.NET services required for Ocelot core in the `AddDefaultAspNetServices <#the-adddefaultaspnetservices-method>`_ method which plays the role of default builder. In this scenario, you do nothing except calling the ``AddOcelot`` method which has been mentioned in feature chapters, if additional startup settings are required. In this case you just reuse default settings to build Ocelot core. The alternative is ``AddOcelotUsingBuilder`` method, see the next section. The AddOcelotUsingBuilder method ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Signatures**: * ``IOcelotBuilder AddOcelotUsingBuilder(this IServiceCollection services, Func customBuilder)`` * ``IOcelotBuilder AddOcelotUsingBuilder(this IServiceCollection services, IConfiguration configuration, Func customBuilder)`` This ``IServiceCollection`` extension method adds Ocelot application services, and it *adds custom ASP.NET services* with configuration injected implicitly or explicitly. Note! The method adds **custom** ASP.NET services required for Ocelot pipeline using custom builder (``customBuilder`` parameter). It is highly recommended to read docs of the `AddDefaultAspNetServices <#the-adddefaultaspnetservices-method>`_ method, or even to review implementation to understand default ASP.NET services which are the minimal part of the gateway pipeline. In this custom scenario, you control everything during ASP.NET MVC pipeline building, and you provide custom settings to build Ocelot core. The OcelotBuilder class ----------------------- **Source code**: `Ocelot.DependencyInjection.OcelotBuilder `_ The ``OcelotBuilder`` class is the core of Ocelot which does the following: - Contructs itself by single public constructor: ``public OcelotBuilder(IServiceCollection services, IConfiguration configurationRoot, Func customBuilder = null)`` - Initializes and stores public properties: **Services** (``IServiceCollection`` object), **Configuration** (``IConfiguration`` object) and **MvcCoreBuilder** (``IMvcCoreBuilder`` object) - Adds **all application services** during construction phase over the ``Services`` property - Adds ASP.NET services by builder using ``Func`` object in these 2 development scenarios: * by default builder (``AddDefaultAspNetServices`` method) if there is no ``customBuilder`` parameter provided * by custom builder with provided delegate object as the ``customBuilder`` parameter - Adds (switches on/off) Ocelot features by: * ``AddSingletonDefinedAggregator`` and ``AddTransientDefinedAggregator`` methods * ``AddCustomLoadBalancer`` method * ``AddDelegatingHandler`` method * ``AddConfigPlaceholders`` method The AddDefaultAspNetServices method ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Class**: `Ocelot.DependencyInjection.OcelotBuilder `_ Currently the method is protected and overriding is forbidden. The role of the method is to inject required services via both ``IServiceCollection`` and ``IMvcCoreBuilder`` interfaces objects for the minimal part of the gateway pipeline. Current implementation is the folowing: .. code-block:: csharp protected IMvcCoreBuilder AddDefaultAspNetServices(IMvcCoreBuilder builder, Assembly assembly) { Services .AddLogging() .AddMiddlewareAnalysis() .AddWebEncoders(); return builder .AddApplicationPart(assembly) .AddControllersAsServices() .AddAuthorization() .AddNewtonsoftJson(); } The method cannot be overridden. It is not virtual, and there is no way to override current behavior by inheritance. And, the method is default builder of Ocelot pipeline while calling the `AddOcelot <#the-addocelot-method>`_ method. As alternative, to "override" this default builder, you can design and reuse custom builder as a ``Func`` delegate object and pass it as parameter to the `AddOcelotUsingBuilder <#the-addocelotusingbuilder-method>`_ extension method. It gives you full control on design and buiding of Ocelot pipeline, but be careful while designing your custom Ocelot pipeline as customizable ASP.NET MVC pipeline. Warning! Most of services from minimal part of the pipeline should be reused, but only a few of services could be removed. Warning!! The method above is called after adding required services of ASP.NET MVC pipeline building by `AddMvcCore `_ method over the ``Services`` property in upper calling context. These services are absolute minimum core services for ASP.NET MVC pipeline. They must be added to DI container always, and they are added implicitly before calling of the method by caller in upper context. So, ``AddMvcCore`` creates an ``IMvcCoreBuilder`` object with its assignment to the ``MvcCoreBuilder`` property. Finally, as a default builder, the method above receives ``IMvcCoreBuilder`` object being ready for further extensions. The next section shows you an example of designing custom Ocelot pipeline by custom builder. Custom Builder -------------- **Goal**: Replace ``Newtonsoft.Json`` services with ``System.Text.Json`` services. The Problem ^^^^^^^^^^^ The default `AddOcelot <#the-addocelot-method>`_ method adds `Newtonsoft JSON `_ services by the ``AddNewtonsoftJson`` extension method in default builder (the `AddDefaultAspNetServices <#the-adddefaultaspnetservices-method>`_ method). The ``AddNewtonsoftJson`` method calling was introduced in old .NET and Ocelot releases which was necessary when Microsoft did not launch the ``System.Text.Json`` library, but now it affects normal use, so we have an intention to solve the problem. Modern `JSON services `_ out of `the box `_ will help to configure JSON settings by the ``JsonSerializerOptions`` property for JSON formatters during (de)serialization. Solution ^^^^^^^^ We have the following methods in ``Ocelot.DependencyInjection.ServiceCollectionExtensions`` class: - ``IOcelotBuilder AddOcelotUsingBuilder(this IServiceCollection services, Func customBuilder)`` - ``IOcelotBuilder AddOcelotUsingBuilder(this IServiceCollection services, IConfiguration configuration, Func customBuilder)`` These method with custom builder allows you to use your any desired JSON library for (de)serialization. But we are going to create custom ``MvcCoreBuilder`` with support of JSON services, such as ``System.Text.Json``. To do that we need to call ``AddJsonOptions`` extension of the ``MvcCoreMvcCoreBuilderExtensions`` class (NuGet package: `Microsoft.AspNetCore.Mvc.Core `_) in **Startup.cs**: .. code-block:: csharp using Microsoft.Extensions.DependencyInjection; using Ocelot.DependencyInjection; using System.Reflection; public class Startup { public void ConfigureServices(IServiceCollection services) { services .AddLogging() .AddMiddlewareAnalysis() .AddWebEncoders() // Add your custom builder .AddOcelotUsingBuilder(MyCustomBuilder); } private static IMvcCoreBuilder MyCustomBuilder(IMvcCoreBuilder builder, Assembly assembly) { return builder .AddApplicationPart(assembly) .AddControllersAsServices() .AddAuthorization() // Replace AddNewtonsoftJson() by AddJsonOptions() .AddJsonOptions(options => { options.JsonSerializerOptions.WriteIndented = true; // use System.Text.Json }); } } The sample code provides settings to render JSON as indented text rather than compressed plain JSON text without spaces. This is just one common use case, and you can add additional services to the builder.