Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Lesedauer 4 Min.

Grundlagen von Health Checks

Ein einfacher Statuscode sagt wenig darüber aus, ob eine Anwendung wirklich betriebsbereit ist. ASP.NET bietet dafür mehr Möglichkeiten, als viele /health-Endpunkte vermuten lassen. Genau dort beginnt der Unterschied zwischen Erreichbarkeit und echter Diagnose.
Healthcheck.jpg
© EMGenie

In vielen Projekten existiert ein /health-Endpunkt, um anzugeben, ob ein Dienst beziehungsweise Endpunkt noch erreichbar ist. Dieser Health Check gibt aber allzu häufig lediglich einen HTTP-Status-Code 200 als OK zurück. Das ist zwar ein technisches Merkmal, dass alles in Ordnung ist, allerdings ohne jeden fachlichen Mehrwert.

Moderne Health Checks sollten dagegen darauf abzielen, die tatsächliche Betriebsfähigkeit der Anwendung und ihrer Abhängigkeiten zu überprüfen und maschinenlesbar zu berichten. Hier ist ASP.NET Core keine Ausnahme. Seit .NET Core 2.2 ist das Health-Check-Framework direkt in ASP.NET Core integriert. Es stellt ein standardisiertes API über die Schnittstelle IHealthCheck, eine zentrale Ausführungskomponente über HealthCheckService und eine Middleware für HTTP-Endpunkte zur Verfügung. Ein Health Check liefert eine HealthStatus-Enumeration mit den Werten Healthy, Degraded sowie Unhealthy plus optionale Daten und Fehlermeldungen, die Monitoring-Systeme wie Prometheus, Azure Application Insights oder Kubernetes-Probes auswerten können.

Die Basiskonfiguration ist minimal: In Program.cs sind die Health Checks zu registrieren und auf einen Endpunkt zu mappen. Im Minimal-Hosting-Modell kann das in etwa so aussehen wie in Listing 1.

Listing 1: Beispiel für die Basis-Registrierung eines Health Checks
var builder = WebApplication.CreateBuilder(args);
builder.Services
    .AddHealthChecks(); // Basis-Registrierung
var app = builder.Build();
app.MapHealthChecks("/health");
app.Run(); 
Ausgabe des Health-Endpunkts im Browser (Bild 1)

Ausgabe des Health-Endpunkts im Browser (Bild 1)

© Autor
Ausgabe des Health-Endpunkts in Postman (Bild 2)

Ausgabe des Health-Endpunkts in Postman (Bild 2)

© Autor

Dieser Endpunkt gibt standardmäßig nur den aggregierten Status zurück (HTTP-Status-Code 200 für Healthy oder Degraded, 503 für Unhealthy). Bild 1 zeigt die Ausgabe im Browser und Bild 2 zeigt die Antwort in Postman.

Für produktive Szenarien empfiehlt sich jedoch eine ausführlichere Ausgabe, etwa JSON, die pro Check einen Status und die entsprechende Fehlermeldung enthält, wie Listing 2 zeigt.

Listing 2: Health-Check-Implementierung mit Status-Informationen
using Microsoft.AspNetCore.Diagnostics.HealthChecks;
using System.Text.Json;
app.MapHealthChecks("/health", new HealthCheckOptions
{
    ResponseWriter = async (context, report) =>
    {
        context.Response.ContentType = "application/json";
        var payload = new
        {
            status = report.Status.ToString(),
            results = report.Entries.Select(e => new
            {
                name = e.Key,
                status = e.Value.Status.ToString(),
                description = e.Value.Description,
                duration = e.Value.Duration.TotalMilliseconds,
            })
        };
        await context.Response.WriteAsync(JsonSerializer.Serialize(payload));
    }
}); 

Die Rückgabe ist jetzt die nachfolgende JSON-Ausgabe, die in Bild 3 als Resultat in Postman gezeigt ist.

 

{"status":"Healthy","results":[]}

 

Damit wird /health zum echten Diagnose-Endpunkt, der nicht nur „rot“ signalisiert, sondern konkret sagt, welcher Check versagt hat und wie lange die Ausführung gedauert hat.

Eigene Checks mit IHealthCheck

Um prüfbare Abhängigkeiten wie Datenbank, Dateisystem oder externe APIs abzudecken, lässt sich die Schnittstelle IHealthCheck implementieren. Die Methode CheckHealthAsync liefert ein HealthCheckResult, das Status, optionale Schlüssel-Werte-Daten und eine Beschreibung enthält. Der Code in Listing 3 demonstriert den Aufbau eines einfachen Checks.

Ausgabe des Health-Endpunkts im JSON-Format in Postman (Bild 3)

Ausgabe des Health-Endpunkts im JSON-Format in Postman (Bild 3)

