Quilt4Net.Toolkit.Health 0.6.0

Quilt4Net.Toolkit.Health

Add configurable health endpoints, heartbeat telemetry, and service monitoring to .NET Web Applications.

Get started

Install the NuGet package Quilt4Net.Toolkit.Health and register the services in Program.cs.

var builder = WebApplication.CreateBuilder(args);

builder.AddQuilt4NetHealth();

var app = builder.Build();

app.UseRouting();
app.UseQuilt4NetHealth();

app.Run();

UseRouting() must be called before UseQuilt4NetHealth().

Endpoints

Six endpoints are available by default. The base path is ~/api/Health (configurable via Pattern and ControllerName).

All endpoints support both GET (returns JSON body) and HEAD (returns status in header), except Metrics and Version which are GET only.

Components

Components are services or resources that your application depends on. Add them to include in Health and Ready checks.

Inline check

builder.AddQuilt4NetHealth(o =>
{
    o.AddComponent(new Component
    {
        Name = "database",
        Essential = true,
        CheckAsync = async sp =>
        {
            // perform check
            return new CheckResult { Success = true, Message = "Connected" };
        }
    });
});

Set Essential = true for critical components (failure = Unhealthy/Unready). Set Essential = false for non-critical components (failure = Degraded).

Component service

For complex checks, implement IComponentService to separate setup from logic.

builder.AddQuilt4NetHealth(o =>
{
    o.AddComponentService<MyComponentService>();
});

Dependencies

Register external services that use Quilt4Net Health API. The dependency endpoint calls their health check.

builder.AddQuilt4NetHealth(o =>
{
    o.AddDependency(new Dependency
    {
        Name = "payment-service",
        Essential = true,
        Uri = new Uri("https://payment.example.com/api/Health/")
    });
});

Heartbeat

The heartbeat feature sends periodic availability telemetry to Application Insights.

Enable heartbeat

builder.AddQuilt4NetHealth(o =>
{
    o.Heartbeat.Enabled = true;
    o.Heartbeat.Interval = TimeSpan.FromMinutes(5);
});

The heartbeat starts when UseQuilt4NetHealth() is called.

TelemetryClient resolution

The heartbeat resolves a TelemetryClient in this order:

1. From DI - If AddApplicationInsightsTelemetry() has been called, that client is used.
2. From HeartbeatOptions - If Heartbeat.ConnectionString is set, a client is created from it.
3. None - A warning is logged and heartbeat execution is skipped.

builder.AddQuilt4NetHealth(o =>
{
    o.Heartbeat.Enabled = true;
    o.Heartbeat.ConnectionString = builder.Configuration["ApplicationInsights:ConnectionString"];
});

HeartbeatOptions

Service probe

Monitor the health of background services and hosted services through a pulse mechanism.

Inject IHostedServiceProbe<T> into your hosted service and call Pulse() on each iteration.

public class MyBackgroundService : BackgroundService
{
    private readonly IHostedServiceProbe _probe;

    public MyBackgroundService(IHostedServiceProbe<MyBackgroundService> probe)
    {
        _probe = probe.Register(plannedInterval: TimeSpan.FromSeconds(30));
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            _probe.Pulse();

            // do work...

            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
        }
    }
}

The probe tracks pulse timing and reports status in Health responses:

• Healthy - Pulse received within the expected interval.
• Degraded - Pulse slightly delayed.
• Unhealthy - Pulse significantly delayed or missing.

Certificate check

Automatically checks SSL certificate expiry for your service and its dependencies.

Configuration

All options can be set via code, appsettings.json, or a combination of both. Priority order:

1. Code - Highest priority, overrides everything.
2. appsettings.json - Overrides defaults.
3. Defaults - Used when nothing else is configured.

Code configuration

builder.AddQuilt4NetHealth(o =>
{
    o.Pattern = "api";
    o.ControllerName = "Health";
    o.FailReadyWhenDegraded = true;
    o.Heartbeat.Enabled = true;
});

appsettings.json

{
  "Quilt4Net": {
    "HealthApi": {
      "Pattern": "api",
      "ControllerName": "Health",
      "FailReadyWhenDegraded": true,
      "Heartbeat": {
        "Enabled": true,
        "Interval": "00:05:00",
        "ConnectionString": "InstrumentationKey=..."
      },
      "Certificate": {
        "CertExpiryDegradedLimitDays": 30,
        "CertExpiryUnhealthyLimitDays": 3
      }
    }
  }
}

Quilt4NetHealthApiOptions

Endpoint access

Each endpoint has configurable access control and visibility.

builder.AddQuilt4NetHealth(o =>
{
    o.Endpoints[HealthEndpoint.Metrics].Get.Access.Level = AccessLevel.AuthenticatedOnly;
    o.Endpoints[HealthEndpoint.Health].Get.State = EndpointState.Hidden;
});

EndpointState: Visible (shown in docs), Hidden (accessible but not in docs), Disabled (not accessible).

AccessLevel: Everyone, AuthenticatedOnly.

DetailsLevel: Everyone, AuthenticatedOnly, NoOne - controls response detail in GET requests.

Environment defaults

Troubleshooting

Startup error: EndpointRoutingMiddleware matches endpoints setup by EndpointMiddleware...

Add app.UseRouting() before app.UseQuilt4NetHealth() in Program.cs.