Dosaic.Hosting.Abstractions 1.2.8

Dosaic.Hosting.Abstractions

Dosaic.Hosting.Abstractions is the core abstraction/interface package that allows .NET developers to build their own Dosaic plugins. Every plugin in the Dosaic ecosystem depends on this package.

Installation

dotnet add package Dosaic.Hosting.Abstractions

or add as a package reference to your .csproj:

<PackageReference Include="Dosaic.Hosting.Abstractions" Version="" />

Usage

Creating a Plugin

A plugin is any public, non-abstract class that implements one or more of the plugin interfaces below. The source generator in Dosaic.Hosting.Generator automatically discovers all such classes at compile time — no runtime reflection or manual registration needed.

using Dosaic.Hosting.Abstractions.Plugins;
using Microsoft.Extensions.DependencyInjection;

namespace MyCompany.MyPlugin
{
    public class MyPlugin : IPluginServiceConfiguration, IPluginApplicationConfiguration
    {
        public void ConfigureServices(IServiceCollection serviceCollection)
        {
            serviceCollection.AddTransient<IMyService, MyService>();
        }

        public void ConfigureApplication(IApplicationBuilder applicationBuilder)
        {
            applicationBuilder.UseMyMiddleware();
        }
    }
}

Plugin Interfaces

All plugin interfaces live in Dosaic.Hosting.Abstractions.Plugins and extend IPluginActivateable.

Plugin execution order

IPluginServiceConfiguration

Called during service-collection setup. Use this for DI registrations.

public class MyPlugin : IPluginServiceConfiguration
{
    public void ConfigureServices(IServiceCollection serviceCollection)
    {
        serviceCollection.AddTransient<IMyService, MyService>();
        serviceCollection.AddSingleton<MyOptions>();
    }
}

IPluginApplicationConfiguration

Called after WebApplication.Build(). Use this for UseXyz() pipeline calls.

public class MyPlugin : IPluginApplicationConfiguration
{
    public void ConfigureApplication(IApplicationBuilder applicationBuilder)
    {
        applicationBuilder.UseRouting();
        applicationBuilder.UseAuthentication();
    }
}

IPluginEndpointsConfiguration

Registers minimal API endpoints. Called during endpoint routing setup.

public class MyPlugin : IPluginEndpointsConfiguration
{
    public void ConfigureEndpoints(IEndpointRouteBuilder endpointRouteBuilder, IServiceProvider serviceProvider)
    {
        endpointRouteBuilder.MapGet("/hello", () => "Hello, World!")
            .RequireAuthorization();
    }
}

IPluginHealthChecksConfiguration

Registers health checks programmatically. See also the health check attributes for declarative registration.

public class MyPlugin : IPluginHealthChecksConfiguration
{
    public void ConfigureHealthChecks(IHealthChecksBuilder healthChecksBuilder)
    {
        healthChecksBuilder.AddUrlGroup(
            new Uri("https://my-dependency/health"),
            "my-dependency",
            HealthStatus.Unhealthy,
            new[] { HealthCheckTag.Readiness });
    }
}

IPluginControllerConfiguration

Configures the MVC builder (e.g. options, formatters, assemblies).

public class MyPlugin : IPluginControllerConfiguration
{
    public void ConfigureControllers(IMvcBuilder controllerBuilder)
    {
        controllerBuilder.AddMvcOptions(options => options.RespectBrowserAcceptHeader = true);
        controllerBuilder.AddApplicationPart(typeof(MyPlugin).Assembly);
    }
}

IPluginConfigurator

A sub-configurator is a small, focused configuration object that is automatically collected and injected as an array into plugins that declare a constructor parameter of type IPluginConfigurator[] (or IEnumerable<IPluginConfigurator>).

// Sub-configurator defined anywhere in the application
public class MyFeatureConfigurator : IPluginConfigurator
{
    public string ConnectionString { get; set; } = "...";
}

// Plugin that receives all configurators
public class MyPlugin : IPluginServiceConfiguration
{
    private readonly MyFeatureConfigurator[] _configurators;

    public MyPlugin(MyFeatureConfigurator[] configurators)
    {
        _configurators = configurators;
    }

    public void ConfigureServices(IServiceCollection serviceCollection) { ... }
}