© Autor
Listing 3: Implementierung für einen Health Check in einer eigenen Klasse
public class SampleHealthCheck : IHealthCheck
{
    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context,
        CancellationToken cancellationToken = default)
    {
        var isHealthy = true; // Prüflogik...
        if (isHealthy)
        {
            return Task.FromResult(
                HealthCheckResult.Healthy("Alles in Ordnung"));
        }
        return Task.FromResult(
            new HealthCheckResult(
                context.Registration.FailureStatus,
                "Ein Fehler ist aufgetreten"));
    }
} 

In der Konfiguration muss der Check über AddCheck registriert sein. Dabei lassen sich Fehlerstatus und Tags festgelegen. Tags helfen später bei der Unterscheidung zwischen Liveness- und Readiness-Proben. Listing 4 zeigt ein Beispiel für diese Konfiguration.

Dieser Code gibt jetzt den JSON-String aus Listing 5 als Antwort zurück.

In Bild 4 ist die Antwort in Postman zu sehen. Der Health-Endpunkt gibt nun eine deutlich umfangreichere Antwort zurück. Soll die Implementierung schlanker ausfallen, lässt sich über AddCheck auch eine Lambda-Funktion angeben, die eine sehr schlanke Prüfung ohne eigene Klasse erlaubt.

Listing 4: Beispiel-Konfiguration für die Health-Check-Implementierung in einer Klasse
builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheck>(
        "Sample",
        failureStatus: HealthStatus.Degraded,
        tags: ["sample"]); 
Listing 5: JSON-Ausgabe des Health Checks
{
   "status":"Healthy",
   "results":[
      {
         "name":"Sample",
         "status":"Healthy",
         "description":"Alles in Ordnung",
         "duration":1.455
      }
   ]
} 
Erweiterte JSON-Ausgabe des Health-Endpunkts (Bild 4)

Erweiterte JSON-Ausgabe des Health-Endpunkts (Bild 4)

© Autor

Ausblick und Zwischenfazit

Dieser erste Beitrag der Serie „Health Checks in ASP.NET richtig nutzen“ hat die Grundlagen vermittelt: Warum Zustandsprüfungen wichtig sind, wie der /health-Endpunkt konfiguriert wird und wie sich eigene Prüfungen implementieren lassen.

Für Health Checks gilt es darüber hinaus zu definieren, welche Art von „Gesundheit“ überhaupt zu prüfen ist: Läuft nur der Prozess? Ist die Datenbank erreichbar? Sind alle kritischen Integrationen funktionsfähig? Diese Abgrenzung ist in produktiven Anwendungen sehr relevant und deshalb Gegenstand weiterer Teile dieser Serie, wenn es von reinen internen Checks hin zu Abhängigkeiten, Ressourcen und Kubernetes-Probes geht.

Neueste Beiträge

System-Thinking für Agenten - Projektanforderungen an Entwickler in Zeiten von KI, Teil 4
Der Agent schlug vor, die Geschäftslogik in den Controller zu verlagern. Technisch korrekt, architektonisch eine Katastrophe. Drei Szenarien zeigen, warum Architekturentscheidungen die Bastion bleiben, die Entwickler nicht delegieren können.
6 Minuten
19. Nov 2026
Enums mit Komfortfunktion - Best of NuGet, Teil 11
Enums sind in Zeiten von unbegrenztem Speicher und außerhalb des AI-Bereichs so gut wie kostenloser Rechenleistung in den Hintergrund getreten. Mit dem NuGet-Paket Enums.NET steht eine Bibliothek zur Verfügung, die dem vernachlässigten Sprachfeature verschiedenste Komfortfunktionen verleiht.
6 Minuten
16. Nov 2026
Funktionen – Wiederkehrende Logik kapseln - Infrastructure as Code mit Azure Bicep, Teil 4
Dieser Beitrag zeigt, wie benutzerdefinierte Funktionen aufgebaut sind, wie sie sich von den eingebauten Bicep-Funktionen unterscheiden und wie sich das Ergebnis einer Funktion vor dem eigentlichen Deployment überprüfen lässt.
5 Minuten

Das könnte Dich auch interessieren

Browser-Apps mit Avalonia entwickeln - Avalonia
Klassische UI-Frameworks finden ihren Weg in den Browser
5 Minuten
11. Aug 2025
Health Checks und Kubernetes - Health Checks in ASP.NET richtig nutzen, Teil 4
In Kubernetes entscheidet ein Health Check nicht nur über Sichtbarkeit im Monitoring, sondern auch darüber, ob Traffic fließt oder ein Container neu startet. Hier zeigen wir, warum saubere Grenzen zwischen Liveness und Readiness in produktiven ASP.NET-Anwendungen so wichtig sind.
4 Minuten
Datenbanken und externe Dienste - Health Checks in ASP.NET richtig nutzen, Teil 2
Erst bei Datenbanken, Caches und externen APIs zeigt sich, wie belastbar ein Health Check wirklich ist. Von einfachen Statusmeldungen ausgehend erweitern wir die Möglichkeiten bis hin zu Prüfungen, die Abhängigkeiten sichtbar machen und damit helfen, Ausfälle besser einzuordnen.
3 Minuten
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige