Integritätsprüfungen in ASP.NET Core

Von Glenn Condron und Jürgen Gutsch

ASP.NET Core bietet Middleware für Integritätsprüfungen und Bibliotheken für die Berichterstellung für Komponenten der App-Infrastruktur.

Integritätsprüfungen werden von einer App als HTTP-Endpunkte verfügbar gemacht. Endpunkte für die Integritätsprüfung können für verschiedene Echtzeitüberwachungsszenarien konfiguriert werden:

• Integritätstests können von Containerorchestratoren und Lastenausgleichsmodulen verwendet werden, um den Status einer App zu überprüfen. Ein Containerorchestrator kann z.B. auf eine fehlerhafte Integritätsprüfung reagieren, indem die Ausführung einer Bereitstellung angehalten oder ein Container neu gestartet wird. Ein Lastenausgleichsmodul kann auf eine fehlerhafte App reagieren, indem Datenverkehr von der fehlerhaften zu einer fehlerfreien Instanz umgeleitet wird.
• Die Nutzung von Arbeitsspeicher, Datenträgern und anderen physischen Serverressourcen kann auf einen fehlerfreien Status überwacht werden.
• Integritätsprüfungen können die Abhängigkeiten einer App testen, wie z.B. Datenbanken und externe Dienstendpunkte, um Verfügbarkeit und normale Funktionsweise zu bestätigen.

Integritätsprüfungen werden in der Regel mit einem externen Überwachungsdienst oder Containerorchestrator verwendet, um den Status einer App zu überprüfen. Bevor Sie Integritätsprüfungen zu einer App hinzufügen, entscheiden Sie, welches Überwachungssystem verwendet werden soll. Das Überwachungssystem bestimmt, welche Arten von Integritätsprüfungen erstellt und wie die jeweiligen Endpunkte konfiguriert werden müssen.

Grundlegender Integritätstest

In vielen Apps genügt zur Ermittlung des App-Status eine grundlegende Integritätstestkonfiguration, die die Verfügbarkeit der App für die Verarbeitung von Anforderungen (Lebendigkeit) meldet.

Die grundlegende Konfiguration registriert Integritätsprüfungsdienste und ruft die Middleware für Integritätsprüfungen auf, damit diese an einem URL-Endpunkt mit dem Integritätsstatus antwortet. Standardmäßig werden keine spezifischen Integritätsprüfungen registriert, um eine bestimmte Abhängigkeit oder ein bestimmtes Subsystem zu testen. Die App wird als fehlerfrei angesehen, wenn sie an der URL des Integritätsendpunkts antworten kann. Der Standardantwortwriter schreibt HealthStatus als Klartextantwort an den Client. HealthStatus ist HealthStatus.Healthy, HealthStatus.Degraded oder HealthStatus.Unhealthy.

Registrieren Sie Integritätsprüfungsdienste mit AddHealthChecks in Program.cs. Erstellen Sie einen Integritätsprüfungsendpunkt durch Aufrufen von MapHealthChecks.

Im folgenden Beispiel wird ein Integritätsprüfungsendpunkt unter /healthz erstellt:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Docker HEALTHCHECK

Docker bietet eine integrierte HEALTHCHECK-Direktive, mit der Sie den Status einer App überprüfen können, die die grundlegende Konfiguration für Integritätsprüfungen verwendet:

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

Das vorherige Beispiel verwendet curl, um eine HTTP-Anforderung an den Integritätsprüfungsendpunkt bei /healthz auszugeben. curl ist nicht in den .NET Linux-Containerimages enthalten, kann aber hinzugefügt werden, indem das erforderliche Paket in der Dockerfile installiert wird. Container, die auf Alpine Linux basierende Images verwenden, können das enthaltene wget anstelle von curl verwenden.

Erstellen von Integritätsprüfungen

