Kontrole kondycji w programie ASP.NET Core

Przez Glenn Condron i Juergen Gutsch

ASP.NET Core oferuje middleware sprawdzania kondycji oraz biblioteki do raportowania kondycji składników infrastruktury aplikacji.

Testy kondycji są udostępniane przez aplikację jako punkty końcowe HTTP. Punkty końcowe kontroli kondycji można skonfigurować dla różnych scenariuszy monitorowania w czasie rzeczywistym:

• Sondy kondycji mogą być używane przez koordynatorów kontenerów i moduły równoważenia obciążenia w celu sprawdzenia stanu aplikacji. Na przykład orkiestrator kontenerów może reagować na niepowodzenie sprawdzania kondycji, zatrzymując wdrożenie stopniowe lub ponownie uruchamiając kontener. Moduł równoważenia obciążenia może reagować na problemy z aplikacją przez przekierowanie ruchu z wadliwego wystąpienia do wystąpienia działającego poprawnie.
• Użycie pamięci, dysku i innych zasobów serwera fizycznego można monitorować pod kątem stanu dobrej kondycji.
• Testy kondycji mogą testować zależności aplikacji, takie jak bazy danych i zewnętrzne punkty końcowe usługi, w celu potwierdzenia dostępności i normalnego działania.

Testy kondycji są zwykle używane z zewnętrzną usługą monitorowania lub koordynatorem kontenerów w celu sprawdzenia stanu aplikacji. Przed dodaniem kontroli kondycji do aplikacji zdecyduj, który system monitorowania ma być używany. System monitorowania określa, jakie typy testów zdrowia należy utworzyć i jak skonfigurować ich punkty końcowe.

Podstawowa sonda kondycji

W przypadku wielu aplikacji podstawowa konfiguracja sondy kondycji, która zgłasza dostępność aplikacji do przetwarzania żądań (statusu działania) jest wystarczająca do ustalenia stanu aplikacji.

Podstawowa konfiguracja rejestruje usługi monitorowania stanu i wywołuje middleware do kontroli stanu zdrowia, aby odpowiedzieć na adresie URL odpowiedzią zdrowotną. Domyślnie żadne konkretne kontrole kondycji nie są rejestrowane w celu przetestowania żadnej konkretnej zależności lub podsystemu. Aplikacja jest uważana za w dobrej kondycji, jeśli może odpowiadać pod adresem URL punktu końcowego zdrowia. Domyślny zapisujący odpowiedzi zapisuje HealthStatus jako odpowiedź w postaci zwykłego tekstu do klienta. Parametr HealthStatus jest HealthStatus.Healthy, HealthStatus.Degraded lub HealthStatus.Unhealthy.

Zarejestruj usługi sprawdzania kondycji w AddHealthChecks w Program.cs. Utwórz punkt końcowy kontroli kondycji, wywołując polecenie MapHealthChecks.

Poniższy przykład tworzy punkt końcowy kontroli kondycji: /healthz.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Doker HEALTHCHECK

Platforma Docker zawiera wbudowaną HEALTHCHECK dyrektywę, której można użyć do sprawdzenia stanu aplikacji korzystającej z podstawowej konfiguracji kontroli kondycji:

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

W poprzednim przykładzie użyto curl do wysłania żądania HTTP do punktu końcowego sprawdzania kondycji na /healthz. curl nie jest uwzględniana w obrazach kontenerów systemu Linux platformy .NET, ale można ją dodać, instalując wymagany pakiet w pliku Dockerfile. Kontenery korzystające z obrazów opartych na systemie Alpine Linux mogą używać dołączonego wget zamiast curl.

Tworzenie kontroli kondycji

Tworzenie kontroli kondycji przez zaimplementowanie interfejsu IHealthCheck . Metoda CheckHealthAsync zwraca wartość HealthCheckResult , która wskazuje kondycję jako Healthy, Degradedlub Unhealthy. Wynik jest zapisywany jako odpowiedź w postaci zwykłego tekstu z konfigurowalnym kodem stanu. Zobacz sekcję Opcje sprawdzania kondycji . HealthCheckResult może również zwracać opcjonalne pary klucz-wartość.

W poniższym przykładzie pokazano układ kontroli kondycji:

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."));
    }
}