Attributes

[Configuration]

Decorating a class with [Configuration("section")] causes the web host to automatically bind the class to the corresponding section in appsettings.* files or environment variables. The bound instance is then injectable as a constructor parameter in any plugin.

# appsettings.yaml
myFeature:
  connectionString: "Server=localhost"
  timeout: 30

using Dosaic.Hosting.Abstractions.Attributes;

[Configuration("myFeature")]
public class MyFeatureConfiguration
{
    public string ConnectionString { get; set; }
    public int Timeout { get; set; }
}

// Consume in any plugin via constructor injection
public class MyPlugin : IPluginServiceConfiguration
{
    private readonly MyFeatureConfiguration _config;

    public MyPlugin(MyFeatureConfiguration config)
    {
        _config = config;
    }

    public void ConfigureServices(IServiceCollection serviceCollection) { ... }
}

Nested sections are supported using : as the delimiter:

[Configuration("database:primary")]
public class PrimaryDbConfig { ... }

[Middleware]

Marks an ApiMiddleware subclass for automatic registration in the middleware pipeline. The optional order parameter controls execution order (default: int.MaxValue — runs last). Lower values run earlier.

using Dosaic.Hosting.Abstractions.Attributes;

[Middleware(order: 100)]
public class MyMiddleware : ApiMiddleware
{
    public MyMiddleware(RequestDelegate next, IDateTimeProvider dateTimeProvider)
        : base(next, dateTimeProvider) { }

    public override async Task Invoke(HttpContext context)
    {
        // before
        await Next.Invoke(context);
        // after
    }
}

Built-in middlewares and their order:

[ReadinessCheckAttribute]

Registers an IHealthCheck implementation as a readiness health check (tags it with HealthCheckTag.Readiness).

using Dosaic.Hosting.Abstractions.Attributes;

[ReadinessCheck("database")]
public class DatabaseHealthCheck : IHealthCheck
{
    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        // check connectivity ...
        return HealthCheckResult.Healthy("Database is reachable.");
    }
}

[LivenessCheckAttribute]

Registers an IHealthCheck implementation as a liveness health check (tags it with HealthCheckTag.Liveness).

[LivenessCheck("application")]
public class ApplicationLivenessCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
        => Task.FromResult(HealthCheckResult.Healthy());
}

Both attributes can be combined on the same class, and additional tags can be passed via the overloaded constructors:

[ReadinessCheck("kafka")]
[LivenessCheck("kafka")]
public class KafkaHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        // check Kafka connectivity
        return Task.FromResult(HealthCheckResult.Healthy("Kafka is available."));
    }
}

[YamlTypeConverterAttribute]

Attaches a custom YAML type converter to a class or struct so that it is used during SerializationExtensions.Serialize / Deserialize calls with SerializationMethod.Yaml. The converter type must implement IYamlConverter.

using Dosaic.Hosting.Abstractions.Attributes;

[YamlTypeConverter(typeof(MyTypeConverter))]
public class MySpecialType { ... }

public class MyTypeConverter : IYamlConverter
{
    public object ReadYaml(IParser parser, Type type, ObjectDeserializer rootDeserializer) { ... }
    public void WriteYaml(IEmitter emitter, object value, Type type, ObjectSerializer serializer) { ... }
}

HealthCheckTag

HealthCheckTag is a validated value object (via Vogen) with two predefined instances:

Custom tags are supported:

var tag = HealthCheckTag.From("custom-tag");

Exceptions

All domain exceptions extend DosaicException, which carries an HttpStatus property automatically used by ExceptionMiddleware to produce the correct HTTP response.

using Dosaic.Hosting.Abstractions.Exceptions;

// Simple usage
throw new NotFoundDosaicException("Order", orderId);
// → message: "Could not find Order with id '42'"

throw new ConflictDosaicException("An order with this reference already exists.");

throw new ValidationDosaicException("Validation failed", new List<FieldValidationError>
{
    new("email", "must be a valid email address"),
    new("amount", "must be greater than 0")
});

// Throw with a custom HTTP status
throw new DosaicException("Service unavailable.", StatusCodes.Status503ServiceUnavailable);

Error Response Models

ExceptionMiddleware produces JSON responses using these models from Dosaic.Hosting.Abstractions.Middlewares.Models:

// Standard error response
record ErrorResponse(DateTime Timestamp, string Message, string RequestId);

// Validation error response (extends ErrorResponse)
record ValidationErrorResponse : ErrorResponse
{
    IEnumerable<FieldValidationError> ValidationErrors { get; }
}

// Single field validation error
record FieldValidationError(string Field, string ValidationMessage);

IImplementationResolver

IImplementationResolver is the runtime service used internally by the web host to discover and instantiate plugins. It is also injectable into plugins for advanced scenarios.

public interface IImplementationResolver
{
    List<Type> FindTypes();
    List<Assembly> FindAssemblies();
    object ResolveInstance(Type type);
    void ClearInstances();
}

Convenience extensions from ImplementationResolverExtensions:

// Find all types matching a predicate
List<Type> types = resolver.FindTypes(t => t.HasAttribute<MyAttribute>());

// Find and instantiate all types matching a predicate
List<object> instances = resolver.FindAndResolve(t => t.Implements<IMyService>());

// Find and instantiate all implementations of T
List<IMyService> services = resolver.FindAndResolve<IMyService>();

IFactory<T>

IFactory<TService> is a lightweight factory abstraction for resolving services lazily or optionally from the DI container. Register using AddFactory<T>().

using Dosaic.Hosting.Abstractions.DependencyInjection;
using Dosaic.Hosting.Abstractions.Extensions;

// Registration
serviceCollection.AddFactory<IMyService>();

// Injection and usage
public class MyConsumer
{
    private readonly IFactory<IMyService> _factory;

    public MyConsumer(IFactory<IMyService> factory) => _factory = factory;

    public void DoWork()
    {
        var service = _factory.Create();             // throws if not registered
        var serviceOrNull = _factory.CreateOrNull(); // returns null if not registered
    }
}

Metrics

Dosaic uses OpenTelemetry for metrics. The static Metrics class provides typed factory methods that cache instrument instances, preventing duplicate-creation errors.

using Dosaic.Hosting.Abstractions.Metrics;

// Counter
var counter = Metrics.CreateCounter<long>("my_requests_total", "calls", "Total number of requests");
counter.Add(1);
counter.Add(1, new KeyValuePair<string, object>("status", "ok"));

// Histogram
var histogram = Metrics.CreateHistogram<double>("my_request_duration_seconds", "s", "Request duration");
histogram.Record(0.42);

// Observable gauge (value polled by the metrics exporter)
Metrics.CreateObservableGauge("queue_depth", () => GetQueueDepth(), "items", "Current queue depth");

// Observable counter
Metrics.CreateObservableCounter("processed_total", () => GetProcessedCount(), "items", "Total processed");

Access the underlying Meter directly for advanced scenarios:

var upDownCounter = Metrics.Meter.CreateUpDownCounter<int>("active_connections", "connections");

Tracing

DosaicDiagnostic

DosaicDiagnostic.CreateSource() creates an ActivitySource named after the calling class's fully-qualified name using the call stack. Call it from a static field initializer.

using Dosaic.Hosting.Abstractions;
using System.Diagnostics;

public class MyService
{
    private static readonly ActivitySource _activitySource = DosaicDiagnostic.CreateSource();

    public async Task DoWorkAsync()
    {
        using var activity = _activitySource.StartActivity("DoWork");
        // ... work ...
    }
}

Constants:

TracingExtensions

using Dosaic.Hosting.Abstractions.Extensions;

// Wraps an async call and auto-sets Ok/Error activity status
var result = await _activitySource.TrackStatusAsync(async activity =>
{
    activity?.SetTag("input", input);
    return await _service.ProcessAsync(input);
});

// Set tags in bulk with an optional prefix
activity.SetTags(new Dictionary<string, string> { ["key"] = "value" }, prefix: "app.");

// Manually set status
activity.SetOkStatus();
activity.SetErrorStatus(exception);

Serialization

SerializationExtensions provides uniform JSON and YAML serialization.

using Dosaic.Hosting.Abstractions.Extensions;

var obj = new MyDto { Name = "hello" };

// JSON (default)
string json = obj.Serialize();
MyDto dto = json.Deserialize<MyDto>();

