Meziantou.Framework

Overview

edit

Meziantou.AspNetCore.ServiceDefaults gives a web application the setup that production needs, in two calls: UseMeziantouConventions on the builder registers the services, and MapMeziantouDefaultEndpoints on the application adds the middleware and the endpoints.

var builder = WebApplication.CreateBuilder(args);

// Add Meziantou service defaults
builder.UseMeziantouConventions();

var app = builder.Build();

// Map default endpoints (health checks, OpenAPI, etc.)
app.MapMeziantouDefaultEndpoints();

app.MapGet("/", () => "Hello World!");

app.Run();

The extension methods are in the Meziantou.AspNetCore.ServiceDefaults namespace. UseMeziantouConventions works on any IHostApplicationBuilder; MapMeziantouDefaultEndpoints extends WebApplication.

What the builder gets

UseMeziantouConventions configures:

  • Dependency injection validation: the service provider is built with ValidateOnBuild and ValidateScopes, so a missing registration or a scoped service injected into a singleton makes builder.Build() throw instead of failing on the first request.
  • OpenTelemetry: logs (with the formatted message and the scopes), metrics (ASP.NET Core, HttpClient, the .NET runtime and the Meziantou.* meters) and traces (ASP.NET Core with SignalR, HttpClient, the Meziantou.* sources and a source named after the application). The /health and /alive requests are not traced. The service name is OTEL_SERVICE_NAME when it is set, the application name otherwise, and the service version is the version of the entry assembly. The OTLP exporter is enabled when OTEL_EXPORTER_OTLP_ENDPOINT is set.
  • Health checks: a self check tagged live.
  • OpenAPI: AddOpenApi, for the document served by MapMeziantouDefaultEndpoints.
  • HTTP clients: service discovery, the standard resilience handler (retries, timeouts, circuit breaker) and a User-Agent header named after the application, on every client created by IHttpClientFactory.
  • JSON: camelCase names, string enums and the other conventions described in JSON conventions, for minimal APIs and for controllers.
  • Problem details and validation: AddProblemDetails and AddValidation.
  • Antiforgery: AddAntiforgery.
  • Kestrel: the Server response header is no longer sent.

Each feature that can be turned off has an option; see Options.

What the application gets

MapMeziantouDefaultEndpoints adds forwarded headers, the no-cache default, HTTPS redirection, an exception handler and HSTS outside Development, and antiforgery, then maps /health, /alive, the static assets and the OpenAPI document. The order and the details are in Default endpoints and middleware.

Forgetting a call

The two calls go together. When MapMeziantouDefaultEndpoints is not called, the application throws an InvalidOperationException that names the missing call when it starts, rather than running without its health checks and security middleware.

Calling it more than once

UseMeziantouConventions registers everything again each time it is called. Code that cannot know whether the conventions are already registered, such as a shared extension method, calls TryUseMeziantouConventions, which does nothing when they are:

builder.UseMeziantouConventions();
builder.TryUseMeziantouConventions(); // Will not register again

When TryUseMeziantouConventions does nothing, its options are ignored: the options of the first call apply. MapMeziantouDefaultEndpoints can be called more than once; the calls after the first do nothing.

Applying the defaults without writing the calls

The Meziantou.AspNetCore.ServiceDefaults.AutoRegister package adds both calls to every WebApplicationBuilder.Build() of your project. See Applying the defaults automatically.

In this group