Logika kontroli kondycji jest umieszczana w metodzie CheckHealthAsync . W poprzednim przykładzie ustawiono tymczasową zmienną isHealthy, na wartość true. Jeśli wartość parametru isHealthy jest ustawiona na false, zwracany jest stan HealthCheckRegistration.FailureStatus.

Jeśli CheckHealthAsync podczas sprawdzania wystąpi wyjątek, zostanie zwrócony nowy HealthReportEntry z ustawioną HealthReportEntry.Status na FailureStatus. Ten stan jest definiowany przez AddCheck (zobacz sekcję Rejestrowanie usług sprawdzania kondycji) i zawiera wewnętrzny wyjątek, który spowodował niepowodzenie sprawdzania. Parametr Description jest ustawiony na komunikat wyjątku.

Rejestrowanie usług kontroli kondycji

Aby zarejestrować usługę sprawdzania kondycji, wywołaj AddCheck w Program.cs:

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

Przeciążenie AddCheck pokazane w poniższym przykładzie ustawia stan błędu (HealthStatus) w celu raportowania, gdy kontrola kondycji zgłasza błąd. Jeśli stan niepowodzenia jest ustawiony na null (wartość domyślna), HealthStatus.Unhealthy jest zgłaszany. To przeciążenie jest przydatnym scenariuszem dla autorów bibliotek, gdzie status awarii wskazywany przez bibliotekę jest wymuszany przez aplikację, gdy wystąpi błąd w sprawdzaniu kondycji, o ile implementacja sprawdzania kondycji respektuje to ustawienie.

Tagi mogą służyć do filtrowania kontroli kondycji. Tagi są opisane w sekcji Filtrowanie kontroli kondycji systemu.

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

AddCheck może również wykonać funkcję lambda. W poniższym przykładzie sprawdzanie kondycji zawsze zwraca zdrowy wynik.

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

Wywołaj metodę AddTypeActivatedCheck , aby przekazać argumenty do implementacji kontroli kondycji. W poniższym przykładzie kontrola kondycji aktywowana typem akceptuje liczbę całkowitą i ciąg w konstruktorze:

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."));
    }
}

Aby zarejestrować poprzednią kontrolę kondycji, wywołaj metodę AddTypeActivatedCheck za pomocą liczby całkowitej i ciągu przekazanego jako argumenty:

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

Zastosuj trasowanie kontroli zdrowia

W Program.cs wywołaj MapHealthChecks na budowniczym punktu końcowego z adresem URL punktu końcowego lub ścieżką względną:

app.MapHealthChecks("/healthz");

Wymagaj hosta

Wywołaj RequireHost , aby określić co najmniej jednego dozwolonego hosta dla endpointu kontroli kondycji. Użyj formatu Unicode, a nie punycode dla hostów i możesz dołączyć port. Jeśli nie podasz kolekcji, zostanie zaakceptowany każdy host.

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

Aby ograniczyć punkt końcowy kontroli kondycji do odpowiadania tylko na określonym porcie, określ port w wywołaniu metody RequireHost. Zazwyczaj użyj tego podejścia w środowisku kontenera, aby uwidocznić port na potrzeby usług monitorowania:

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

Warning

Interfejs API opierający się na nagłówku Host, tak jak HttpRequest.Host oraz RequireHost, podlega potencjalnemu fałszowaniu przez klientów.

Aby zapobiec fałszowaniu hostów i portów, użyj jednej z następujących metod:

• Użyj HttpContext.Connection (ConnectionInfo.LocalPort), gdzie sprawdzane są porty.
• Zastosowanie filtrowania hostów.

Aby zapobiec fałszowaniu portu przez nieautoryzowanych klientów, wywołaj metodę RequireAuthorization:

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

Aby uzyskać więcej informacji, zobacz Dopasowywanie hostów w trasach za pomocą elementu RequireHost.

Wymagaj autoryzacji

Wywołaj polecenie RequireAuthorization , aby uruchomić oprogramowanie pośredniczące autoryzacji w punkcie końcowym żądania sprawdzania kondycji. Przeciążenie RequireAuthorization akceptuje co najmniej jedną zasady autoryzacji. Jeśli nie podano zasad, są używane domyślne zasady autoryzacji:

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

Włącz żądania Cross-Origin (CORS)