Integritätsprüfungen werden durch Implementieren der IHealthCheck-Schnittstelle erstellt. Die CheckHealthAsync-Methode gibt ein HealthCheckResult zurück, das die Integrität als Healthy, Degraded oder Unhealthy angibt. Das Ergebnis wird als Klartextantwort mit einem konfigurierbaren Statuscode geschrieben. Die Konfiguration wird im Abschnitt Integritätsprüfungsoptionen beschrieben. HealthCheckResult kann auch optionale Schlüssel-Wert-Paare zurückgeben.

Das folgende Beispiel veranschaulicht das Layout einer Integritätsprüfung:

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

Die Integritätsprüfungslogik wird in der CheckHealthAsync-Methode platziert. Im vorherigen Beispiel wird die Dummyvariable isHealthy auf true festgelegt. Wenn der Wert von isHealthy auf false festgelegt ist, wird der HealthCheckRegistration.FailureStatus-Status zurückgegeben.

Wenn CheckHealthAsync während der Überprüfung eine Ausnahme auslöst, wird ein neues Element HealthReportEntry zurückgegeben, dessen HealthReportEntry.Status auf FailureStatus festgelegt ist. Dieser Status ist definiert durch AddCheck (weitere Informationen finden Sie im Abschnitt Registrieren von Diensten zur Integritätsprüfung) und enthält die innere Ausnahme, die den Prüfungsfehler verursacht hat. Description ist auf die Meldung der Ausnahme festgelegt.

Registrieren von Integritätsprüfungsdiensten

Rufen Sie AddCheck in Program.cs auf, um einen Integritätsprüfungsdienst zu registrieren:

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

Die in der folgenden Abbildung gezeigte AddCheck-Überladung legt den Fehlerstatus (HealthStatus) fest, der angegeben werden soll, wenn die Integritätsprüfung einen Fehler meldet. Wenn der Fehlerstatus auf null (Standardwert) festgelegt ist, wird HealthStatus.Unhealthy gemeldet. Diese Überladung ist ein nützliches Szenario für Bibliotheksersteller: Bei einem Integritätsprüfungsfehler wird der durch die Bibliothek angegebene Fehlerstatus von der App erzwungen, wenn die Implementierung der Integritätsprüfung die Einstellung berücksichtigt.

Tags können zum Filtern von Integritätsprüfungen verwendet werden. Tags werden im Abschnitt Filtern von Integritätsprüfungen beschrieben.

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

AddCheck kann auch eine Lambdafunktion ausführen. Im folgenden Beispiel gibt die Integritätsprüfung immer ein fehlerfreies Ergebnis zurück:

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

Rufen Sie AddTypeActivatedCheck auf, um Argumente an die Implementierung einer Integritätsprüfung zu übergeben. Im folgenden Beispiel akzeptiert eine typaktivierte Integritätsprüfung in ihrem Konstruktor eine ganze Zahl und eine Zeichenfolge:

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

Um die vorherige Integritätsprüfung zu registrieren, rufen Sie AddTypeActivatedCheck mit der ganzen Zahl und der Zeichenfolge auf, die als Argumente übergeben werden:

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

Verwenden von Integritätsprüfungsrouting

Rufen Sie in Program.cs auf der Endpunkterstellung mit der Endpunkt-URL oder dem relativen Pfad MapHealthChecks auf:

app.MapHealthChecks("/healthz");

Anfordern des Hosts

Rufen Sie RequireHost auf, um einen oder mehrere zugelassene Hosts für den Integritätsprüfungs-Endpunkt anzugeben. Hosts sollten Unicode anstelle von Punycode verwenden und können einen Port enthalten. Wenn keine Sammlung bereitgestellt wird, wird jeder Host akzeptiert:

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

Um den Integritätsprüfungsendpunkt so einzuschränken, dass er nur an einem bestimmten Port antwortet, geben Sie beim Aufruf von RequireHost einen Port an. Dieser Ansatz wird normalerweise in einer Containerumgebung verfolgt, um einen Port für Überwachungsdienste verfügbar zu machen:

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

Warnung

Die APIs, die auf dem Hostheader basieren, z. B. HttpRequest.Host und RequireHost, sind potenziellem Spoofing durch Clients ausgesetzt.

