When building modern APIs, health checks are a common way to expose the status of your application. By default, ASP.NET Core health checks return a very minimal response (often just HTTP status codes). But what if you want to return a clean JSON payload that can easily be consumed by monitoring systems?
Step 1: Create a Custom JSON Response Writer
ASP.NET Core’s HealthCheckOptions allows us to plug in a custom ResponseWriter. Here’s one that outputs a JSON response containing the health status:
private async Task JsonResponseWriter(HttpContext context, HealthReport report)
{
context.Response.ContentType = "application/json";
await JsonSerializer.SerializeAsync(
context.Response.Body,
new { Status = report.Status.ToString() },
new JsonSerializerOptions
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase
}
);
}
What this does:
-
Sets the response type to
application/json. -
Serializes an anonymous object containing the health check
Status. -
Uses camelCase naming to keep JSON consistent with API conventions.
Step 2: Hook the Writer into Health Checks
Now, wire up the health check middleware in your pipeline:
app.UseHealthChecks("/health", new HealthCheckOptions
{
ResponseWriter = JsonResponseWriter
});
Explanation:
-
Requests to
/healthwill trigger your health checks. -
Instead of the default plain-text response, your
JsonResponseWriterwill return JSON like:
{
"status": "Healthy"
}
Step 3: Configure Global JSON Options
To keep your entire API’s JSON responses consistent, configure the JsonSerializerOptions in Startup.cs (or Program.cs for minimal hosting):
services.AddControllers()
.AddJsonOptions(options =>
{
options.JsonSerializerOptions.IgnoreNullValues = true;
options.JsonSerializerOptions.WriteIndented = true;
});
-
IgnoreNullValues = true→ Null properties won’t clutter your responses. -
WriteIndented = true→ JSON output is more readable (great for debugging).
With this setup:
-
Hitting
/healthgives a clean JSON response. -
All controllers return JSON using consistent formatting.
-
Monitoring tools can easily parse your app’s health status.
Example response:
{
"status": "Healthy"
}
Conclusion
By adding a custom ResponseWriter and configuring global JSON options, you can make your ASP.NET Core health checks more API-friendly. This approach is simple, clean, and integrates seamlessly into modern monitoring setups like Kubernetes, Prometheus, or cloud load balancers.