ASP.NET Core 中的健康狀態檢查

作者：Glenn Condron 和 Juergen Gutsch

ASP.NET Core 提供健康情況檢查中介軟體和程式庫，用來報告應用程式基礎結構元件的健康情況。

應用程式會將健康狀態檢查公開為 HTTP 端點。 您可以針對各種即時監控案例來設定健康情況檢查端點：

• 容器協調器和負載平衡器可以使用健康狀態探查，來檢查應用程式的狀態。 例如，容器協調器可能會暫停輪流部署或重新啟動容器，來回應失敗的健康狀態檢查。 負載平衡器可能會將流量從失敗的執行個體路由傳送至狀況良好的執行個體，來回應狀況不良的應用程式。
• 您可以監控所使用記憶體、磁碟及其他實體伺服器資源的健康狀態。
• 健康狀態檢查可以測試應用程式的相依性 (例如資料庫和外部服務端點)，確認其是否可用且正常運作。

健康情況檢查通常會與外部監控服務或容器協調器搭配使用，來檢查應用程式的狀態。 將健康狀態檢查新增至應用程式之前，請決定要使用的監控系統。 監控系統會指定要建立哪些健康狀態檢查類型，以及如何設定其端點。

基本健康狀態探查

對於許多應用程式，報告應用程式是否可處理要求的基本健康狀態探查組態 (「活躍度」)，便足以探索應用程式的狀態。

基本設定會登錄健康情況檢查服務，並呼叫健康情況檢查中介軟體以在具有健康情況回應的 URL 端點做出回應。 預設並未登錄特定健康狀態檢查來測試任何特定相依性或子系統。 如果應用程式可以在健康情況端點 URL 做出回應，則視為狀況良好。 預設回應寫入器會將 HealthStatus 以純文字回應形式寫入至用戶端。 HealthStatus 是 HealthStatus.Healthy、HealthStatus.Degraded 或 HealthStatus.Unhealthy。

在 Program.cs 中，使用 AddHealthChecks 登錄健康狀態檢查服務。 呼叫 MapHealthChecks 來建立健康情況檢查端點。

下列範例會在 /healthz 建立健康情況檢查端點：

C#

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Docker HEALTHCHECK

Docker 提供內建 HEALTHCHECK 指示詞，可用來檢查使用基本健康狀態檢查組態的應用程式狀態：

Dockerfile

HEALTHCHECK CMD curl --fail http://localhost:5000/healthz || exit

上述範例會使用 curl，以在 /healthz 針對健康情況檢查端點提出 HTTP 要求。 curl 未包括在 .NET Linux 容器映像中，但可以在 Dockerfile 中安裝必要套件來進行新增。 根據 Alpine Linux 來使用映像的容器可以使用所包括的 wget 來取代 curl。

建立健康狀態檢查

健康狀態檢查是藉由實作 IHealthCheck 介面來建立。 CheckHealthAsync 方法會傳回指出狀態為 Healthy、Degraded 或 Unhealthy 的 HealthCheckResult。 結果會寫成具有可設定狀態碼的純文字回應。 健康情況檢查選項小節中會描述設定。 HealthCheckResult 也可以傳回選擇性索引鍵/值組。

下列範例示範健康情況檢查的配置：

C#

public class SampleHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        var isHealthy = true;

        // ...

        if (isHealthy)
        {
            return Task.FromResult(
                HealthCheckResult.Healthy("A healthy result."));
        }

        return Task.FromResult(
            new HealthCheckResult(
                context.Registration.FailureStatus, "An unhealthy result."));
    }
}

健康情況檢查的邏輯放在 CheckHealthAsync 方法中。 上述範例會將虛擬變數 isHealthy 設定為 true。 如果 isHealthy 的值設定為 false，則會傳回 HealthCheckRegistration.FailureStatus 狀態。

如果 CheckHealthAsync 在檢查期間擲回例外狀況，則會傳回其 HealthReportEntry.Status 設定為 FailureStatus 的新 HealthReportEntry。 此狀態是由 AddCheck 所定義 (請參閱登錄健康情況檢查服務一節)，並包括造成檢查失敗的內部例外狀況。 Description 會設定為例外狀況的訊息。

登錄健康狀態檢查服務

若要登錄健康情況檢查服務，請在 Program.cs 中呼叫 AddCheck：

C#

builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheck>("Sample");

