Edit

Share via

Health checks in .NET Aspire

  • Article

Health checks provide availability and state information about an app. Health checks are often exposed as HTTP endpoints, but can also be used internally by the app to write logs or perform other tasks based on the current health. Health checks are typically used in combination with an external monitoring service or container orchestrator to check the status of an app. The data reported by health checks can be used for various scenarios:

  • Influence decisions made by container orchestrators, load balancers, API gateways, and other management services. For instance, if the health check for a containerized app fails, it might be skipped by a load balancer routing traffic.
  • Verify that underlying dependencies are available, such as a database or cache, and return an appropriate status message.
  • Trigger alerts or notifications when an app isn't responding as expected.

.NET Aspire health check endpoints

.NET Aspire exposes two default health check HTTP endpoints in Development environments when the AddServiceDefaults and MapDefaultEndpoints methods are called from the Program.cs file:

  • The /health endpoint indicates if the app is running normally where it's ready to receive requests. All health checks must pass for app to be considered ready to accept traffic after starting.

    GET /health

    The /health endpoint returns an HTTP status code 200 and a text/plain value of Healthy when the app is healthy.

  • The /alive indicates if an app is running or has crashed and must be restarted. Only health checks tagged with the live tag must pass for app to be considered alive.

    GET /alive

    The /alive endpoint returns an HTTP status code 200 and a text/plain value of Healthy when the app is alive.

The AddServiceDefaults and MapDefaultEndpoints methods also apply various configurations to your app beyond just health checks, such as OpenTelemetry and service discovery configurations.

Non-development environments

In non-development environments, the /health and /alive endpoints are disabled by default. If you need to enable them, its recommended to protect these endpoints with various routing features, such as host filtering and/or authorization. For more information, see Health checks in ASP.NET Core.

Additionally, it may be advantageous to configure request timeouts and output caching for these endpoints to prevent abuse or denial-of-service attacks. To do so, consider the following modified AddDefaultHealthChecks method:

public static IHostApplicationBuilder AddDefaultHealthChecks(this IHostApplicationBuilder builder)
{
    builder.Services.AddRequestTimeouts(
        configure: static timeouts =>
            timeouts.AddPolicy("HealthChecks", TimeSpan.FromSeconds(5)));

    builder.Services.AddOutputCache(
        configureOptions: static caching =>
            caching.AddPolicy("HealthChecks",
            build: static policy => policy.Expire(TimeSpan.FromSeconds(10))));

    builder.Services.AddHealthChecks()
        // Add a default liveness check to ensure app is responsive
        .AddCheck("self", () => HealthCheckResult.Healthy(), ["live"]);

    return builder;
}

The preceding code:

  • Adds a timeout of 5 seconds to the health check requests with a policy named HealthChecks.
  • Adds a 10-second cache to the health check responses with a policy named HealthChecks.

Now consider the updated MapDefaultEndpoints method:

public static WebApplication MapDefaultEndpoints(this WebApplication app)
{
    var healthChecks = app.MapGroup("");

    healthChecks
        .CacheOutput("HealthChecks")
        .WithRequestTimeout("HealthChecks");

    // All health checks must pass for app to be
    // considered ready to accept traffic after starting
    healthChecks.MapHealthChecks("/health");

    // Only health checks tagged with the "live" tag
    // must pass for app to be considered alive
    healthChecks.MapHealthChecks("/alive", new()
    {
        Predicate = static r => r.Tags.Contains("live")
    });

    return app;
}

The preceding code:

  • Groups the health check endpoints under the / path.
  • Caches the output and specifies a request time with the corresponding HealthChecks policy.

In addition to the updated AddDefaultHealthChecks and MapDefaultEndpoints methods, you must also add the corresponding services for both request timeouts and output caching.

In the appropriate consuming app's entry point (usually the Program.cs file), add the following code:

// Wherever your services are being registered.
// Before the call to Build().
builder.Services.AddRequestTimeouts();
builder.Services.AddOutputCache();

var app = builder.Build();

// Wherever your app has been built, before the call to Run().
app.UseRequestTimeouts();
app.UseOutputCache();

app.Run();

For more information, see Request timeouts middleware in ASP.NET Core and Output caching middleware in ASP.NET Core.

Integration health checks

.NET Aspire integrations can also register additional health checks for your app. These health checks contribute to the returned status of the /health and /alive endpoints. For example, the .NET Aspire PostgreSQL integration automatically adds a health check to verify the following conditions:

  • A database connection could be established
  • A database query could be executed successfully

If either of these operations fail, the corresponding health check also fails.

Configure health checks

You can disable health checks for a given integration using one of the available configuration options. .NET Aspire integrations support Microsoft.Extensions.Configurations to apply settings through config files such as appsettings.json:

{
  "Aspire": {
    "Npgsql": {
      "DisableHealthChecks": true,
    }
  }
}

You can also use an inline delegate to configure health checks:

builder.AddNpgsqlDbContext<MyDbContext>(
    "postgresdb",
    static settings => settings.DisableHealthChecks  = true);

See also