Mimo że ręczne uruchamianie kontroli kondycji z przeglądarki nie jest typowym scenariuszem, oprogramowanie pośredniczące CORS można włączyć poprzez wywołanie RequireCors na punktach końcowych kontroli kondycji. Przeciążenie RequireCors akceptuje delegata konstruktora zasad CORS (CorsPolicyBuilder) lub nazwę zasad. Aby uzyskać więcej informacji, zobacz Włączanie żądań między źródłami (CORS) w ASP.NET Core.

Opcje kontroli kondycji

HealthCheckOptions umożliwia dostosowanie zachowania kontroli kondycji:

• Kontrole kondycji filtrów
• Dostosowywanie kodu stanu HTTP
• Blokowanie nagłówków pamięci podręcznej
• Dostosowywanie danych wyjściowych

Filtrowanie sprawdzania kondycji

Domyślnie oprogramowanie pośredniczące sprawdzania kondycji uruchamia wszystkie zarejestrowane kontrole kondycji. Aby uruchomić podzbiór testów kondycji, podaj funkcję, która zwraca wartość logiczną jako argument opcji Predicate.

Poniższy przykład filtruje kontrole zdrowotne, tak aby uruchamiane były tylko te oznaczone tagiem sample.

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

Dostosowywanie kodu stanu HTTP

Użyj ResultStatusCodes do dostosowywania mapowania stanu kondycji na kody stanu HTTP. Następujące StatusCodes przypisania są wartościami domyślnymi używanymi przez middleware. Zmień wartości kodu stanu, aby spełnić wymagania:

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

Tłumienie nagłówków pamięci podręcznej

AllowCachingResponses kontroluje, czy middleware do sprawdzania kondycji dodaje nagłówki HTTP do odpowiedzi z sondy, aby zapobiec buforowaniu odpowiedzi. Jeśli wartość to false (wartość domyślna), oprogramowanie pośredniczące ustawia lub zastępuje nagłówki Cache-Control, Expires i Pragma, aby zapobiec buforowaniu odpowiedzi. Jeśli wartość to true, oprogramowanie pośredniczące nie modyfikuje nagłówków pamięci podręcznej odpowiedzi:

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

Dostosowywanie danych wyjściowych

Aby dostosować dane wyjściowe raportu kontroli kondycji, ustaw HealthCheckOptions.ResponseWriter właściwość na delegata, który zapisuje odpowiedź:

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

Domyślny delegat zapisuje minimalną odpowiedź w postaci czystego tekstu z wartością ciągu HealthReport.Status. Poniższy delegat niestandardowy zwraca niestandardową odpowiedź JSON przy użyciu polecenia System.Text.Json:

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()));
}

Interfejs API sprawdzania kondycji nie zapewnia wbudowanej obsługi złożonych formatów zwracanych JSON, ponieważ format jest specyficzny dla wybranego systemu monitorowania. Dostosuj odpowiedź w poprzednich przykładach zgodnie z potrzebami. Aby uzyskać więcej informacji na temat serializacji JSON za pomocą System.Text.Json, zobacz Jak serializować i deserializować JSON na platformie .NET.

Sonda bazy danych

Kontrola kondycji może określić zapytanie bazy danych do uruchomienia jako test logiczny, aby wskazać, czy baza danych odpowiada normalnie.

AspNetCore.Diagnostics.HealthChecks, biblioteka sprawdzania kondycji dla aplikacji ASP.NET Core zawiera kontrolę kondycji uruchamianą względem bazy danych programu SQL Server. AspNetCore.Diagnostics.HealthChecks SELECT 1 Wykonuje zapytanie względem bazy danych, aby potwierdzić, że połączenie z bazą danych jest w dobrej kondycji.

Warning

Podczas sprawdzania połączenia z bazą danych przy użyciu zapytania wybierz zapytanie, które szybko zwraca. Podejście do zapytania powoduje przeciążenie bazy danych i obniżenie wydajności. W większości przypadków uruchomienie zapytania testowego nie jest konieczne. Wystarczy nawiązać pomyślne połączenie z bazą danych. Jeśli okaże się, że konieczne jest uruchomienie zapytania, wybierz proste zapytanie SELECT, takie jak SELECT 1.

Aby użyć tej kontroli kondycji programu SQL Server, dołącz odwołanie do AspNetCore.HealthChecks.SqlServer pakietu NuGet. Poniższy przykład rejestruje kontrolę kondycji programu SQL Server:

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);

