Substantive.AspNetCore.HealthChecks

Opinionated health-check host helpers for .NET services. The library delivers ready-to-use registration, response formatting, and endpoint helpers so every API in the estate exposes consistent readiness and liveness probes.

Highlights

• Pre-registers liveness, CPU, and memory checks using AddHealthChecksHost.
• Optional drive storage and Entity Framework DbContext checks that light up through configuration.
• JSON response writer (HealthReportResponseWriter) that returns detailed status for dashboards and probes.
• MapHealthCheckEndpoints helper that exposes health/readyz and health/livez endpoints with consistent tagging.

Getting Started

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecksHost(options =>
{
    options.EnableDriveHealthCheck = builder.Environment.IsDevelopment();
    options.EnableDbContextHealthCheck = true;
    options.CPUUtilizationUnhealthyThreshold = 90;
});

var app = builder.Build();
app.MapHealthCheckEndpoints();
app.Run();

Service Registration

Call services.AddHealthChecksHost() in Program.cs (after other dependencies). The extension:

1. Creates and validates HealthChecksHostOptions at startup.
2. Registers resource monitoring (IResourceMonitor) required by CPU/memory checks.
3. Adds health checks:
   • LivenessHealthCheck tagged with liveness.
   • CpuHealthCheck and MemoryHealthCheck tagged with readiness.
   • Optional drive storage checks per mounted drive when EnableDriveHealthCheck is true.
   • Optional AddDbContextCheck<TContext> for every registered DbContext when EnableDbContextHealthCheck is true.

Options Reference

All thresholds are validated through HealthChecksHostOptionsValidator and IOptionsValidateOnStart, so misconfigurations fail fast during app startup.

Endpoint Mapping

WebApplicationExtensions.MapHealthCheckEndpoints() maps two endpoints:

• health/readyz → filters checks tagged with readiness or ready.
• health/livez → filters checks tagged with liveness or live.

Both endpoints:

• Use HealthReportResponseWriter to emit camel-cased JSON with enum values serialized as strings.
• Allow response caching by default.
• Can be wrapped in route groups or authorization middleware if needed.

Response Format

HealthReportResponseWriter.WriteDetailResponse serializes the full HealthReport, including individual entry status, description, data, and duration. The writer honors HttpContext.RequestAborted and sets application/json; charset=utf-8.

Customization Tips

• Override thresholds per environment using app configuration (e.g., appsettings.Production.json).
• Add custom health checks by chaining services.AddHealthChecks() after calling AddHealthChecksHost().
• For multi-tenant or multi-region deployments, prepend a path segment or require host filtering by wrapping MapHealthCheckEndpoints() with additional middleware.