Verwenden Sie einen der folgenden Ansätze, um Host- und Portspoofing zu verhindern:

• Verwenden Sie HttpContext.Connection (ConnectionInfo.LocalPort), wobei die Ports aktiviert sind.
• Verwenden Sie die Hostfilterung.

Um zu verhindern, dass nicht autorisierte Clients den Port spoofen, rufen Sie RequireAuthorization auf:

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

Weitere Informationen finden Sie unter Hostabgleich in Routen mit RequireHost.

Anfordern der Autorisierung

Rufen Sie RequireAuthorization auf, um die Autorisierungsmiddleware auf dem Integritätsprüfungs-Anforderungsendpunkt auszuführen. Eine RequireAuthorization-Überladung akzeptiert eine oder mehrere Autorisierungsrichtlinien. Wenn keine Richtlinie bereitgestellt wird, wird die standardmäßige Autorisierungsrichtlinie verwendet:

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

Aktivieren ursprungsübergreifender Anforderungen (CORS)

Obwohl das manuelle Ausführen von Integritätsprüfungen über einen Browser kein gängiges Szenario ist, kann CORS-Middleware durch Aufrufen von RequireCors für Integritätsprüfungsendpunkte aktiviert werden. Eine RequireCors-Überladung akzeptiert einen CORS-Richtliniengenerator-Delegaten (CorsPolicyBuilder) oder einen Richtliniennamen. Weitere Informationen finden Sie unter Aktivieren ursprungsübergreifender Anforderungen (Cross-Origin Requests, CORS) in ASP.NET Core.

Optionen für die Integritätsprüfung

HealthCheckOptions ermöglichen die Anpassung des Verhaltens von Integritätsprüfungen:

• Filtern von Integritätsprüfungen
• Anpassen des HTTP-Statuscodes
• Unterdrücken von Cacheheadern
• Anpassen der Ausgabe

Filtern von Integritätsprüfungen

Standardmäßig führt die Middleware für Integritätsprüfungen alle registrierten Integritätsprüfungen aus. Um eine Teilmenge von Integritätsprüfungen auszuführen, stellen Sie eine Funktion bereit, die einen booleschen Wert an die Option Predicate zurückgibt.

Im folgenden Beispiel werden die Integritätsprüfungen so gefiltert, dass nur die mit sample gekennzeichneten ausgeführt werden:

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

Anpassen des HTTP-Statuscodes

Verwenden Sie ResultStatusCodes, um die Zuordnung des Integritätsstatus zu HTTP-Statuscodes anzupassen. Die folgenden StatusCodes-Zuweisungen stellen die von der Middleware verwendeten Standardwerte dar. Ändern Sie die Statuscodewerte so, dass sie Ihren Anforderungen entsprechen:

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

Unterdrücken von Cacheheadern

AllowCachingResponses steuert, ob die Middleware für Integritätsprüfungen einer Testantwort HTTP-Header hinzufügt, um das Zwischenspeichern von Antworten zu verhindern. Wenn der Wert false (Standard) lautet, legt die Middleware die Header Cache-Control, Expires und Pragma fest oder überschreibt sie, um eine Zwischenspeicherung der Antworten zu verhindern. Wenn der Wert true lautet, ändert die Middleware die Cacheheader der Antwort nicht:

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

Anpassen der Ausgabe

Um die Ausgabe eines Integritätsprüfungsberichts anzupassen, legen Sie die Eigenschaft HealthCheckOptions.ResponseWriter für einen Delegaten fest, der die Antwort schreibt:

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

Der Standarddelegat schreibt eine minimale Klartextantwort mit dem Zeichenfolgenwert HealthReport.Status. Der folgende benutzerdefinierte Delegat gibt eine benutzerdefinierte JSON-Antwort mithilfe von System.Text.Json aus:

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