Note

Firma Microsoft nie utrzymuje ani nie wspiera AspNetCore.Diagnostics.HealthChecks.

Sonda DbContext w Entity Framework Core

Sprawdzanie DbContext potwierdza, że aplikacja może komunikować się z bazą danych skonfigurowaną dla elementu EF CoreDbContext. Aplikacje, które obsługują DbContext weryfikację:

• Użyj platformy Entity Framework (EF) Core.
• Dołącz odniesienie do pakietu NuGet Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore.

AddDbContextCheck rejestruje kontrolę kondycji dla elementu DbContext. Element DbContext jest dostarczany do metody jako TContext. Przeciążenie jest dostępne do skonfigurowania stanu niepowodzenia, tagów i niestandardowego zapytania testowego.

Domyślnie:

• Wywołuje DbContextHealthCheck metodę EF CoreCanConnectAsync. Możesz dostosować operację wykonywaną podczas kontroli kondycji przy użyciu AddDbContextCheck przeciążeń metod.
• Nazwa sprawdzania kondycji to nazwa typu TContext.

Poniższy przykład rejestruje element DbContext i skojarzony element DbContextHealthCheck:

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

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

Oddzielne sondy gotowości i żywotności

W niektórych scenariuszach hostingu użyj pary kontroli kondycji, aby odróżnić dwa stany aplikacji:

• Gotowość wskazuje, czy aplikacja działa normalnie, ale nie jest gotowa do odbierania żądań.
• Liveness wskazuje, czy aplikacja uległa awarii i musi zostać ponownie uruchomiona.

Rozważmy następujący przykład: Aplikacja musi pobrać duży plik konfiguracji, zanim będzie gotowa do przetwarzania żądań. Nie chcesz ponownie uruchamiać aplikacji, jeśli początkowe pobieranie nie powiedzie się, ponieważ aplikacja może ponowić próbę pobrania pliku kilka razy. Użyj sondy liveness, aby opisać stan żywotności procesu, nie są uruchamiane żadne inne kontrole. Chcesz również uniemożliwić wysyłanie żądań do aplikacji przed pomyślnym pobraniem pliku konfiguracji. Użyj sondy gotowości, aby wskazać stan "nie jest gotowy", dopóki pobieranie się nie powiedzie, a aplikacja będzie gotowa do odbierania żądań.

Następujące zadanie w tle symuluje proces uruchamiania, który trwa około 15 sekund. Po zakończeniu zadania zadanie ustawia StartupHealthCheck.StartupCompleted właściwość na true:

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;
    }
}

Ten StartupHealthCheck raportuje ukończenie długotrwałego zadania uruchamiania i ujawnia właściwość StartupCompleted, którą ustawia usługa w tle.

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."));
    }
}

Zarejestruj kontrolę kondycji przy użyciu AddCheck w Program.cs, włącznie z usługą hostowaną. Ponieważ hostowana usługa ustawia właściwość na badanie stanu zdrowia, zarejestruj także badanie stanu zdrowia w kontenerze usługi jako singleton.

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

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

Aby utworzyć dwa różne punkty końcowe kontroli kondycji, wywołaj MapHealthChecks dwa razy.

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

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

W poprzednim przykładzie są tworzone następujące punkty końcowe sprawdzania kondycji:

• /healthz/ready w celu sprawdzenia gotowości. Sprawdzanie gotowości ogranicza kontrole kondycji do tych oznaczonych tagiem ready.
• /healthz/live w celu sprawdzenia żywotności. Sprawdzanie żywotności filtruje wszystkie kontrole kondycji, zwracając false w delegacie HealthCheckOptions.Predicate. Aby uzyskać więcej informacji na temat filtrowania kontroli kondycji, zobacz Filtrowanie kontroli kondycji w tym artykule.

Zanim zadanie uruchamiania zostanie ukończone, punkt końcowy /healthz/ready zgłasza stan Unhealthy. Po zakończeniu zadania uruchamiania ten punkt końcowy zgłasza stan Healthy. Punkt końcowy /healthz/live wyklucza wszystkie sprawdzania i raportuje stan Healthy dla wszystkich wywołań.

Przykład rozwiązania Kubernetes