下列範例中所顯示的 AddCheck 多載會設定在健康狀態檢查報告失敗時所要報告的失敗狀態 (HealthStatus)。 如果將失敗狀態設定為 null (預設)，則會報告 HealthStatus.Unhealthy。 此多載對程式庫作者很有用。若健康狀態檢查實作採用此設定，則當健康狀態檢查失敗時，應用程式就會強制程式庫指出失敗狀態。

「標記」可以用來篩選健康情況檢查。 標記會在篩選健康情況檢查小節中予以描述。

C#

builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheck>(
        "Sample",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "sample" });

AddCheck 也可以執行匿名函式。 在下列範例中，健康情況檢查一律會傳回狀況良好結果：

C#

builder.Services.AddHealthChecks()
    .AddCheck("Sample", () => HealthCheckResult.Healthy("A healthy result."));

呼叫 AddTypeActivatedCheck，以將引數傳遞至健康情況檢查實作。 在下列範例中，啟用類型的健康情況檢查會在其建構函式中接受整數和字串：

C#

public class SampleHealthCheckWithArgs : IHealthCheck
{
    private readonly int _arg1;
    private readonly string _arg2;

    public SampleHealthCheckWithArgs(int arg1, string arg2)
        => (_arg1, _arg2) = (arg1, arg2);

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        // ...

        return Task.FromResult(HealthCheckResult.Healthy("A healthy result."));
    }
}

若要登錄上述健康情況檢查，請使用傳遞為引數的整數和字串來呼叫 AddTypeActivatedCheck：

C#

builder.Services.AddHealthChecks()
    .AddTypeActivatedCheck<SampleHealthCheckWithArgs>(
        "Sample",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "sample" },
        args: new object[] { 1, "Arg" });

使用健康情況檢查路由傳送

在 Program.cs 中，使用端點 URL 或相對路徑以在端點建立器上呼叫 MapHealthChecks：

C#

app.MapHealthChecks("/healthz");

需要主機

呼叫 RequireHost，以將一或多個允許的主機指定給健康情況檢查端點。 主機應該是 Unicode，而不是 punycode，而且可能會包括連接埠。 如果未提供集合，則會接受任何主機：

C#

app.MapHealthChecks("/healthz")
    .RequireHost("www.contoso.com:5001");

若要限制健康情況檢查端點只在特定連接埠上回應，請在 RequireHost 呼叫中指定連接埠。 此方式通常用於容器環境，以公開監控服務的連接埠：

C#

app.MapHealthChecks("/healthz")
    .RequireHost("*:5001");

警告

依賴於主機標頭的 API (例如 HttpRequest.Host 和 RequireHost) 可能會受到用戶端的詐騙。

若要防止主機和連接埠詐騙，請使用下列其中一種方式：

• 使用可在其中檢查連接埠的 HttpContext.Connection (ConnectionInfo.LocalPort)。
• 採用主機篩選。

若要防止未經授權的用戶端詐騙連接埠，請呼叫 RequireAuthorization：

C#

app.MapHealthChecks("/healthz")
    .RequireHost("*:5001")
    .RequireAuthorization();

如需詳細資訊，請參閱具有 RequireHost 之路由中的主機比對。

需要授權

呼叫 RequireAuthorization，以在健康情況檢查要求端點上執行授權中介軟體。 RequireAuthorization 多載接受一或多個授權原則。 如果未提供原則，則會使用預設授權原則：

C#

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

啟用跨原始來源要求 (CORS)

雖然從瀏覽器手動執行健康情況檢查不是常見案例，但是您可以在健康情況檢查端點上呼叫 RequireCors，以啟用 CORS 中介軟體。 RequireCors 多載接受 CORS 原則建立器委派 (CorsPolicyBuilder) 或原則名稱。 如需詳細資訊，請參閱在 ASP.NET Core 中啟用跨原始來源要求 (CORS)。

健康狀態檢查選項

HealthCheckOptions 讓您有機會自訂健康狀態檢查行為：

• 篩選健康狀態檢查
• 自訂 HTTP 狀態碼
• 隱藏快取標頭
• 自訂輸出

篩選健康狀態檢查

根據預設，健康情況檢查中介軟體會執行所有已登錄的健康情況檢查。 若要執行健康狀態檢查子集，請對 Predicate 選項提供傳回布林值的函式。

下列範例會篩選健康情況檢查，以只執行已標記 sample 的檢查：

C#

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    Predicate = healthCheck => healthCheck.Tags.Contains("sample")
});

自訂 HTTP 狀態碼