Die Integritätsprüfungs-API bietet keine integrierte Unterstützung für komplexe JSON-Rückgabeformate, da das Format für Ihre Überwachungssystemauswahl spezifisch ist. Passen Sie die Antwort in den vorangehenden Beispielen nach Bedarf an. Weitere Informationen zur JSON-Serialisierung mit System.Text.Json finden Sie unter Serialisieren und Deserialisieren von JSON in .NET.

Datenbanktest

Eine Integritätsprüfung kann eine Datenbankabfrage angeben, die als boolescher Test ausgeführt wird, um zu ermitteln, ob die Datenbank normal reagiert.

AspNetCore.Diagnostics.HealthChecks, eine Integritätsprüfungsbibliothek für ASP.NET Core-Apps, enthält eine Integritätsprüfung, die für eine SQL Server-Datenbank ausgeführt wird. AspNetCore.Diagnostics.HealthChecks führt eine SELECT 1-Abfrage in der Datenbank aus, um zu bestätigen, dass die Verbindung mit der Datenbank fehlerfrei ist.

Warnung

Wenn Sie die Datenbankverbindung mithilfe einer Abfrage überprüfen, wählen Sie eine Abfrage aus, die eine schnelle Antwort zurückgibt. Bei einer Abfrage besteht immer das Risiko, dass die Datenbank überladen und ihre Leistung beeinträchtigt wird. In den meisten Fällen ist es nicht notwendig, eine Testabfrage auszuführen. Es genügt zumeist, einfach erfolgreich eine Verbindung mit der Datenbank herzustellen. Wenn Sie eine Abfrage ausführen müssen, wählen Sie eine einfache SELECT-Abfrage aus, wie z.B. SELECT 1.

Um diese SQL Server-Integritätsprüfung zu verwenden, fügen Sie einen Paketverweis auf das NuGet-Paket AspNetCore.HealthChecks.SqlServer ein. Im folgenden Beispiel wird die SQL Server-Integritätsüberprüfung registriert:

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

Hinweis

AspNetCore.Diagnostics.HealthChecks wird nicht von Microsoft verwaltet oder unterstützt.

Entity Framework Core-DbContext-Test

Die DbContext-Überprüfung bestätigt, dass die App mit der Datenbank kommunizieren kann, die für einen EF Core-DbContext konfiguriert wurde. Die DbContext Überprüfung wird in Apps unterstützt, für die gilt:

• In ihnen wird Entity Framework Core (EF Core) verwendet.
• Fügen Sie einen Verweis auf das NuGet-Paket Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore ein.

AddDbContextCheck registriert eine Integritätsprüfung für einen DbContext. DbContext wird der Methode als TContext bereitgestellt. Eine Überladung ist verfügbar, um den Fehlerstatus, Tags sowie eine benutzerdefinierte Testabfrage zu konfigurieren.

Standardmäßig:

• Der DbContextHealthCheck ruft die CanConnectAsync-Methode von EF Core auf. Sie können festlegen, welcher Vorgang ausgeführt wird, wenn die Integrität mit AddDbContextCheck-Methodenüberladungen überprüft wird.
• Der Name der Integritätsprüfung ist der Name des TContext-Typs.

Im folgenden Beispiel werden ein DbContext und ein zugeordneter DbContextHealthCheck registriert:

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

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

Separate Tests für Bereitschaft und Lebendigkeit

In einigen Hostingszenarien wird ein Integritätsprüfungspaar verwendet, mit dem zwischen zwei App-Status unterschieden wird:

• Bereitschaft gibt an, ob die App ordnungsgemäß ausgeführt wird, aber nicht für den Empfang von Anforderungen bereit ist.
• Livetest gibt an, ob eine App abgestürzt ist und neu gestartet werden muss.

Betrachten Sie das folgende Beispiel: Eine App muss eine große Konfigurationsdatei herunterladen, bevor sie für die Verarbeitung von Anforderungen bereit ist. Wir möchten nicht, dass die App neu gestartet wird, wenn der erste Download fehlschlägt, da die App mehrmals versuchen kann, die Datei herunterzuladen. Wir verwenden einen Livetest, um den Livezustand des Prozesses zu beschreiben. Weitere Überprüfungen erfolgen nicht. Außerdem soll verhindert werden, dass Anforderungen an die App gesendet werden, bevor die Konfigurationsdatei erfolgreich heruntergeladen wurde. Wir verwenden einen Bereitschaftstest, um den Status "nicht bereit" anzugeben, bis der Download erfolgreich durchgeführt wurde und die App für den Empfang von Anforderungen bereit ist.