// YAML
string yaml = obj.Serialize(SerializationMethod.Yaml);
MyDto dto2 = yaml.Deserialize<MyDto>(SerializationMethod.Yaml);

// Access the default JsonSerializerOptions (camelCase, enums as strings, etc.)
var options = SerializationExtensions.DefaultOptions;

IKindSpecifier — Polymorphic deserialization

Implementing IKindSpecifier on an interface enables discriminated-union deserialization where the concrete type is selected based on a Kind property in the JSON/YAML payload.

public interface IShape : IKindSpecifier { }

public class Circle : IShape
{
    public string Kind => "circle";
    public double Radius { get; set; }
}

public class Rectangle : IShape
{
    public string Kind => "rectangle";
    public double Width { get; set; }
    public double Height { get; set; }
}

// Deserializes to Circle or Rectangle depending on the "kind" field
IShape shape = """{"kind":"circle","radius":5}""".Deserialize<IShape>();

Utility Extensions

ObjectExtensions — DeepPatch

Applies non-null property values from a patch object onto a target, with configurable behaviour for nested objects and lists.

using Dosaic.Hosting.Abstractions.Extensions;

var original = new MyEntity { Name = "Old", Tags = new List<string> { "a" } };
var patch    = new MyEntity { Name = "New", Tags = new List<string> { "b" } };

original.DeepPatch(patch);
// original.Name == "New", original.Tags == ["a", "b"]   (new items are merged)

original.DeepPatch(patch, PatchMode.OverwriteLists);
// original.Tags == ["b"]                                 (list is replaced)

PatchMode flags: Full, IgnoreLists, IgnoreObjects, OverwriteLists.

StringExtensions

"MyPropertyName".ToSnakeCase();     // "my_property_name"
"hello world".ToUrlEncoded();       // "hello%20world"
"hello%20world".FromUrlEncoded();   // "hello world"

ConfigurationExtensions

// Bind a config section to a new instance of T
var opts = configuration.BindToSection<MyOptions>("myFeature");

TypeExtensions

typeof(MyClass).Implements<IMyInterface>()   // true / false
typeof(MyClass).HasAttribute<MyAttribute>()  // true / false
typeof(MyClass).GetAttribute<MyAttribute>()  // attribute instance or null
typeof(MyClass).CanBeInstantiated()          // !IsAbstract && !IsInterface
typeof(MyClass).GetNormalizedName()          // human-readable generic type name

EnumerableExtensions

items.ForEach(item => Console.WriteLine(item));

EnumExtensions

PatchMode.IgnoreLists.IsFlagSet(PatchMode.IgnoreLists); // true

GlobalStatusCodeOptions

Controls which HTTP status codes are automatically rewritten to the standard ErrorResponse JSON format by ExceptionMiddleware. Default codes: 401, 403, 404, 406, 415, 500.

// Customise in a plugin's ConfigureServices:
serviceCollection.Configure<GlobalStatusCodeOptions>(opts =>
{
    opts.Add(HttpStatusCode.ServiceUnavailable);
    opts.Remove(HttpStatusCode.NotFound);
    opts.Clear(); // remove all defaults
});

ApiMiddleware

ApiMiddleware is the abstract base class for all Dosaic middlewares. Subclass it and decorate with [Middleware] for automatic registration in the pipeline.

using Dosaic.Hosting.Abstractions;
using Dosaic.Hosting.Abstractions.Attributes;
using Chronos.Abstractions;

[Middleware(order: 50)]
public class CorrelationIdMiddleware : ApiMiddleware
{
    public CorrelationIdMiddleware(RequestDelegate next, IDateTimeProvider dateTimeProvider)
        : base(next, dateTimeProvider) { }

    public override async Task Invoke(HttpContext context)
    {
        if (!context.Request.Headers.TryGetValue("X-Correlation-Id", out _))
            context.Response.Headers.Append("X-Correlation-Id", Guid.NewGuid().ToString());

        await Next.Invoke(context);
    }
}

Helper methods available inside ApiMiddleware:

// Write a typed JSON response
await WriteResponse(context, StatusCodes.Status200OK, new { ok = true });

// Write the standard ErrorResponse JSON
await WriteDefaultResponse(context, StatusCodes.Status400BadRequest, "Custom message");