Korzystanie z oddzielnych testów gotowości i dostępności jest przydatne w środowisku, takim jak Kubernetes. Na platformie Kubernetes może być konieczne uruchomienie czasochłonnych zadań podczas rozruchu, zanim aplikacja będzie mogła zaakceptować żądania, takich jak test dostępności podstawowej bazy danych. Korzystając z oddzielnych testów, koordynator może określić, czy aplikacja działa, ale nie jest jeszcze gotowa, czy nie można uruchomić aplikacji. Aby uzyskać więcej informacji na temat sond gotowości i kondycji na platformie Kubernetes, zobacz Konfigurowanie sond kondycji i gotowości w dokumentacji platformy Kubernetes.

W poniższym przykładzie pokazano konfigurację sondy gotowości Kubernetes:

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

Rozpowszechnianie biblioteki kontroli kondycji

Aby rozpowszechnić kontrolę stanu zdrowia jako bibliotekę:

1. Napisz kontrolę kondycji, która implementuje IHealthCheck interfejs jako klasę autonomiczną. Klasa może polegać na iniekcji zależności (DI), aktywacji typu i nazwanych opcjach uzyskiwania dostępu do danych konfiguracji.

2. Napisz metodę rozszerzenia z parametrami, które aplikacja, która korzysta, wywołuje w swojej metodzie Program.cs. Rozważmy następujące przykładowe sprawdzanie kondycji, które akceptuje arg1 i arg2 jako parametry konstruktora:

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

   Powyższy podpis wskazuje, że kontrola kondycji wymaga niestandardowych danych do przetwarzania logiki sondy sprawdzania kondycji. Dane są przekazywane delegatowi, który jest używany do utworzenia instancji sprawdzenia kondycji, gdy sprawdzenie kondycji jest zarejestrowane za pomocą metody rozszerzenia. W poniższym przykładzie obiekt wywołujący określa:

   • arg1: punkt danych typu liczbowego całkowitego dla sprawdzania stanu zdrowia.
   • arg2: argument ciągu dla sprawdzania kondycji.
   • name: opcjonalna nazwa sprawdzania kondycji. Jeśli nullzostanie użyta wartość domyślna.
   • failureStatus: opcjonalny HealthStatuselement , który jest zgłaszany dla stanu błędu. Jeśli null, HealthStatus.Unhealthy jest używany.
   • tags: opcjonalna IEnumerable<string> kolekcja tagów.

   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));
       }
   }
   

Wydawca kontroli kondycji

Po dodaniu elementu IHealthCheckPublisher do kontenera usługi system monitorowania kondycji okresowo wykonuje sprawdzanie kondycji i wywołuje PublishAsync z wynikiem. Ten proces jest przydatny w scenariuszu systemu monitorowania stanu zdrowia opartym na zasadzie wypychania, który oczekuje, że każdy proces będzie okresowo wywoływał system monitorowania w celu określenia stanu zdrowia.

HealthCheckPublisherOptions pozwól ustawić następujące ustawienia:

• Delay: początkowe opóźnienie po uruchomieniu aplikacji przed wykonaniem IHealthCheckPublisher wystąpień. Opóźnienie odbywa się raz podczas uruchamiania i nie ma zastosowania do późniejszych iteracji. Wartość domyślna to pięć sekund.
• Period: okres IHealthCheckPublisher wykonywania. Wartość domyślna to 30 sekund.
• Predicate: Jeśli Predicate jest null (wartość domyślna), usługa wydawcy testów kondycji uruchamia wszystkie zarejestrowane testy kondycji. Aby uruchomić podzbiór kontroli kondycji, podaj funkcję, która filtruje zestaw testów. Predykat jest obliczany w każdym okresie.
• Timeout: limit czasu na wykonywanie kontroli kondycji dla wszystkich IHealthCheckPublisher wystąpień. Użyj polecenia InfiniteTimeSpan , aby wykonać bez limitu czasu. Wartość domyślna to 30 sekund.

W poniższym przykładzie pokazano układ wydawcy zdrowotnego.

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

        return Task.CompletedTask;
    }
}

Klasa HealthCheckPublisherOptions udostępnia właściwości służące do konfigurowania zachowania publikatora sprawdzania kondycji systemu.

W poniższym przykładzie wydawca kontroli kondycji jest rejestrowany jako singleton i konfiguruje HealthCheckPublisherOptions element:

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:

• Zawiera wydawców dla kilku systemów, w tym Application Insights.
• Nie jest obsługiwany ani utrzymywany przez firmę Microsoft.

Indywidualne kontrole kondycji

Można ustawić Delay i Period indywidualnie na każdym HealthCheckRegistration. Ustaw te wartości, gdy chcesz uruchomić niektóre kontrole kondycji z inną szybkością niż okres ustawiony w pliku HealthCheckPublisherOptions.

Poniższy kod ustawia wartości Delay i Period dla elementu SampleHealthCheck1:

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();

Wstrzykiwanie zależności i kontrole kondycji

Można zastosować iniekcję zależności, aby wykorzystać instancję określonego Type wewnątrz klasy monitorującej stan zdrowia. Wstrzykiwanie zależności może być przydatne do wstrzykiwania opcji lub konfiguracji globalnej do kontroli kondycji. Używanie wstrzykiwania zależności nie jest typowym scenariuszem konfigurowania kontroli kondycji. Zwykle każde sprawdzenie kondycji jest dość specyficzne dla rzeczywistego testu i jest konfigurowane przy użyciu metod rozszerzeń IHealthChecksBuilder.

W poniższym przykładzie pokazano przykładową kontrolę kondycji, która pobiera obiekt konfiguracji za pośrednictwem iniekcji zależności:

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."));
    }
}

Element SampleHealthCheckWithDiConfig oraz sprawdzanie kondycji należy dodać do kontenera usługi :

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 vs MapHealthChecks

Kontrole stanu zdrowia można umożliwić dostęp osobom dzwoniącym na dwa sposoby:

• UseHealthChecks rejestruje oprogramowanie pośredniczące do obsługi żądań kontroli kondycji w potoku oprogramowania pośredniczącego.
• MapHealthChecks rejestruje punkt końcowy kontroli kondycji. Punkt końcowy jest zgodny i wykonywany wraz z innymi punktami końcowymi w aplikacji.

Zamiast korzystać z MapHealthChecks, można użyć pośredniego oprogramowania obsługującego punkty końcowe, takiego jak autoryzacja, co pozwala uzyskać bardziej precyzyjną kontrolę nad polityką dopasowywania. UseHealthChecks Używając zamiast MapHealthChecks, można kontrolować dokładnie, gdzie testy kondycji są uruchamiane w potoku oprogramowania pośredniczącego.

UseHealthChecks:

• Przerywa potok, gdy żądanie jest zgodne z punktem końcowym sprawdzania kondycji. Krótkie spięcie jest często pożądane, ponieważ pozwala uniknąć niepotrzebnej pracy, takiej jak logowanie oraz inne elementy pośredniczące.
• Służy głównie do konfigurowania middleware monitorowania stanu w potoku.
• Może dopasować dowolną ścieżkę na porcie używając null lub pustego PathString. Umożliwia wykonanie kontroli zdrowia dla każdego żądania kierowanego do określonego portu.
• Kod źródłowy

MapHealthChecks Pozwala:

• Kończenie potoku, gdy żądanie jest zgodne z punktem końcowym sprawdzania kondycji, wywołując metodę ShortCircuit. Na przykład app.MapHealthChecks("/healthz").ShortCircuit();. Aby uzyskać więcej informacji, zobacz Oprogramowanie pośredniczące zwarcie po routingu.
• Mapowanie określonych tras lub punktów końcowych na potrzeby kontroli kondycji.
• Dostosowanie adresu URL lub ścieżki, w której jest dostępny punkt końcowy sprawdzania kondycji.
• Mapowanie wielu punktów końcowych kontroli kondycji z różnymi trasami lub konfiguracjami. Obsługa wielu punktów końcowych:
  • Włącza oddzielne punkty końcowe dla różnych typów testów kondycji lub składników.
  • Służy do rozróżniania różnych aspektów kondycji aplikacji lub stosowania określonych konfiguracji do podzbiorów kontroli kondycji.
• Kod źródłowy

Dodatkowe zasoby

• Wyświetl lub pobierz przykładowy kod (jak pobrać)

Note

Ten artykuł został częściowo utworzony z pomocą sztucznej inteligencji. Przed opublikowaniem autor przejrzał i poprawił zawartość zgodnie z potrzebą. Zapoznaj się z naszymi zasadami korzystania z zawartości generowanej za pośrednictwem AI w usłudze Microsoft Learn.