Die folgende Hintergrundaufgabe simuliert einen Startprozess, der ungefähr 15 Sekunden dauert. Nach Abschluss des Vorgangs legt die Aufgabe die StartupHealthCheck.StartupCompleted-Eigenschaft auf TRUE fest:

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 meldet die Beendigung der lang ausgeführten Startaufgabe und macht die Eigenschaft StartupCompleted verfügbar, die vom Hintergrunddienst festgelegt wird:

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

Die Integritätsprüfung wird mit AddCheck zusammen mit dem gehosteten Dienst in Program.cs registriert. Da der gehostete Dienst die Eigenschaft in der Integritätsprüfung festlegen muss, wird die Integritätsprüfung ebenfalls im Dienstcontainer als Singleton registriert:

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

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

Um zwei verschiedene Integritätsprüfungsendpunkte zu erstellen, rufen Sie MapHealthChecks zweimal auf:

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

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

Im vorherigen Beispiel werden die folgenden Integritätsprüfungsendpunkte erstellt:

• /healthz/ready für die Bereitschaftsprüfung. Die Bereitschaftsprüfung filtert Integritätsprüfungen heraus, die mit ready gekennzeichnet sind.
• /healthz/live für die Lebendigkeitsprüfung. Die Liveüberprüfung filtert alle Integritätsprüfungen heraus, indem false im Delegaten HealthCheckOptions.Predicate zurückgegeben wird. Weitere Informationen zum Filtern von Integritätsprüfungen finden Sie unter Filtern von Integritätsprüfungen in diesem Artikel.

Bevor die Startaufgabe abgeschlossen ist, meldet der Endpunkt /healthz/ready den Status Unhealthy. Bevor die Startaufgabe abgeschlossen ist, meldet dieser Endpunkt den Status Healthy. Der Endpunkt /healthz/live schließt alle Überprüfungen aus und meldet für alle Aufrufe den Status Healthy.

Kubernetes-Beispiel

Die Verwendung von Bereitschafts- und Lebendigkeitstests ist in Umgebungen wie Kubernetes sehr nützlich. In Kubernetes muss eine App möglicherweise zeitaufwendige Startaufgaben ausführen, bevor sie Anforderungen wie z. B. das Testen der Verfügbarkeit der zugrunde liegenden Datenbank erfüllt. Durch Verwendung separater Überprüfungen kann der Orchestrator unterscheiden, ob eine App funktioniert, aber noch nicht bereit ist, oder ob die App nicht gestartet wurde. Weitere Informationen zu Bereitschafts- und Lebendigkeitstests in Kubernetes finden Sie in der Kubernetes-Dokumentation unter Configure Liveness and Readiness Probes (Konfigurieren von Lebendigkeits- und Bereitschaftstests).

Das folgende Beispiel veranschaulicht die Konfiguration eines Bereitschaftstests in 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

Verteilen einer Integritätsprüfungsbibliothek

So verteilen Sie eine Integritätsprüfung als Bibliothek:

1. Schreiben Sie eine Integritätsprüfung, die die IHealthCheck-Schnittstelle als eigenständige Klasse implementiert. Die Klasse kann Abhängigkeitsinjektion (Dependency Injection, DI), Typaktivierung und benannte Optionen verwenden, um auf Konfigurationsdaten zuzugreifen.