您可以使用 ResultStatusCodes 來自訂健康狀態與 HTTP 狀態碼的對應。 下列 StatusCodes 指派是中介軟體所使用的預設值。 變更狀態碼值，以符合您的需求：

C#

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    ResultStatusCodes =
    {
        [HealthStatus.Healthy] = StatusCodes.Status200OK,
        [HealthStatus.Degraded] = StatusCodes.Status200OK,
        [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable
    }
});

隱藏快取標頭

AllowCachingResponses 會控制健康情況檢查中介軟體是否將 HTTP 標頭新增至探查回應，以防止回應快取。 如果值為 false (預設)，則中介軟體會設定或覆寫 Cache-Control、Expires 和 Pragma 標頭，以防止回應快取。 如果值為 true，則中介軟體不會修改回應的快取標頭：

C#

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    AllowCachingResponses = true
});

自訂輸出

若要自訂健康情況檢查報告的輸出，請將 HealthCheckOptions.ResponseWriter 屬性設定為可寫入回應的委派：

C#

app.MapHealthChecks("/healthz", new HealthCheckOptions
{
    ResponseWriter = WriteResponse
});

預設委派會使用字串值 HealthReport.Status 寫入基本純文字回應。 下列自訂委派會使用 System.Text.Json來輸出自訂 JSON 回應：

C#

private static Task WriteResponse(HttpContext context, HealthReport healthReport)
{
    context.Response.ContentType = "application/json; charset=utf-8";

    var options = new JsonWriterOptions { Indented = true };

    using var memoryStream = new MemoryStream();
    using (var jsonWriter = new Utf8JsonWriter(memoryStream, options))
    {
        jsonWriter.WriteStartObject();
        jsonWriter.WriteString("status", healthReport.Status.ToString());
        jsonWriter.WriteStartObject("results");

        foreach (var healthReportEntry in healthReport.Entries)
        {
            jsonWriter.WriteStartObject(healthReportEntry.Key);
            jsonWriter.WriteString("status",
                healthReportEntry.Value.Status.ToString());
            jsonWriter.WriteString("description",
                healthReportEntry.Value.Description);
            jsonWriter.WriteStartObject("data");

            foreach (var item in healthReportEntry.Value.Data)
            {
                jsonWriter.WritePropertyName(item.Key);

                JsonSerializer.Serialize(jsonWriter, item.Value,
                    item.Value?.GetType() ?? typeof(object));
            }

            jsonWriter.WriteEndObject();
            jsonWriter.WriteEndObject();
        }

        jsonWriter.WriteEndObject();
        jsonWriter.WriteEndObject();
    }

    return context.Response.WriteAsync(
        Encoding.UTF8.GetString(memoryStream.ToArray()));
}

健康情況檢查 API 未提供複雜 JSON 傳回格式的內建支援，因為此格式是您所選擇的監控系統所特有。 視需要，自訂上述範例中的回應。 如需使用 System.Text.Json進行 JSON 序列化的詳細資訊，請參閱 如何在 .NET 中序列化和還原序列化 JSON。

資料庫探查

健康狀態檢查可指定資料庫查詢以布林測試方式來執行，藉此指出資料庫是否正常回應。

AspNetCore.Diagnostics.HealthChecks，一種適用於 ASP.NET Core 應用程式的健康情況檢查程式庫，包括針對 SQL Server 資料庫所執行的健康情況檢查。 AspNetCore.Diagnostics.HealthChecks 會對資料庫執行 SELECT 1 查詢，以確認資料庫連線狀況良好。

警告

使用查詢檢查資料庫連線時，請選擇快速傳回的查詢。 查詢方法具有多載資料庫而降低其效能的風險。 在大部分情況下，不需要執行測試查詢。 只要成功建立資料庫連線就已足夠。 如果您發現有必要執行查詢，請選擇簡單的 SELECT 查詢，例如 SELECT 1。

若要使用此 SQL Server 健康情況檢查，請包括 AspNetCore.HealthChecks.SqlServer NuGet 套件的套件參考。 下列範例會登錄 SQL Server 健康情況檢查：

C#

var conStr = builder.Configuration.GetConnectionString("DefaultConnection");
if (string.IsNullOrEmpty(conStr))
{
    throw new InvalidOperationException(
                       "Could not find a connection string named 'DefaultConnection'.");
}
builder.Services.AddHealthChecks()
    .AddSqlServer(conStr);

備註

Microsoft 不會維護或支援 AspNetCore.Diagnostics.HealthChecks。

Entity Framework Core DbContext 探查

