ASP.NET Core健康检查端点仅返回状态字符串，无法获取完整JSON响应

问题 #

在ASP.NET Core应用里实现了IHealthCheck接口，用来在应用完成预热前返回503状态码。但用Postman调用健康检查端点时，只能看到状态字符串（比如Healthy），拿不到Microsoft.Extensions.Diagnostics.HealthChecks.HealthCheckResult对应的完整JSON响应。

期望得到的JSON响应示例：

{
   "Status": "Healthy",
   "Description": "The Initialization task has completed."
}

实际仅返回类似Healthy的纯文本。

使用的StartupHealthCheck类代码如下：

public class StartupHealthCheck : IHealthCheck
{
    private volatile bool _isReady;
    private readonly IGlobalState _globalState;
    public StartupHealthCheck(IGlobalState globalState)
        => _globalState = globalState;

    public bool StartupCompleted
    {
        get => _isReady;
        set => _isReady = value;
    }

    public async Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        if (StartupCompleted && _globalState.PercentageInitialized == 100)
        {
            return HealthCheckResult.Healthy("The Initialization task has completed.");
        }

        return new HealthCheckResult(HealthStatus.Unhealthy, $"The Initialization task is still running at - {_globalState.PercentageInitialized}%.");
    }
}

解决方案 #

ASP.NET Core健康检查端点默认返回纯文本格式，要获取完整JSON结构，得在配置健康检查时指定JSON响应编写器。

1. 注册健康检查服务 #

在Program.cs（或旧版的Startup.cs）里注册健康检查时，添加自定义配置：

builder.Services.AddHealthChecks()
    .AddCheck<StartupHealthCheck>("startup_check");

2. 配置端点的JSON响应 #

在端点路由配置中，给健康检查端点设置自定义的响应写入逻辑：

app.MapHealthChecks("/health", new HealthCheckOptions
{
    ResponseWriter = async (context, report) =>
    {
        context.Response.ContentType = "application/json";
        var response = new
        {
            Status = report.Status.ToString(),
            Description = report.Entries["startup_check"].Description
        };
        await context.Response.WriteAsync(System.Text.Json.JsonSerializer.Serialize(response));
    }
});

3. 额外说明 #

• 你可以根据需求在自定义响应里添加更多字段，比如检查项名称、耗时、详细错误信息等。
• 确保代码里引用了System.Text.Json命名空间，不然JSON序列化会报错。
• 如果用的是.NET 6及以上的顶级语句模式，直接把代码加到Program.cs对应的配置阶段就行。

内容的提问来源于stack exchange，提问作者qwerty123