2. Schreiben Sie eine Erweiterungsmethode mit Parametern, die von der nutzenden App in ihrer Program.cs-Methode aufgerufen werden. Betrachten Sie das folgende Beispiel einer Integritätsprüfung, die arg1 und arg2 als Konstruktorparameter akzeptiert:

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

   Die vorherige Signatur gibt an, dass die Integritätsprüfung benutzerdefinierte Daten benötigt, um die Prüflogik der Integritätsprüfung zu verarbeiten. Die Daten werden für den Delegaten bereitgestellt, der zum Erstellen der Integritätsprüfungsinstanz verwendet wird, wenn die Integritätsprüfung bei einer Erweiterungsmethode registriert wird. Im folgenden Beispiel gibt der Aufrufer Folgendes an:

   • arg1: ein integer-Datenpunkt für die Integritätsprüfung.
   • arg2: ein Zeichenfolgenargument für die Integritätsprüfung.
   • name: ein optionaler Name der Integritätsprüfung. Falls null, wird ein Standardwert verwendet.
   • failureStatus: ein optionales Element HealthStatus, das bei einem Fehlerstatus gemeldet wird. Wenn der Wert null ist, wird HealthStatus.Unhealthy verwendet.
   • tags: eine optionale IEnumerable<string>-Sammlung von Tags.

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

Herausgeber der Integritätsprüfung

Wenn dem Dienstcontainer ein IHealthCheckPublisher hinzugefügt wird, führt das Integritätsprüfungssystem Ihre Integritätsprüfungen regelmäßig aus und ruft PublishAsync mit dem Ergebnis auf. Dieser Prozess ist nützlich in einem Szenario mit pushbasiertem Integritätsüberwachungssystem, in dem jeder Prozess das Überwachungssystem regelmäßig aufrufen muss, um Integrität zu bestimmen.

HealthCheckPublisherOptions ermöglichen Ihnen, Folgendes festzulegen:

• Delay: Hierbei handelt es sich um die angewendete anfängliche Verzögerung zwischen dem Start der App und der Ausführung von IHealthCheckPublisher-Instanzen. Die Verzögerung wird einmal beim Start angewendet und gilt nicht für spätere Iterationen. Der Standardwert beträgt fünf Sekunden.
• Period: Hierbei handelt es sich um die Dauer der Ausführung von IHealthCheckPublisher. Der Standardwert ist 30 Sekunden.
• Predicate: Wenn der Wert für Predicatenull ist (Standard), führt der Veröffentlichungsdienst für die Integritätsprüfung alle registrierten Integritätsprüfungen durch. Um eine Teilmenge von Integritätsprüfungen auszuführen, stellen Sie eine Funktion bereit, die die Menge der Prüfungen filtert. Das Prädikat wird in jedem Zeitraum ausgewertet.
• Timeout: Hierbei handelt es sich um das Zeitlimit für die Ausführung der Integritätsprüfungen für alle IHealthCheckPublisher-Instanzen. Verwenden Sie InfiniteTimeSpan zur Ausführung ohne Timeout. Der Standardwert ist 30 Sekunden.

Das folgende Beispiel veranschaulicht das Layout eines Integritätsprüfungsherausgebers:

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

        return Task.CompletedTask;
    }
}

Die HealthCheckPublisherOptions-Klasse stellt Eigenschaften zum Konfigurieren des Verhaltens des Integritätsprüfungsherausgebers bereit.

Im folgenden Beispiel wird ein Integritätsprüfungsherausgeber als Singleton registriert und HealthCheckPublisherOptions konfiguriert:

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:

• Enthält Herausgeber für verschiedene Systeme, einschließlich Application Insights.
• Wird von Microsoft nicht verwaltet oder unterstützt.

Individuelle Integritätsprüfungen

Delayund Period können jeweils einzeln für HealthCheckRegistration festgelegt werden. Dies ist nützlich, wenn Sie einige Integritätsprüfungen in einem anderen Rhythmus als dem in HealthCheckPublisherOptions festgelegten Zeitraum durchführen möchten.

Mit dem folgenden Code wird Delay und Period für SampleHealthCheck1 festgelegt:

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

Abhängigkeitsinjektion und Integritätsprüfungen