DbContext 檢查會確認應用程式是否可以與針對 EF CoreDbContext 所設定的資料庫通訊。 應用程式支援 DbContext 檢查：

• 使用 Entity Framework (EF) Core。
• 包括 Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore NuGet 套件的套件參考。

AddDbContextCheck 會登錄 DbContext 的健康狀態檢查。 DbContext 會以 TContext 形式提供給方法。 多載可用來設定失敗狀態、標籤和自訂測試查詢。

預設情況：

• DbContextHealthCheck 會呼叫 EF Core 的 CanConnectAsync 方法。 您可以自訂使用 AddDbContextCheck 方法多載檢查健康狀態時所要執行的作業。
• 健康狀態檢查的名稱是 TContext 類型的名稱。

下列範例會登錄 DbContext 和相關聯的 DbContextHealthCheck：

C#

builder.Services.AddDbContext<SampleDbContext>(options =>
    options.UseSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection")));

builder.Services.AddHealthChecks()
    .AddDbContextCheck<SampleDbContext>();

個別的整備度與活躍度探查

在某些裝載案例中，會使用一組健康情況檢查來區分兩個應用程式狀態：

• 「整備」指出應用程式是否正在正常執行，但尚未準備好接收要求。
• 「活躍度」指出應用程式是否已當機，而且必須重新予以啟動。

請考慮下列範例：應用程式在準備好處理要求之前必須下載大型設定檔。 如果初始下載失敗，則我們不想要重新啟動應用程式，因為應用程式可以重試下載檔案數次。 我們使用「活躍度探查」來描述處理序的活躍度，而不會執行其他檢查。 我們也想要防止在設定檔下載成功之前將要求傳送至應用程式。 除非下載成功，而且應用程式準備好接收要求，否則我們會使用「整備度探查」來指出「尚未就緒」狀態。

下列背景工作會模擬大約需要 15 秒的啟動處理序。 完成後，工作會將 StartupHealthCheck.StartupCompleted 屬性設定為 True：

C#

public class StartupBackgroundService : BackgroundService
{
    private readonly StartupHealthCheck _healthCheck;

    public StartupBackgroundService(StartupHealthCheck healthCheck)
        => _healthCheck = healthCheck;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Simulate the effect of a long-running task.
        await Task.Delay(TimeSpan.FromSeconds(15), stoppingToken);

        _healthCheck.StartupCompleted = true;
    }
}

StartupHealthCheck 會報告長時間執行的啟動工作完成，並公開背景服務所設定的 StartupCompleted 屬性：

C#

public class StartupHealthCheck : IHealthCheck
{
    private volatile bool _isReady;

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

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        if (StartupCompleted)
        {
            return Task.FromResult(HealthCheckResult.Healthy("The startup task has completed."));
        }

        return Task.FromResult(HealthCheckResult.Unhealthy("That startup task is still running."));
    }
}

健康狀態檢查是 Program.cs 中使用 AddCheck 隨託管服務一起登錄。 因為所裝載服務必須在健康情況檢查上設定此屬性，所以也會在服務容器中將健康情況檢查登錄為單一資料庫：

C#

builder.Services.AddHostedService<StartupBackgroundService>();
builder.Services.AddSingleton<StartupHealthCheck>();

builder.Services.AddHealthChecks()
    .AddCheck<StartupHealthCheck>(
        "Startup",
        tags: new[] { "ready" });

若要建立兩個不同的健康情況檢查端點，請呼叫 MapHealthChecks 兩次：

C#

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

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

上述範例會建立下列健康情況檢查端點：

• /healthz/ready 用於整備檢查。 整備檢查會將健康情況檢查篩選為已標記 ready 的檢查。
• /healthz/live 用於活躍度檢查。 活躍度檢查會在 HealthCheckOptions.Predicate 委派中傳回 false，以篩選出所有健康情況檢查。 如需篩選健康情況檢查的詳細資訊，請參閱本文中的篩選健康情況檢查。

啟動工作完成之前，/healthz/ready 端點會回報 Unhealthy 狀態。 啟動工作完成之後，此端點會回報 Healthy 狀態。 /healthz/live 端點會排除所有檢查，並將所有呼叫的狀態都回報為 Healthy。

Kubernetes 範例

