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:
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"));
}
}
Register the custom health check:
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")
});
Register tagged checks:
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.