Es ist möglich, eine Instanz eines bestimmten Type innerhalb einer Integritätsprüfungsklasse über eine Abhängigkeitsinjektion zu verwenden. Die Abhängigkeitsinjektion kann hilfreich sein, um Optionen oder eine globale Konfiguration in eine Integritätsprüfung einzufügen. Die Verwendung der Abhängigkeitsinjektion ist kein gängiges Szenario zum Konfigurieren von Integritätsprüfungen. In der Regel ist jede Integritätsprüfung spezifisch für den tatsächlichen Test und wird mithilfe von IHealthChecksBuilder-Erweiterungsmethoden konfiguriert.

Das folgende Beispiel zeigt ein Beispiel für eine Integritätsprüfung, die ein Konfigurationsobjekt über eine Abhängigkeitsinjektion abruft:

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 und die Integritätsprüfung müssen dem Dienstcontainer hinzugefügt werden:

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 im Vergleich zu MapHealthChecks

Es gibt zwei Möglichkeiten, Integritätsprüfungen für Aufrufer zugänglich zu machen:

• UseHealthChecks registriert Middleware für die Verarbeitung von Integritätsprüfungsanforderungen in der Middlewarepipeline.
• MapHealthChecks registriert einen Integritätsprüfungsendpunkt. Der Endpunkt wird zusammen mit anderen Endpunkten in der App abgeglichen und ausgeführt.

Der Vorteil der Verwendung von MapHealthChecks gegenüber UseHealthChecks ist die Möglichkeit, endpunktfähige Middleware wie Autorisierung zu verwenden und eine präzisere Kontrolle über die Abgleichsrichtlinie zu haben. Der Hauptvorteil der Verwendung von UseHealthChecks gegenüber MapHealthChecks besteht darin, genau zu steuern, wo Integritätsprüfungen in der Middlewarepipeline ausgeführt werden.

UseHealthChecks:

• Beendet die Pipeline, wenn eine Anforderung mit dem Integritätsprüfungsendpunkt übereinstimmt. Kurzschlüsse sind häufig wünschenswert, da dadurch unnötige Arbeit vermieden wird, z. B. Protokollierung und andere Middleware.
• Wird in erster Linie zum Konfigurieren der Integritätsprüfungsmiddleware in der Pipeline verwendet.
• Kann einen beliebigen Pfad an einem Port mit einem null-Wert oder einem leeren PathString-Wert abgleichen. Ermöglicht das Durchführen einer Integritätsprüfung für jede Anforderung, die an den angegebenen Port gestellt wird.
• Quellcode

MapHealthChecks ermöglicht:

• Beendet die Pipeline, wenn eine Anforderung mit dem Integritätsprüfungsendpunkt übereinstimmt, indem ShortCircuit aufgerufen wird. Beispiel: app.MapHealthChecks("/healthz").ShortCircuit();. Weitere Informationen finden Sie unter Kurzschluss der Middleware nach dem Routing.
• Zuordnen bestimmter Routen oder Endpunkte für Integritätsprüfungen.
• Anpassen der URL oder des Pfads, unter der bzw. dem auf den Integritätsprüfungsendpunkt zugegriffen werden kann.
• Zuordnen mehrerer Integritätsprüfungsendpunkte mit unterschiedlichen Routen oder Konfigurationen. Unterstützung mehrerer Endpunkte:
  • Aktiviert separate Endpunkte für verschiedene Arten von Integritätsprüfungen oder -komponenten.
  • Wird verwendet, um zwischen verschiedenen Aspekten der App-Integrität zu unterscheiden oder bestimmte Konfigurationen auf Teilmengen von Integritätsprüfungen anzuwenden.
• Quellcode

Zusätzliche Ressourcen

• Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Hinweis

Dieser Artikel wurde teilweise mit Hilfe künstlicher Intelligenz erstellt. Vor der Veröffentlichung hat ein Autor den Inhalt geprüft und nach Bedarf überarbeitet. Weitere Informationen finden Sie unter Unsere Prinzipien für die Verwendung von KI-generierten Inhalten in Microsoft Learn.