Advanced ASP.NET Core Health Checks

Introduction

ASP.NET Core is designed for building high‑performance, cloud‑native Web APIs. In modern deployments—especially with Docker, Kubernetes, and load balancers—applications must continuously report their health status.

Health checks in ASP.NET Core Web API provide a standardized way to expose application health so that:

Load balancers can route traffic correctly
Container orchestrators can restart unhealthy services
Monitoring systems can raise alerts
DevOps teams can diagnose failures quickly

This article explains health checks in ASP.NET Core Web API with a clear, end‑to‑end, production‑ready approach suitable for real‑world systems.

What Are Health Checks in ASP.NET Core?

A health check is a lightweight endpoint that reports whether an ASP.NET Core application and its dependencies are functioning correctly.

ASP.NET Core health checks can validate:

API availability
Database connectivity
External services
Memory and system resources
Custom business services

Health checks return one of three states:

Healthy – The application is operating normally
Degraded – The application is running with reduced functionality
Unhealthy – The application cannot function correctly

Installing Required Packages

Add the required NuGet packages to your ASP.NET Core Web API project:

Microsoft.AspNetCore.Diagnostics.HealthChecks
Microsoft.Extensions.Diagnostics.HealthChecks
AspNetCore.HealthChecks.SqlServer

These packages integrate seamlessly with the ASP.NET Core middleware pipeline.

Configuring Basic Health Checks

Health checks are configured in Program.cs.

Register Health Check Services

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/health");

app.Run();

When you access /health, the API responds with:

Healthy

This confirms that the ASP.NET Core application is running.

Adding Dependency Health Checks

Real‑world ASP.NET Core APIs rely on external dependencies. Health checks ensure those dependencies are available before serving traffic.

SQL Server Health Check

builder.Services.AddHealthChecks()
    .AddSqlServer(
        connectionString: builder.Configuration.GetConnectionString("DefaultConnection"),
        name: "sql-database",
        failureStatus: HealthStatus.Unhealthy,
        timeout: TimeSpan.FromSeconds(5));

This check verifies that the API can connect to the database and marks the service as Unhealthy if the database is unavailable.

Memory Health Check

builder.Services.AddHealthChecks()
    .AddWorkingSetHealthCheck(
        maximumWorkingSetBytes: 512 * 1024 * 1024,
        name: "memory");

This prevents the API from running under excessive memory pressure, which is critical in containerized environments.

External API Health Check

builder.Services.AddHealthChecks()
    .AddUrlGroup(
        new Uri("https://api.github.com"),
        name: "external-api");

This ensures dependent external services are reachable.

Creating Custom Health Checks in ASP.NET Core

ASP.NET Core allows custom health checks by implementing the IHealthCheck interface.

using Microsoft.Extensions.Diagnostics.HealthChecks;

public class CustomServiceHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        bool isServiceHealthy = true; // Custom logic

        if (isServiceHealthy)
            return Task.FromResult(HealthCheckResult.Healthy("Service is running"));

        return Task.FromResult(HealthCheckResult.Unhealthy("Service is unavailable"));
    }
}

builder.Services.AddHealthChecks()
    .AddCheck<CustomServiceHealthCheck>("custom-service");

Returning Structured JSON Responses

In production systems, structured JSON responses are preferred over plain text.

app.MapHealthChecks("/health", new HealthCheckOptions
{
    ResponseWriter = async (context, report) =>
    {
        context.Response.ContentType = "application/json";

        var response = new
        {
            status = report.Status.ToString(),
            checks = report.Entries.Select(entry => new
            {
                name = entry.Key,
                status = entry.Value.Status.ToString(),
                description = entry.Value.Description
            })
        };

        await context.Response.WriteAsJsonAsync(response);
    }
});

Liveness and Readiness Probes in ASP.NET Core

For container orchestration platforms like Kubernetes, health checks are divided into two categories.

Liveness Probe

app.MapHealthChecks("/health/live", new HealthCheckOptions
{
    Predicate = _ => false
});

The liveness probe confirms that the ASP.NET Core process is running.

Readiness Probe

app.MapHealthChecks("/health/ready", new HealthCheckOptions
{
    Predicate = check => check.Tags.Contains("ready")
});

builder.Services.AddHealthChecks()
    .AddSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection"),
        tags: new[] { "ready" });

Health Checks UI Dashboard

ASP.NET Core supports a Health Checks UI dashboard for monitoring application status visually.

builder.Services.AddHealthChecksUI()
    .AddInMemoryStorage();

app.MapHealthChecksUI(options =>
{
    options.UIPath = "/health-ui";
    options.ApiPath = "/health-ui-api";
});

Securing Health Check Endpoints

Health endpoints should be secured in production environments.

app.MapHealthChecks("/health")
   .RequireAuthorization();

This prevents unauthorized access to infrastructure details.

Best Practices for ASP.NET Core Health Checks

Keep health checks fast and lightweight
Separate liveness and readiness checks
Avoid heavy database queries
Use tags for environment‑specific checks
Do not expose sensitive information publicly

Conclusion

Health checks in ASP.NET Core Web API are a fundamental requirement for modern application architecture. They provide real-time visibility into application health, enable automated recovery, and integrate seamlessly with DevOps and cloud platforms.

By implementing health checks correctly, your ASP.NET Core APIs become resilient, observable, and production‑ready.