使用個別的整備度與活躍度檢查在 Kubernetes 之類的環境中很有用。 在 Kubernetes 中，應用程式可能需要先執行耗時的啟動工作，才能接受要求 (例如基礎資料庫可用性測試)。 使用個別的檢查可讓協調器區分應用程式是否為正常運作但尚未準備好，或應用程式是否無法啟動。 如需 Kubernetes 中整備度與活躍度探查的詳細資訊，請參閱 Kubernetes 文件中的 Configure Liveness and Readiness Probes (設定活躍度與整備度探查)。

下列範例示範 Kubernetes 整備度探查組態：

YAML

spec:
  template:
  spec:
    readinessProbe:
      # an http probe
      httpGet:
        path: /healthz/ready
        port: 80
      # length of time to wait for a pod to initialize
      # after pod startup, before applying health checking
      initialDelaySeconds: 30
      timeoutSeconds: 1
    ports:
      - containerPort: 80

發佈健康狀態檢查程式庫

若要發佈健康狀態檢查作為程式庫：

1. 寫入健康狀態檢查，將 IHealthCheck 介面當做獨立類別來實作。 此類別可能依賴相依性插入 (DI)、類型啟用和具名選項來存取組態資料。

2. 使用取用應用程式在其 Program.cs 方法中呼叫的參數，來寫入延伸模組。 請考慮下列範例健康情況檢查，而此檢查接受 arg1 和 arg2 作為建構函式參數：

   C#

   public SampleHealthCheckWithArgs(int arg1, string arg2)
       => (_arg1, _arg2) = (arg1, arg2);
   

   上述簽章指出健康情況檢查需要自訂資料，才能處理健康情況檢查探查邏輯。 此資料會提供給委派，以在使用延伸模組登錄健康狀態檢查時，用來建立健康狀態檢查執行個體。 在下列範例中，呼叫端會指定：

   • arg1：健康情況檢查的整數資料點。
   • arg2：健康情況檢查的字串引數。
   • name：選用的健康情況檢查名稱。 如果 null，則會使用預設值。
   • failureStatus：選用的 HealthStatus，其回報失敗狀態。 如果為 null，則會使用 HealthStatus.Unhealthy。
   • tags：標記的選用 IEnumerable<string> 集合。
   C#

   public static class SampleHealthCheckBuilderExtensions
   {
       private const string DefaultName = "Sample";
   
       public static IHealthChecksBuilder AddSampleHealthCheck(
           this IHealthChecksBuilder healthChecksBuilder,
           int arg1,
           string arg2,
           string? name = null,
           HealthStatus? failureStatus = null,
           IEnumerable<string>? tags = default)
       {
           return healthChecksBuilder.Add(
               new HealthCheckRegistration(
                   name ?? DefaultName,
                   _ => new SampleHealthCheckWithArgs(arg1, arg2),
                   failureStatus,
                   tags));
       }
   }
   

健康狀態檢查發行者

當 IHealthCheckPublisher 新增至服務容器時，健康狀態檢查系統會定期執行健康狀態檢查，並呼叫 PublishAsync 傳回結果。 此處理序適用於推送型健康情況監控系統案例，而此案例預期每個處理序都會定期呼叫監控系統來判斷健康情況。

HealthCheckPublisherOptions 可讓您設定：

• Delay：初始延遲會在應用程式啟動之後且執行 IHealthCheckPublisher 執行個體之前套用。 啟動後就會套用延遲，但不會套用至後面的反覆項目。 預設值是五秒鐘。
• Period：IHealthCheckPublisher 執行的期間。 預設值為 30 秒。
• Predicate：如果 Predicate 為 null (預設)，則健康情況檢查發行者服務會執行所有已登錄的健康情況檢查。 若要執行一部分的健康狀態檢查，請提供可篩選該組檢查的函式。 每個期間都會評估該述詞。
• Timeout：執行所有 IHealthCheckPublisher 執行個體之健康情況檢查的逾時。 若要在沒有逾時的情況下執行，請使用 InfiniteTimeSpan。 預設值為 30 秒。

下列範例示範健康情況發行者的配置：

C#

public class SampleHealthCheckPublisher : IHealthCheckPublisher
{
    public Task PublishAsync(HealthReport report, CancellationToken cancellationToken)
    {
        if (report.Status == HealthStatus.Healthy)
        {
            // ...
        }
        else
        {
            // ...
        }

        return Task.CompletedTask;
    }
}

HealthCheckPublisherOptions 類別提供屬性來設定健康情況檢查發行者的行為。

下列範例會將健康情況檢查發行者登錄為單一資料庫，並設定 HealthCheckPublisherOptions：

C#

builder.Services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = healthCheck => healthCheck.Tags.Contains("sample");
});

builder.Services.AddSingleton<IHealthCheckPublisher, SampleHealthCheckPublisher>();

AspNetCore.Diagnostics.HealthChecks：

• 包括數個系統的發行者，包括 Application Insights。
• 不受 Microsoft 維護或支援。

個別的 HealthChecks

Delay 和 Period 可以在每個 HealthCheckRegistration 上個別設定。 當您想要以與 HealthCheckPublisherOptions 中所設定的期間不同的速率執行一些健康情況檢查時，這非常有用。

下列程式碼會設定 SampleHealthCheck1 的 Delay 和 Period：

C#

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks()
   .Add(new HealthCheckRegistration(
       name: "SampleHealthCheck1",
       instance: new SampleHealthCheck(),
       failureStatus: null,
       tags: null,
       timeout: default)
   {
       Delay = TimeSpan.FromSeconds(40),
       Period = TimeSpan.FromSeconds(30)
   });

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

相依性插入和健康情況檢查

您可以使用相依性插入來取用健康情況檢查類別內特定 Type 的執行個體。 相依性插入適用於將選項或全域設定插入至健康情況檢查。 使用相依性插入「不」是設定健康情況檢查的常見案例。 通常，每個健康情況檢查都是專屬於實際測試，並且使用 IHealthChecksBuilder 擴充方法進行設定。

下列範例顯示可透過相依性插入來擷取設定物件的範例健康情況檢查：

C#

public class SampleHealthCheckWithDI : IHealthCheck
{
    private readonly SampleHealthCheckWithDiConfig _config;

    public SampleHealthCheckWithDI(SampleHealthCheckWithDiConfig config)
        => _config = config;

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        var isHealthy = true;

        // use _config ...

        if (isHealthy)
        {
            return Task.FromResult(
                HealthCheckResult.Healthy("A healthy result."));
        }

        return Task.FromResult(
            new HealthCheckResult(
                context.Registration.FailureStatus, "An unhealthy result."));
    }
}

SampleHealthCheckWithDiConfig 和健康情況檢查需要新增至服務容器：

C#

builder.Services.AddSingleton<SampleHealthCheckWithDiConfig>(new SampleHealthCheckWithDiConfig
{
    BaseUriToCheck = new Uri("https://sample.contoso.com/api/")
});
builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheckWithDI>(
        "With Dependency Injection",
        tags: new[] { "inject" });

UseHealthChecks 與MapHealthChecks

有兩種方式可讓呼叫端存取健康情況檢查：

• UseHealthChecks 會登錄中介軟體來處理中介軟體管線中的健康情況檢查要求。
• MapHealthChecks 會登錄健康情況檢查端點。 端點會與應用程式中的其他端點進行比對和執行。

使用 MapHealthChecks 優於 UseHealthChecks 的優點是能夠使用端點感知中介軟體 (例如授權)，並更精細地控制比對原則。 使用 UseHealthChecks 優於 MapHealthChecks 的主要優點是確切控制中介軟體管線中執行健康情況檢查的位置。

UseHealthChecks：

• 在要求符合健康情況檢查端點時終止管線。 最短線路可避免不必要的工作，因此經常使用 (例如記錄和其他中介軟體)。
• 主要用於在管線中設定健康情況檢查中介軟體。
• 可以比對連接埠上的任何路徑與 null 或空白 PathString。 允許在針對所指定連接埠所提出的任何要求上執行健康情況檢查。
• 原始程式碼

MapHealthChecks 允許：

• 呼叫 ShortCircuit，以在要求符合健康情況檢查端點時終止管線。 例如： app.MapHealthChecks("/healthz").ShortCircuit(); 。 如需詳細資訊，請參閱路由之後尋找中介軟體的最短路徑。
• 對應特定路由或端點以進行健康情況檢查。
• 自訂可存取健康情況檢查端點的 URL 或路徑。
• 使用不同的路由或設定來對應多個健康情況檢查端點。 多個端點支援：
  • 針對不同類型的健康情況檢查或元件啟用不同的端點。
  • 用來區分應用程式健康情況的不同層面，或將特定設定套用至健康情況檢查的子集。
• 原始程式碼

其他資源

• 檢視或下載範例程式碼 \(英文\) (如何下載)

備註

本文部分是透過人工智慧協助建立的。 發佈之前，請視需要進行作者檢閱並修訂內容。 請參閱我們在 Microsoft Learn 中使用 AI 產生的內容的原則。