Kontroly stavu v ASP.NET Core

Od Glenn Condron

ASP.NET Core nabízí kontrolu stavu middlewaru a knihovny pro vytváření sestav stavu součástí infrastruktury aplikace.

Kontroly stavu jsou zpřístupněné aplikací jako koncové body HTTP. Koncové body kontroly stavu je možné nakonfigurovat pro nejrůznější scénáře monitorování v reálném čase:

  • Sondy stavu můžou použít orchestrace kontejnerů a nástroje pro vyrovnávání zatížení ke kontrole stavu aplikace. Například produkt Orchestrator může reagovat na selhání kontroly stavu zastavením zavedení nasazení nebo restartováním kontejneru. Nástroj pro vyrovnávání zatížení může reagovat na poškozenou aplikaci směrováním provozu mimo instanci selhání do stavu v pořádku.
  • Použití paměti, disku a dalších prostředků fyzického serveru se dá monitorovat v dobrém stavu.
  • Kontroly stavu můžou testovat závislosti aplikace, jako jsou databáze a externí koncové body služby, aby se potvrdila dostupnost a normální fungování.

Zobrazit nebo stáhnout ukázkový kód (Jak stáhnout)

Ukázková aplikace obsahuje příklady scénářů popsaných v tomto tématu. Pokud chcete pro daný scénář spustit ukázkovou aplikaci, použijte příkaz dotnet Run ze složky projektu v příkazovém prostředí. README.mdPodrobnosti o tom, jak používat ukázkovou aplikaci, najdete v souboru ukázkové aplikace a v popisech scénářů v tomto tématu.

Požadavky

Kontroly stavu se obvykle používají s externí službou monitorování nebo nástrojem Orchestrator Container Service ke kontrole stavu aplikace. Před přidáním kontrol stavu do aplikace se rozhodněte, který monitorovací systém se má použít. Monitorovací systém vyhodnotí, jaké typy kontrol stavu se mají vytvořit a jak nakonfigurovat jejich koncové body.

na Microsoft.AspNetCore.Diagnostics.HealthChecks balíček se odkazuje implicitně pro ASP.NET Core aplikace. K provedení kontrol stavu pomocí Entity Framework Core přidejte do Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore balíčku odkaz.

Ukázková aplikace poskytuje spouštěcí kód k předvedení kontrol stavu pro několik scénářů. Scénář testu databáze kontroluje stav připojení k databázi pomocí AspNetCore.Diagnostics.HealthChecks . Scénář testu DbContext zkontroluje databázi pomocí EF Core DbContext . K prozkoumání scénářů databáze se jedná o ukázkovou aplikaci:

Poznámka

AspNetCore.Diagnostics.HealthChecks není spravován nebo není podporován společností Microsoft.

Další scénář kontroly stavu ukazuje, jak filtrovat kontroly stavu na port pro správu. Ukázková aplikace vyžaduje, abyste vytvořili Properties/launchSettings.json soubor, který obsahuje adresu URL pro správu a port pro správu. Další informace naleznete v části Filter by port .

Základní sonda stavu

U mnoha aplikací je základní konfigurace sondy stavu, která oznamuje dostupnost aplikace pro zpracování požadavků (živý), ke zjištění stavu aplikace dostačující.

Základní konfigurace registruje služby kontroly stavu a volá middleware kontroly stavu, aby reagovala na koncový bod adresy URL s odpovědí na stav. Ve výchozím nastavení nejsou k otestování konkrétní závislosti nebo subsystému registrovány žádné konkrétní kontroly stavu. Aplikace se považuje za v pořádku, pokud dokáže reagovat na adresu URL koncového bodu stavu. Výchozí zapisovač odpovědí zapíše stav ( HealthStatus ) jako odpověď ve formátu prostého textu zpátky klientovi a uvede buď HealthStatus.Healthy stav, HealthStatus.Degraded nebo HealthStatus.Unhealthy .

Registrovat služby kontroly stavu AddHealthChecks v nástroji v Startup.ConfigureServices . Vytvořte koncový bod kontroly stavu voláním MapHealthChecks v Startup.Configure .

V ukázkové aplikaci je koncový bod kontroly stavu vytvořený v /health ( BasicStartup.cs ):

public class BasicStartup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddHealthChecks();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapHealthChecks("/health");
        });
    }
}

Pokud chcete spustit scénář základní konfigurace pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario basic

Ukázka Docker

Docker nabízí vestavěnou HEALTHCHECK direktivu, která se dá použít ke kontrole stavu aplikace, která používá konfiguraci základní kontroly stavu:

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

Vytvořit kontroly stavu

Kontroly stavu jsou vytvářeny implementací IHealthCheck rozhraní. CheckHealthAsyncMetoda vrátí hodnotu HealthCheckResult , která označuje stav jako Healthy , Degraded nebo Unhealthy . Výsledek je zapsán jako odpověď v podobě prostého textu s konfigurovatelným stavovým kódem (konfigurace je popsána v části Možnosti kontroly stavu ). HealthCheckResult může také vracet volitelné páry klíč-hodnota.

Následující ExampleHealthCheck Třída ukazuje rozložení kontroly stavu. Logika kontrol stavu je umístěna v CheckHealthAsync metodě. Následující příklad nastaví fiktivní proměnnou healthCheckResultHealthy na true . Pokud healthCheckResultHealthy je hodnota nastavená na false , vrátí se HealthCheckRegistration.FailureStatus stav.

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

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

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

Pokud CheckHealthAsync vyvolá výjimku během kontroly, HealthReportEntry je vrácena nová se HealthReportEntry.Status sadou FailureStatus , která je definována na, který je definován AddCheck (viz část Registrace služby pro kontrolu stavu ) a obsahuje vnitřní výjimku , která původně způsobila chybu kontroly. DescriptionJe nastavená na zprávu výjimky.

Registrovat služby kontroly stavu

ExampleHealthCheckTyp se přidá do služby kontroly stavu pomocí AddCheck Startup.ConfigureServices :

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>("example_health_check");

AddCheckPřetížení znázorněné v následujícím příkladu nastaví stav selhání ( HealthStatus ) na hodnotu ohlásit, když při kontrole stavu nahlásí chybu. Pokud je stav selhání nastavený na null (výchozí), HealthStatus.Unhealthy nahlásí se. Toto přetížení je užitečným scénářem pro autory knihoven, kde stav selhání uvedený v knihovně vynutila aplikace, když dojde k selhání kontroly stavu, pokud se při implementaci kontroly stavu splní nastavení.

Značky lze použít k filtrování kontrol stavu (popsaných dále v oddílu Filtr kontrol stavu ).

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>(
        "example_health_check",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "example" });

AddCheck lze také spustit funkci lambda. V následujícím příkladu je název kontroly stavu zadán jako Example a zaškrtávací políčka vždy vrátí dobrý stav:

services.AddHealthChecks()
    .AddCheck("Example", () =>
        HealthCheckResult.Healthy("Example is OK!"), tags: new[] { "example" });

Volání AddTypeActivatedCheck předání argumentů do implementace kontroly stavu. V následujícím příkladu TestHealthCheckWithArgs akceptuje celé číslo a řetězec, který se použije při CheckHealthAsync volání:

private class TestHealthCheckWithArgs : IHealthCheck
{
    public TestHealthCheckWithArgs(int i, string s)
    {
        I = i;
        S = s;
    }

    public int I { get; set; }

    public string S { get; set; }

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

TestHealthCheckWithArgs je zaregistrován voláním AddTypeActivatedCheck s celým číslem a řetězcem předaným implementaci:

services.AddHealthChecks()
    .AddTypeActivatedCheck<TestHealthCheckWithArgs>(
        "test", 
        failureStatus: HealthStatus.Degraded, 
        tags: new[] { "example" }, 
        args: new object[] { 5, "string" });

Použití směrování kontrol stavu

V Startup.Configure nástroji zavolejte MapHealthChecks na tvůrce koncového bodu s adresou URL koncového bodu nebo relativní cestou:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
});

Vyžadovat hostitele

Zavolejte RequireHost k zadání jednoho nebo více povolených hostitelů pro koncový bod kontroly stavu. Hostitelé by měli být místo punycodei Unicode a můžou zahrnovat port. Pokud není zadaná kolekce, bude přijat libovolný hostitel.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireHost("www.contoso.com:5001");
});

Další informace naleznete v části Filter by port .

Vyžadovat autorizaci

Voláním RequireAuthorization pro spuštění autorizačního middleware na koncovém bodu žádosti o kontrolu stavu. RequireAuthorizationPřetížení přijímá jednu nebo více autorizačních zásad. Pokud zásada není zadaná, použije se výchozí zásada autorizace.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireAuthorization();
});

Povolení žádostí nepůvodního zdroje (CORS)

I když ruční provádění kontrol stavu z prohlížeče není běžným scénářem použití, je možné middleware CORS povolit voláním RequireCors na koncové body kontrol stavu. RequireCorsPřetížení přijímá delegáta tvůrců zásad CORS ( CorsPolicyBuilder ) nebo název zásady. Pokud zásada není zadaná, použije se výchozí zásada CORS. Další informace naleznete v tématu Povolit žádosti mezi zdroji (CORS) v ASP.NET Core.

Možnosti kontroly stavu

HealthCheckOptions Poskytněte možnost přizpůsobení chování kontroly stavu:

Filtrovat kontroly stavu

Ve výchozím nastavení middleware pro kontrolu stavu spouští všechny zaregistrované kontroly stavu. Chcete-li spustit podmnožinu kontrol stavu, zadejte funkci, která vrací logickou hodnotu pro Predicate možnost. V následujícím příkladu Bar je kontrole stavu Filtrováno podle značky ( bar_tag ) v podmíněném příkazu funkce, kde true je vrácena pouze v případě, že Tags odpovídá vlastnost kontroly stavu foo_tag nebo baz_tag :

V Startup.ConfigureServices:

services.AddHealthChecks()
    .AddCheck("Foo", () =>
        HealthCheckResult.Healthy("Foo is OK!"), tags: new[] { "foo_tag" })
    .AddCheck("Bar", () =>
        HealthCheckResult.Unhealthy("Bar is unhealthy!"), tags: new[] { "bar_tag" })
    .AddCheck("Baz", () =>
        HealthCheckResult.Healthy("Baz is OK!"), tags: new[] { "baz_tag" });

V nástroji Startup.Configure Predicate odfiltruje kontrolu stavu pruhů. Pouze foo a Baz Execute:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("foo_tag") ||
            check.Tags.Contains("baz_tag")
    });
});

Přizpůsobení stavového kódu HTTP

Slouží ResultStatusCodes k přizpůsobení mapování stavu na stavové kódy HTTP. Následující StatusCodes přiřazení jsou výchozí hodnoty používané middlewarem. Změňte hodnoty stavového kódu tak, aby splňovaly vaše požadavky.

V Startup.Configure:

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

Potlačení hlaviček mezipaměti

AllowCachingResponses určuje, jestli middleware kontroly stavu přidá hlavičky HTTP do odpovědi sondy, aby se zabránilo ukládání odpovědí do mezipaměti. Pokud je hodnota (výchozí), middleware nastaví nebo přepíše hlavičky , a , aby se zabránilo false Cache-Control ukládání odpovědí do Expires Pragma mezipaměti. Pokud je hodnota true , middleware neupraví hlavičky mezipaměti odpovědi.

V Startup.Configure:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        AllowCachingResponses = false
    });
});

Přizpůsobení výstupu

V Startup.Configure nastavte HealthCheckOptions.ResponseWriter možnost delegáta pro zápis odpovědi:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResponseWriter = WriteResponse
    });
});

Výchozí delegát zapíše minimální odpověď ve formátu prostého textu s řetězcovou hodnotou HealthReport.Status . Následující vlastní delegáti vystupuje jako výstup vlastní odpovědi JSON.

První příklad z ukázkové aplikace ukazuje, jak použít System.Text.Json :

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

    var options = new JsonWriterOptions
    {
        Indented = true
    };

    using (var stream = new MemoryStream())
    {
        using (var writer = new Utf8JsonWriter(stream, options))
        {
            writer.WriteStartObject();
            writer.WriteString("status", result.Status.ToString());
            writer.WriteStartObject("results");
            foreach (var entry in result.Entries)
            {
                writer.WriteStartObject(entry.Key);
                writer.WriteString("status", entry.Value.Status.ToString());
                writer.WriteString("description", entry.Value.Description);
                writer.WriteStartObject("data");
                foreach (var item in entry.Value.Data)
                {
                    writer.WritePropertyName(item.Key);
                    JsonSerializer.Serialize(
                        writer, item.Value, item.Value?.GetType() ?? 
                        typeof(object));
                }
                writer.WriteEndObject();
                writer.WriteEndObject();
            }
            writer.WriteEndObject();
            writer.WriteEndObject();
        }

        var json = Encoding.UTF8.GetString(stream.ToArray());

        return context.Response.WriteAsync(json);
    }
}

Druhý příklad ukazuje, jak použít Newtonsoft.Json :

private static Task WriteResponse(HttpContext context, HealthReport result)
{
    context.Response.ContentType = "application/json";

    var json = new JObject(
        new JProperty("status", result.Status.ToString()),
        new JProperty("results", new JObject(result.Entries.Select(pair =>
            new JProperty(pair.Key, new JObject(
                new JProperty("status", pair.Value.Status.ToString()),
                new JProperty("description", pair.Value.Description),
                new JProperty("data", new JObject(pair.Value.Data.Select(
                    p => new JProperty(p.Key, p.Value))))))))));

    return context.Response.WriteAsync(
        json.ToString(Formatting.Indented));
}

V ukázkové aplikaci zakomentování SYSTEM_TEXT_JSON direktivy preprocesoru v souboru CustomWriterStartup.cs Newtonsoft.Json povolte verzi WriteResponse .

Rozhraní API pro kontroly stavu neposkytuje integrovanou podporu složitých návratových formátů JSON, protože formát je specifický pro váš výběr monitorovacího systému. Podle potřeby přizpůsobte odpověď v předchozích příkladech. Další informace o serializaci JSON pomocí najdete v tématu Jak serializovat a System.Text.Json deserializovat JSON v rozhraní .NET.

Test databáze

Kontrola stavu může určit databázový dotaz, který se má spustit jako logický test, který bude indikovat, jestli databáze normálně reaguje.

Ukázková aplikace používá knihovnu kontroly stavu pro ASP.NET Core aplikací k provedení kontroly stavu u AspNetCore.Diagnostics.HealthChecks SQL Server databáze. AspNetCore.Diagnostics.HealthChecks provede dotaz na databázi a potvrdí, že je připojení SELECT 1 k databázi v pořádku.

Upozornění

Při kontrole připojení k databázi pomocí dotazu zvolte dotaz, který se vrátí rychle. Přístup k dotazům riskuje přetížení databáze a snížení jejího výkonu. Ve většině případů není spuštění testovacího dotazu nezbytné. Pouhé vytvoření úspěšného připojení k databázi je dostačující. Pokud zjistíte, že je nutné spustit dotaz, zvolte jednoduchý dotaz SELECT, například SELECT 1 .

Zahrnout odkaz na balíček na AspNetCore.HealthChecks.SqlServer .

Do souboru ukázkové aplikace zadejte platný připojovací appsettings.json řetězec databáze. Aplikace používá databázi SQL Server s názvem HealthCheckSample :

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\MSSQLLocalDB;Database=HealthCheckSample;Trusted_Connection=True;MultipleActiveResultSets=true;ConnectRetryCount=0"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    },
    "Console": {
      "IncludeScopes": "true"
    }
  },
  "AllowedHosts": "*"
}

Zaregistrujte služby kontroly stavu pomocí AddHealthChecks v Startup.ConfigureServices . Ukázková aplikace volá AddSqlServer metodu s připojovacím řetězcem databáze ( DbHealthStartup.cs ):

services.AddHealthChecks()
    .AddSqlServer(Configuration["ConnectionStrings:DefaultConnection"]);

Koncový bod kontroly stavu se vytvoří voláním v MapHealthChecks Startup.Configure :

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
}

Pokud chcete spustit scénář sondy databáze pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario db

Poznámka

AspNetCore.Diagnostics.HealthChecks není udržováno ani podporováno společností Microsoft.

Entity Framework Core dbContext

Kontrola DbContext potvrzuje, že aplikace může komunikovat s databází nakonfigurovanou pro EF Core DbContext . Kontrola DbContext se podporuje v aplikacích, které:

AddDbContextCheck<TContext> zaregistruje kontrolu stavu pro DbContext . se DbContext dodá TContext jako pro metodu . Přetížení je k dispozici ke konfiguraci stavu selhání, značek a vlastního testovacího dotazu.

Ve výchozím nastavení:

  • Volání DbContextHealthCheck EF Core metody CanConnectAsync . To, jaká operace se spustí, můžete přizpůsobit při kontrole stavu pomocí AddDbContextCheck přetížení metody.
  • Název kontroly stavu je název TContext typu.

V ukázkové aplikaci se AppDbContext služba poskytuje a AddDbContextCheck zaregistrovaná jako služba v ( Startup.ConfigureServices DbContextHealthStartup.cs ):

services.AddHealthChecks()
    .AddDbContextCheck<AppDbContext>();

services.AddDbContext<AppDbContext>(options =>
{
    options.UseSqlServer(
        Configuration["ConnectionStrings:DefaultConnection"]);
});

Koncový bod kontroly stavu se vytvoří voláním v MapHealthChecks Startup.Configure :

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
}

Pokud chcete spustit DbContext scénář testu pomocí ukázkové aplikace, ověřte, že databáze zadaná připojovacím řetězcem v instanci SQL Server databáze. Pokud databáze existuje, odstraňte ji.

V příkazovém prostředí spusťte ze složky projektu následující příkaz:

dotnet run --scenario dbcontext

Po spuštění aplikace zkontrolujte stav vytvořením požadavku na koncový /health bod v prohlížeči. Databáze a AppDbContext neexistují, takže aplikace poskytuje následující odpověď:

Unhealthy

Aktivujte ukázkovou aplikaci a vytvořte databázi. Vytvořte požadavek na /createdatabase . Aplikace odpoví:

Creating the database...
Done!
Navigate to /health to see the health status.

Vytvořte požadavek na koncový /health bod. Databáze a kontext existují, takže aplikace reaguje:

Healthy

Aktivujte ukázkovou aplikaci, která databázi odstraní. Vytvořte požadavek na /deletedatabase . Aplikace odpoví:

Deleting the database...
Done!
Navigate to /health to see the health status.

Vytvořte požadavek na koncový /health bod. Aplikace poskytne odpověď, která není v pořádku:

Unhealthy

Samostatné testy připravenosti a živého stavu

V některých scénářích hostování se používá dvojice kontrol stavu, které rozlišují dva stavy aplikací:

  • Připravenost značí, jestli aplikace běží normálně, ale není připravená přijímat požadavky.
  • Živá hodnota značí, jestli aplikace havaruje a je nutné ji restartovat.

Představte si následující příklad: Aplikace musí před zpracováním požadavků stáhnout velký konfigurační soubor. Nechceme, aby se aplikace restartoval, pokud počáteční stažení selže, protože aplikace může soubor několikrát znovu stáhnout. Sonda aktivity používáme k popisu aktivity procesu, žádné další kontroly se nesníží. Chceme také zabránit odeslání požadavků do aplikace před úspěšným stažením konfiguračního souboru. Sondu připravenosti používáme k označení nepřipravenosti stavu, dokud stahování neprovede a aplikace nebude připravená přijímat požadavky.

Ukázková aplikace obsahuje kontrolu stavu, která hlásí dokončení dlouhotrvá spouštěcí úlohy v hostované službě. Objekt zpřístupňuje vlastnost , na kterou může hostovaná služba nastavit po dokončení dlouhotr běžící StartupHostedServiceHealthCheck StartupTaskCompleted úlohy ( true StartupHostedServiceHealthCheck.cs ):

public class StartupHostedServiceHealthCheck : IHealthCheck
{
    private volatile bool _startupTaskCompleted = false;

    public string Name => "slow_dependency_check";

    public bool StartupTaskCompleted
    {
        get => _startupTaskCompleted;
        set => _startupTaskCompleted = value;
    }

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

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

Dlouhotrvá úloha na pozadí je spuštěna hostovanou službou ( Services/StartupHostedService ). Na závěr úlohy je StartupHostedServiceHealthCheck.StartupTaskCompleted nastavena na true :

public class StartupHostedService : IHostedService, IDisposable
{
    private readonly int _delaySeconds = 15;
    private readonly ILogger _logger;
    private readonly StartupHostedServiceHealthCheck _startupHostedServiceHealthCheck;

    public StartupHostedService(ILogger<StartupHostedService> logger, 
        StartupHostedServiceHealthCheck startupHostedServiceHealthCheck)
    {
        _logger = logger;
        _startupHostedServiceHealthCheck = startupHostedServiceHealthCheck;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("Startup Background Service is starting.");

        // Simulate the effect of a long-running startup task.
        Task.Run(async () =>
        {
            await Task.Delay(_delaySeconds * 1000);

            _startupHostedServiceHealthCheck.StartupTaskCompleted = true;

            _logger.LogInformation("Startup Background Service has started.");
        });

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("Startup Background Service is stopping.");

        return Task.CompletedTask;
    }

    public void Dispose()
    {
    }
}

Kontrola stavu je zaregistrovaná v AddCheck spolu Startup.ConfigureServices s hostovanou službou. Vzhledem k tomu, že hostovaná služba musí nastavit vlastnost kontroly stavu, je kontrola stavu zaregistrovaná také v kontejneru služby ( LivenessProbeStartup.cs ):

services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();

services.AddHealthChecks()
    .AddCheck<StartupHostedServiceHealthCheck>(
        "hosted_service_startup", 
        failureStatus: HealthStatus.Degraded, 
        tags: new[] { "ready" });

services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = (check) => check.Tags.Contains("ready");
});

services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();

Koncový bod kontroly stavu se vytvoří voláním v MapHealthChecks Startup.Configure . V ukázkové aplikaci se koncové body kontroly stavu vytvářejí na adrese:

  • /health/ready pro kontrolu připravenosti. Kontrola připravenosti filtruje kontroly stavu na kontrolu stavu se ready značkou .
  • /health/live pro kontrolu živého přenosu. Kontrola aktivity filtruje hodnotu tak, že se vrátí v části (další informace StartupHostedServiceHealthCheck najdete v tématu Kontrola stavu false HealthCheckOptions.Predicate filtru).

V následujícím příkladu kódu:

  • Kontrola připravenosti používá všechny zaregistrované kontroly se značkou Ready.
  • PredicateVyloučí všechny kontroly a vrátí 200-Ok.
app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("ready"),
    });

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

Pokud chcete scénář konfigurace připravenosti/aktivity spustit pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario liveness

V prohlížeči několikrát navštivte /health/ready stránku, dokud neuplyly 15 sekund. Kontrola stavu se hlásí Unhealthy prvních 15 sekund. Po 15 sekundách koncový bod hlásí , který odráží dokončení Healthy dlouhotrvá úlohy hostovanou službou.

V tomto příkladu se také vytvoří Publisher stavu (implementace), která spustí první kontrolu připravenosti IHealthCheckPublisher se dvěmasekudovou prodlevou. Další informace najdete v části Kontrola Publisher stavu.

Příklad Kubernetes

Použití samostatných kontrol připravenosti a aktivity je užitečné v prostředí, jako je Kubernetes. V Kubernetes může být nutné, aby aplikace před přijetím požadavků časově náročně pracovala na spuštění, například test dostupnosti podkladové databáze. Použití samostatných kontrol umožňuje orchestrátoru rozlišit, jestli aplikace funguje, ale ještě není připravená, nebo jestli se aplikaci nepodařilo spustit. Další informace o testech připravenosti a aktivity v Kubernetes najdete v tématu Konfigurace sond aktivity a připravenosti v dokumentaci ke Kubernetes.

Následující příklad ukazuje konfiguraci sondy připravenosti Kubernetes:

spec:
  template:
  spec:
    readinessProbe:
      # an http probe
      httpGet:
        path: /health/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

Sonda založená na metrikách s vlastním zapisovačem odpovědí

Ukázková aplikace předvede kontrolu stavu paměti pomocí vlastního zapisovače odpovědí.

MemoryHealthCheck hlásí snížený výkon, pokud aplikace používá více než danou prahovou hodnotu paměti (1 GB v ukázkové aplikaci). HealthCheckResultZahrnuje informace o uvolňování paměti (GC) pro aplikaci ( MemoryHealthCheck.cs ):

public class MemoryHealthCheck : IHealthCheck
{
    private readonly IOptionsMonitor<MemoryCheckOptions> _options;

    public MemoryHealthCheck(IOptionsMonitor<MemoryCheckOptions> options)
    {
        _options = options;
    }

    public string Name => "memory_check";

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, 
        CancellationToken cancellationToken = default(CancellationToken))
    {
        var options = _options.Get(context.Registration.Name);

        // Include GC information in the reported diagnostics.
        var allocated = GC.GetTotalMemory(forceFullCollection: false);
        var data = new Dictionary<string, object>()
        {
            { "AllocatedBytes", allocated },
            { "Gen0Collections", GC.CollectionCount(0) },
            { "Gen1Collections", GC.CollectionCount(1) },
            { "Gen2Collections", GC.CollectionCount(2) },
        };
        var status = (allocated < options.Threshold) ? 
            HealthStatus.Healthy : context.Registration.FailureStatus;

        return Task.FromResult(new HealthCheckResult(
            status,
            description: "Reports degraded status if allocated bytes " +
                $">= {options.Threshold} bytes.",
            exception: null,
            data: data));
    }
}

Registrovat služby kontroly stavu AddHealthChecks v nástroji v Startup.ConfigureServices . Místo povolení kontroly stavu předáním AddCheck MemoryHealthCheck jako služby je zaregistrována jako služba. Všechny IHealthCheck registrované služby jsou k dispozici pro služby kontroly stavu a middleware. Službu pro kontrolu stavu doporučujeme zaregistrovat jako služby typu singleton.

V CustomWriterStartup.cs ukázkové aplikaci:

services.AddHealthChecks()
    .AddMemoryHealthCheck("memory");

Koncový bod kontroly stavu je vytvořen voláním MapHealthChecks v Startup.Configure . WriteResponseDelegát je k dispozici pro ResponseWriter pro výstup vlastní odpovědi JSON, když se spustí kontroly stavu:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResponseWriter = WriteResponse
    });
}

WriteResponseDelegát naformátuje CompositeHealthCheckResult objekt do objektu JSON a pro odpověď na kontrolu stavu vrátí výstup JSON. Další informace najdete v části přizpůsobení výstupu .

Pokud chcete spustit test založený na metrikách s vlastním výstupem zapisovače odpovědí pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario writer

Poznámka

AspNetCore.Diagnostics.HealthChecks zahrnuje scénáře kontroly stavu založené na metrikách, včetně diskového úložiště a maximálního počtu kontrol živých hodnot.

AspNetCore.Diagnostics.HealthChecks není spravován nebo není podporován společností Microsoft.

Filtrovat podle portu

Zavolejte RequireHost MapHealthChecks pomocí vzoru adresy URL, který určuje port pro omezení požadavků na kontrolu stavu na zadaný port. Obvykle se používá v prostředí kontejneru k vystavení portu pro monitorovací služby.

Ukázková aplikace nakonfiguruje port pomocí poskytovatele konfigurace proměnné prostředí. Port je nastaven v launchSettings.json souboru a předán poskytovateli konfigurace prostřednictvím proměnné prostředí. Také je nutné nakonfigurovat server tak, aby naslouchal žádosti na portu pro správu.

Pokud chcete ukázkovou aplikaci použít k předvedení konfigurace portů pro správu, vytvořte launchSettings.json soubor ve Properties složce.

Následující Properties/launchSettings.json soubor v ukázkové aplikaci není zahrnutý v souborech projektu ukázkové aplikace a musí se vytvořit ručně:

{
  "profiles": {
    "SampleApp": {
      "commandName": "Project",
      "commandLineArgs": "",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "ASPNETCORE_URLS": "http://localhost:5000/;http://localhost:5001/",
        "ASPNETCORE_MANAGEMENTPORT": "5001"
      },
      "applicationUrl": "http://localhost:5000/"
    }
  }
}

Registrovat služby kontroly stavu AddHealthChecks v nástroji v Startup.ConfigureServices . Vytvořte koncový bod kontroly stavu voláním MapHealthChecks v Startup.Configure .

V ukázkové aplikaci volání RequireHost na koncový bod v Startup.Configure Určuje port pro správu z konfigurace:

endpoints.MapHealthChecks("/health")
    .RequireHost($"*:{Configuration["ManagementPort"]}");

Koncové body se vytvoří v ukázkové aplikaci v Startup.Configure . V následujícím příkladu kódu:

  • Kontrola připravenosti používá všechny registrované kontroly se značkou ' Read '.
  • PredicateVyloučí všechny kontroly a vrátí 200 – OK.
app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("ready"),
    });

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

Poznámka

Vytvoření launchSettings.json souboru v ukázkové aplikaci se vyhnete nastavením portu pro správu explicitně v kódu. V Program.cs místě HostBuilder , kde je vytvořena, přidejte volání do ListenAnyIP a poskytněte koncový bod portu pro správu aplikace. V Configure nástroji ManagementPortStartup.cs Zadejte port pro správu s RequireHost :

Program.cs:

return new HostBuilder()
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseKestrel()
            .ConfigureKestrel(serverOptions =>
            {
                serverOptions.ListenAnyIP(5001);
            })
            .UseStartup(startupType);
    })
    .Build();

ManagementPortStartup.cs:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireHost("*:5001");
});

Pokud chcete spustit scénář konfigurace portu pro správu pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario port

Distribuce knihovny kontroly stavu

Postup při distribuci kontroly stavu jako knihovny:

  1. Zapište kontrolu stavu, která implementuje IHealthCheck rozhraní jako samostatnou třídu. Třída může spoléhat na vkládání závislostí (di), aktivovat typ a pojmenované možnosti pro přístup k datům konfigurace.

    V logice kontroly stavu pro CheckHealthAsync :

    • data1 a data2 jsou použity v metodě pro spuštění logiky kontroly stavu testu.
    • AccessViolationException je zpracována.

    V případě AccessViolationException , že dojde k chybě, se FailureStatus vrátí s a HealthCheckResult umožní uživatelům konfigurovat stav selhání kontroly stavu.

    using System;
    using System.Threading;
    using System.Threading.Tasks;
    using Microsoft.Extensions.Diagnostics.HealthChecks;
    
    namespace SampleApp
    {
        public class ExampleHealthCheck : IHealthCheck
        {
            private readonly string _data1;
            private readonly int? _data2;
    
            public ExampleHealthCheck(string data1, int? data2)
            {
                _data1 = data1 ?? throw new ArgumentNullException(nameof(data1));
                _data2 = data2 ?? throw new ArgumentNullException(nameof(data2));
            }
    
            public async Task<HealthCheckResult> CheckHealthAsync(
                HealthCheckContext context, CancellationToken cancellationToken)
            {
                try
                {
                    return HealthCheckResult.Healthy();
                }
                catch (AccessViolationException ex)
                {
                    return new HealthCheckResult(
                        context.Registration.FailureStatus,
                        description: "An access violation occurred during the check.",
                        exception: ex,
                        data: null);
                }
            }
        }
    }
    
  2. Zapište metodu rozšíření s parametry, které aplikace spotřebovávají ve své Startup.Configure metodě. V následujícím příkladu předpokládejme následující signatura metody kontroly stavu:

    ExampleHealthCheck(string, string, int )
    

    Předchozí signatura indikuje, že ExampleHealthCheck pro zpracování logiky sondy kontroly stavu vyžaduje další data. Data jsou k dispozici delegátovi použitému k vytvoření instance kontroly stavu při registraci kontroly stavu s metodou rozšíření. V následujícím příkladu volající určuje nepovinné:

    • název kontroly stavu ( name ). Pokud null se example_health_check používá.
    • datový bod řetězce pro kontrolu stavu ( data1 ).
    • celočíselný datový bod pro kontrolu stavu ( data2 ). Pokud null se 1 používá.
    • stav selhání ( HealthStatus ). Výchozí formát je null. V případě null , že HealthStatus.Unhealthy je hlášen stav selhání.
    • značky ( IEnumerable<string> ).
    using System.Collections.Generic;
    using Microsoft.Extensions.Diagnostics.HealthChecks;
    
    public static class ExampleHealthCheckBuilderExtensions
    {
        const string DefaultName = "example_health_check";
    
        public static IHealthChecksBuilder AddExampleHealthCheck(
            this IHealthChecksBuilder builder,
            string name = default,
            string data1,
            int data2 = 1,
            HealthStatus? failureStatus = default,
            IEnumerable<string> tags = default)
        {
            return builder.Add(new HealthCheckRegistration(
                name ?? DefaultName,
                sp => new ExampleHealthCheck(data1, data2),
                failureStatus,
                tags));
        }
    }
    

Publisher kontroly stavu

Když IHealthCheckPublisher se přidá do kontejneru služby, systém kontroly stavu pravidelně spouští kontroly stavu a volání PublishAsync s výsledkem. To je užitečné ve scénáři sledování stavu založeném na nabízených oznámeních, který očekává, že každý proces bude pravidelně volat monitorovací systém, aby se zjistil stav.

IHealthCheckPublisherRozhraní má jedinou metodu:

Task PublishAsync(HealthReport report, CancellationToken cancellationToken);

HealthCheckPublisherOptions umožňuje nastavit:

  • Delay: Počáteční zpoždění použité po spuštění aplikace před spuštěním IHealthCheckPublisher instancí. Zpoždění se použije jednou při spuštění a nevztahuje se na další iterace. Výchozí hodnota je pět sekund.
  • Period: Období IHealthCheckPublisher provádění. Výchozí hodnota je 30 sekund.
  • Predicate: Pokud Predicate je null (výchozí), služba Vydavatel kontroly stavu spustí všechny zaregistrované kontroly stavu. Chcete-li spustit podmnožinu kontrol stavu, zadejte funkci, která filtruje sadu kontrol. Predikát je vyhodnocen každou periodu.
  • Timeout: Časový limit pro spuštění kontrol stavu pro všechny IHealthCheckPublisher instance. Použijte InfiniteTimeSpan k provedení bez časového limitu. Výchozí hodnota je 30 sekund.

V ukázkové aplikaci ReadinessPublisher je IHealthCheckPublisher implementace. Stav kontroly stavu se protokoluje pro každou kontrolu na úrovni protokolu:

public class ReadinessPublisher : IHealthCheckPublisher
{
    private readonly ILogger _logger;

    public ReadinessPublisher(ILogger<ReadinessPublisher> logger)
    {
        _logger = logger;
    }

    // The following example is for demonstration purposes only. Health Checks 
    // Middleware already logs health checks results. A real-world readiness 
    // check in a production app might perform a set of more expensive or 
    // time-consuming checks to determine if other resources are responding 
    // properly.
    public Task PublishAsync(HealthReport report, 
        CancellationToken cancellationToken)
    {
        if (report.Status == HealthStatus.Healthy)
        {
            _logger.LogInformation("{Timestamp} Readiness Probe Status: {Result}", 
                DateTime.UtcNow, report.Status);
        }
        else
        {
            _logger.LogError("{Timestamp} Readiness Probe Status: {Result}", 
                DateTime.UtcNow, report.Status);
        }

        cancellationToken.ThrowIfCancellationRequested();

        return Task.CompletedTask;
    }
}

V příkladu ukázkové aplikace LivenessProbeStartup StartupHostedService má kontroler připravenosti dvě sekundy na spuštění a spustí kontrolu každých 30 sekund. Chcete-li aktivovat IHealthCheckPublisher implementaci, ukázka se registruje ReadinessPublisher jako služba s jedním prvkem v kontejneru Injektáže (di) pro vkládání závislostí :

services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();

services.AddHealthChecks()
    .AddCheck<StartupHostedServiceHealthCheck>(
        "hosted_service_startup", 
        failureStatus: HealthStatus.Degraded, 
        tags: new[] { "ready" });

services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = (check) => check.Tags.Contains("ready");
});

services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();

Poznámka

AspNetCore.Diagnostics.HealthCheckszahrnuje vydavatele pro několik systémů, včetně Application Insights.

AspNetCore.Diagnostics.HealthChecks není spravován nebo není podporován společností Microsoft.

Omezení kontrol stavu pomocí MapWhen

Použijte MapWhen k podmíněně větvení kanálu žádostí pro koncové body kontroly stavu.

V následujícím příkladu MapWhen větví kanál žádosti o aktivaci middlewaru pro kontrolu stavu, pokud se pro koncový bod přijme požadavek Get api/HealthCheck :

app.MapWhen(
    context => context.Request.Method == HttpMethod.Get.Method && 
        context.Request.Path.StartsWith("/api/HealthCheck"),
    builder => builder.UseHealthChecks());

app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
});

Další informace naleznete v tématu ASP.NET Core Jiné.

ASP.NET Core nabízí kontrolu stavu middlewaru a knihovny pro vytváření sestav stavu součástí infrastruktury aplikace.

Kontroly stavu jsou zpřístupněné aplikací jako koncové body HTTP. Koncové body kontroly stavu je možné nakonfigurovat pro nejrůznější scénáře monitorování v reálném čase:

  • Sondy stavu můžou použít orchestrace kontejnerů a nástroje pro vyrovnávání zatížení ke kontrole stavu aplikace. Například produkt Orchestrator může reagovat na selhání kontroly stavu zastavením zavedení nasazení nebo restartováním kontejneru. Nástroj pro vyrovnávání zatížení může reagovat na poškozenou aplikaci směrováním provozu mimo instanci selhání do stavu v pořádku.
  • Použití paměti, disku a dalších prostředků fyzického serveru se dá monitorovat v dobrém stavu.
  • Kontroly stavu můžou testovat závislosti aplikace, jako jsou databáze a externí koncové body služby, aby se potvrdila dostupnost a normální fungování.

Zobrazit nebo stáhnout ukázkový kód (Jak stáhnout)

Ukázková aplikace obsahuje příklady scénářů popsaných v tomto tématu. Pokud chcete pro daný scénář spustit ukázkovou aplikaci, použijte příkaz dotnet Run ze složky projektu v příkazovém prostředí. README.mdPodrobnosti o tom, jak používat ukázkovou aplikaci, najdete v souboru ukázkové aplikace a v popisech scénářů v tomto tématu.

Požadavky

Kontroly stavu se obvykle používají s externí službou monitorování nebo nástrojem Orchestrator Container Service ke kontrole stavu aplikace. Před přidáním kontrol stavu do aplikace se rozhodněte, který monitorovací systém se má použít. Monitorovací systém vyhodnotí, jaké typy kontrol stavu se mají vytvořit a jak nakonfigurovat jejich koncové body.

na Microsoft.AspNetCore.Diagnostics.HealthChecks balíček se odkazuje implicitně pro ASP.NET Core aplikace. K provedení kontrol stavu pomocí Entity Framework Core přidejte do balíčku odkaz na balíček Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore .

Ukázková aplikace poskytuje spouštěcí kód k předvedení kontrol stavu pro několik scénářů. Scénář testu databáze kontroluje stav připojení k databázi pomocí AspNetCore.Diagnostics.HealthChecks . Scénář testu DbContext zkontroluje databázi pomocí EF Core DbContext . K prozkoumání scénářů databáze se jedná o ukázkovou aplikaci:

Poznámka

AspNetCore.Diagnostics.HealthChecks není spravován nebo není podporován společností Microsoft.

Další scénář kontroly stavu ukazuje, jak filtrovat kontroly stavu na port pro správu. Ukázková aplikace vyžaduje, abyste vytvořili Properties/launchSettings.json soubor, který obsahuje adresu URL pro správu a port pro správu. Další informace naleznete v části Filter by port .

Základní sonda stavu

U mnoha aplikací je základní konfigurace sondy stavu, která oznamuje dostupnost aplikace pro zpracování požadavků (živý), ke zjištění stavu aplikace dostačující.

Základní konfigurace registruje služby kontroly stavu a volá middleware kontroly stavu, aby reagovala na koncový bod adresy URL s odpovědí na stav. Ve výchozím nastavení nejsou k otestování konkrétní závislosti nebo subsystému registrovány žádné konkrétní kontroly stavu. Aplikace se považuje za v pořádku, pokud dokáže reagovat na adresu URL koncového bodu stavu. Výchozí zapisovač odpovědí zapíše stav ( HealthStatus ) jako odpověď ve formátu prostého textu zpátky klientovi a uvede buď HealthStatus.Healthy stav, HealthStatus.Degraded nebo HealthStatus.Unhealthy .

Registrovat služby kontroly stavu AddHealthChecks v nástroji v Startup.ConfigureServices . Vytvořte koncový bod kontroly stavu voláním MapHealthChecks v Startup.Configure .

V ukázkové aplikaci je koncový bod kontroly stavu vytvořený v /health ( BasicStartup.cs ):

public class BasicStartup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddHealthChecks();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseRouting();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapHealthChecks("/health");
        });
    }
}

Pokud chcete spustit scénář základní konfigurace pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario basic

Ukázka Docker

Docker nabízí vestavěnou HEALTHCHECK direktivu, která se dá použít ke kontrole stavu aplikace, která používá konfiguraci základní kontroly stavu:

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

Vytvořit kontroly stavu

Kontroly stavu jsou vytvářeny implementací IHealthCheck rozhraní. CheckHealthAsyncMetoda vrátí hodnotu HealthCheckResult , která označuje stav jako Healthy , Degraded nebo Unhealthy . Výsledek je zapsán jako odpověď v podobě prostého textu s konfigurovatelným stavovým kódem (konfigurace je popsána v části Možnosti kontroly stavu ). HealthCheckResult může také vracet volitelné páry klíč-hodnota.

Následující ExampleHealthCheck Třída ukazuje rozložení kontroly stavu. Logika kontrol stavu je umístěna v CheckHealthAsync metodě. Následující příklad nastaví fiktivní proměnnou healthCheckResultHealthy na true . Pokud healthCheckResultHealthy je hodnota nastavená na false , vrátí se HealthCheckResult.Unhealthy stav.

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

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

        return Task.FromResult(
            HealthCheckResult.Unhealthy("An unhealthy result."));
    }
}

Registrovat služby kontroly stavu

ExampleHealthCheckTyp se přidá do služby kontroly stavu pomocí AddCheck Startup.ConfigureServices :

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>("example_health_check");

AddCheckPřetížení znázorněné v následujícím příkladu nastaví stav selhání ( HealthStatus ) na hodnotu ohlásit, když při kontrole stavu nahlásí chybu. Pokud je stav selhání nastavený na null (výchozí), HealthStatus.Unhealthy nahlásí se. Toto přetížení je užitečným scénářem pro autory knihoven, kde stav selhání uvedený v knihovně vynutila aplikace, když dojde k selhání kontroly stavu, pokud se při implementaci kontroly stavu splní nastavení.

Značky lze použít k filtrování kontrol stavu (popsaných dále v oddílu Filtr kontrol stavu ).

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>(
        "example_health_check",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "example" });

AddCheck lze také spustit funkci lambda. V následujícím příkladu je název kontroly stavu zadán jako Example a zaškrtávací políčka vždy vrátí dobrý stav:

services.AddHealthChecks()
    .AddCheck("Example", () =>
        HealthCheckResult.Healthy("Example is OK!"), tags: new[] { "example" });

Volání AddTypeActivatedCheck předání argumentů do implementace kontroly stavu. V následujícím příkladu TestHealthCheckWithArgs akceptuje celé číslo a řetězec, který se použije při CheckHealthAsync volání:

private class TestHealthCheckWithArgs : IHealthCheck
{
    public TestHealthCheckWithArgs(int i, string s)
    {
        I = i;
        S = s;
    }

    public int I { get; set; }

    public string S { get; set; }

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

TestHealthCheckWithArgs je zaregistrován voláním AddTypeActivatedCheck s celým číslem a řetězcem předaným implementaci:

services.AddHealthChecks()
    .AddTypeActivatedCheck<TestHealthCheckWithArgs>(
        "test", 
        failureStatus: HealthStatus.Degraded, 
        tags: new[] { "example" }, 
        args: new object[] { 5, "string" });

Použití směrování kontrol stavu

V Startup.Configure nástroji zavolejte MapHealthChecks na tvůrce koncového bodu s adresou URL koncového bodu nebo relativní cestou:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
});

Vyžadovat hostitele

Zavolejte RequireHost k zadání jednoho nebo více povolených hostitelů pro koncový bod kontroly stavu. Hostitelé by měli být místo punycodei Unicode a můžou zahrnovat port. Pokud není zadaná kolekce, bude přijat libovolný hostitel.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireHost("www.contoso.com:5001");
});

Další informace naleznete v části Filter by port .

Vyžadovat autorizaci

Voláním RequireAuthorization pro spuštění autorizačního middleware na koncovém bodu žádosti o kontrolu stavu. RequireAuthorizationPřetížení přijímá jednu nebo více autorizačních zásad. Pokud zásada není zadaná, použije se výchozí zásada autorizace.

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireAuthorization();
});

Povolení žádostí nepůvodního zdroje (CORS)

I když ruční provádění kontrol stavu z prohlížeče není běžným scénářem použití, je možné middleware CORS povolit voláním RequireCors na koncové body kontrol stavu. RequireCorsPřetížení přijímá delegáta tvůrců zásad CORS ( CorsPolicyBuilder ) nebo název zásady. Pokud zásada není zadaná, použije se výchozí zásada CORS. Další informace naleznete v tématu Povolit žádosti mezi zdroji (CORS) v ASP.NET Core.

Možnosti kontroly stavu

HealthCheckOptions Poskytněte možnost přizpůsobení chování kontroly stavu:

Filtrovat kontroly stavu

Ve výchozím nastavení middleware pro kontrolu stavu spouští všechny zaregistrované kontroly stavu. Chcete-li spustit podmnožinu kontrol stavu, zadejte funkci, která vrací logickou hodnotu pro Predicate možnost. V následujícím příkladu Bar je kontrole stavu Filtrováno podle značky ( bar_tag ) v podmíněném příkazu funkce, kde true je vrácena pouze v případě, že Tags odpovídá vlastnost kontroly stavu foo_tag nebo baz_tag :

V Startup.ConfigureServices:

services.AddHealthChecks()
    .AddCheck("Foo", () =>
        HealthCheckResult.Healthy("Foo is OK!"), tags: new[] { "foo_tag" })
    .AddCheck("Bar", () =>
        HealthCheckResult.Unhealthy("Bar is unhealthy!"), tags: new[] { "bar_tag" })
    .AddCheck("Baz", () =>
        HealthCheckResult.Healthy("Baz is OK!"), tags: new[] { "baz_tag" });

V nástroji Startup.Configure Predicate odfiltruje kontrolu stavu pruhů. Pouze foo a Baz Execute:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("foo_tag") ||
            check.Tags.Contains("baz_tag")
    });
});

Přizpůsobení stavového kódu HTTP

Slouží ResultStatusCodes k přizpůsobení mapování stavu na stavové kódy HTTP. Následující StatusCodes přiřazení jsou výchozí hodnoty používané middlewarem. Změňte hodnoty stavového kódu tak, aby splňovaly vaše požadavky.

V Startup.Configure:

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

Potlačit hlavičky mezipaměti

AllowCachingResponses Určuje, zda middleware kontroluje stav přidává hlavičky protokolu HTTP do odezvy sondy, aby nedocházelo k ukládání odpovědí do mezipaměti. Pokud je hodnota false (výchozí), middleware nastaví nebo přepíše Cache-Control Expires hlavičky, a, Pragma aby nedocházelo k ukládání odpovědí do mezipaměti. Pokud je hodnota true , middleware neupraví hlavičky mezipaměti odpovědi.

V Startup.Configure:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        AllowCachingResponses = false
    });
});

Přizpůsobení výstupu

V nástroji Startup.Configure nastavte HealthCheckOptions.ResponseWriter možnost delegáta pro zápis odpovědi:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResponseWriter = WriteResponse
    });
});

Výchozí delegát zapisuje minimální odpověď ve formátu prostého textu s hodnotou řetězce HealthReport.Status . Následující vlastní Delegáti výstupují vlastní odpověď JSON.

První příklad z ukázkové aplikace ukazuje, jak používat System.Text.Json :

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

    var options = new JsonWriterOptions
    {
        Indented = true
    };

    using (var stream = new MemoryStream())
    {
        using (var writer = new Utf8JsonWriter(stream, options))
        {
            writer.WriteStartObject();
            writer.WriteString("status", result.Status.ToString());
            writer.WriteStartObject("results");
            foreach (var entry in result.Entries)
            {
                writer.WriteStartObject(entry.Key);
                writer.WriteString("status", entry.Value.Status.ToString());
                writer.WriteString("description", entry.Value.Description);
                writer.WriteStartObject("data");
                foreach (var item in entry.Value.Data)
                {
                    writer.WritePropertyName(item.Key);
                    JsonSerializer.Serialize(
                        writer, item.Value, item.Value?.GetType() ?? 
                        typeof(object));
                }
                writer.WriteEndObject();
                writer.WriteEndObject();
            }
            writer.WriteEndObject();
            writer.WriteEndObject();
        }

        var json = Encoding.UTF8.GetString(stream.ToArray());

        return context.Response.WriteAsync(json);
    }
}

Druhý příklad ukazuje, jak použít Newtonsoft.Jsna:

private static Task WriteResponse(HttpContext context, HealthReport result)
{
    context.Response.ContentType = "application/json";

    var json = new JObject(
        new JProperty("status", result.Status.ToString()),
        new JProperty("results", new JObject(result.Entries.Select(pair =>
            new JProperty(pair.Key, new JObject(
                new JProperty("status", pair.Value.Status.ToString()),
                new JProperty("description", pair.Value.Description),
                new JProperty("data", new JObject(pair.Value.Data.Select(
                    p => new JProperty(p.Key, p.Value))))))))));

    return context.Response.WriteAsync(
        json.ToString(Formatting.Indented));
}

V ukázkové aplikaci přidejte do SYSTEM_TEXT_JSON direktivy preprocesoru v nástroji, CustomWriterStartup.cs aby bylo možné povolit Newtonsoft.Json verzi WriteResponse .

Rozhraní API pro kontroly stavu neposkytuje vestavěnou podporu pro komplexní formáty vrácených hodnot JSON, protože formát je specifický pro váš výběr systému monitorování. Podle potřeby upravte odpověď v předchozích příkladech. Další informace o serializaci JSON s System.Text.Json najdete v tématu jak serializovat a deserializovat JSON v rozhraní .NET.

Test databáze

Kontrola stavu může určit databázový dotaz, který se má spustit jako logický test, aby označoval, zda databáze obvykle reaguje.

ukázková aplikace používá AspNetCore.Diagnostics.HealthChecks knihovnu kontroly stavu pro ASP.NET Core aplikací k provedení kontroly stavu databáze SQL Server. AspNetCore.Diagnostics.HealthChecks spustí SELECT 1 dotaz na databázi, aby se ověřilo, že připojení k databázi je v pořádku.

Upozornění

Při kontrole připojení k databázi pomocí dotazu vyberte dotaz, který se rychle vrátí. Přístup k dotazům spouští riziko přetížení databáze a snížení výkonu. Ve většině případů není nutné spustit testovací dotaz. Stačí pouze provést úspěšné připojení k databázi. Pokud zjistíte, že je nutné spustit dotaz, zvolte jednoduchý dotaz SELECT, například SELECT 1 .

Zahrnout odkaz na balíček do AspNetCore.HealthChecks.SqlServer .

V souboru ukázkové aplikace zadejte platný připojovací řetězec databáze appsettings.json . aplikace používá SQL Server databázi s názvem HealthCheckSample :

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\MSSQLLocalDB;Database=HealthCheckSample;Trusted_Connection=True;MultipleActiveResultSets=true;ConnectRetryCount=0"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    },
    "Console": {
      "IncludeScopes": "true"
    }
  },
  "AllowedHosts": "*"
}

Registrovat služby kontroly stavu AddHealthChecks v nástroji v Startup.ConfigureServices . Ukázková aplikace volá AddSqlServer metodu s připojovacím řetězcem databáze ( DbHealthStartup.cs ):

services.AddHealthChecks()
    .AddSqlServer(Configuration["ConnectionStrings:DefaultConnection"]);

Koncový bod kontroly stavu se vytvoří voláním MapHealthChecks v Startup.Configure :

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
}

Pokud chcete spustit scénář testu databáze pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario db

Poznámka

AspNetCore.Diagnostics.HealthChecks není spravován nebo není podporován společností Microsoft.

Test Entity Framework Core DbContext

Tato DbContext kontrolu potvrdí, že aplikace může komunikovat s databází nakonfigurovanou pro EF Core DbContext . Tato DbContext kontrolu je podporovaná v aplikacích, které:

AddDbContextCheck<TContext> zaregistruje kontrolu stavu pro DbContext . DbContextJe dodán jako TContext Metoda metodě. K dispozici je přetížení pro konfiguraci stavu selhání, značek a vlastního testovacího dotazu.

Ve výchozím nastavení:

  • DbContextHealthCheckVolá CanConnectAsync metodu EF Core. Můžete přizpůsobit, která operace je spuštěna při kontrole stavu pomocí AddDbContextCheck přetížení metod.
  • Název kontroly stavu je název TContext typu.

V ukázkové aplikaci AppDbContext je k dispozici AddDbContextCheck a zaregistrováno jako služba v Startup.ConfigureServices ( DbContextHealthStartup.cs ):

services.AddHealthChecks()
    .AddDbContextCheck<AppDbContext>();

services.AddDbContext<AppDbContext>(options =>
{
    options.UseSqlServer(
        Configuration["ConnectionStrings:DefaultConnection"]);
});

Koncový bod kontroly stavu se vytvoří voláním MapHealthChecks v Startup.Configure :

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health");
}

pokud chcete spustit DbContext scénář sondy pomocí ukázkové aplikace, zkontrolujte, že databáze určená připojovacím řetězcem v instanci SQL Server neexistuje. Pokud databáze existuje, odstraňte ji.

Ze složky projektu v příkazovém prostředí spusťte následující příkaz:

dotnet run --scenario dbcontext

Po spuštění aplikace ověřte stav tak, že v prohlížeči vytvoříte požadavek na /health koncový bod. Databáze a AppDbContext neexistuje, takže aplikace nabízí následující odpověď:

Unhealthy

Aktivujte ukázkovou aplikaci pro vytvoření databáze. Vytvořte žádost na /createdatabase . Aplikace odpoví:

Creating the database...
Done!
Navigate to /health to see the health status.

Vytvořte požadavek na /health koncový bod. Databáze a kontext existují, takže aplikace reaguje:

Healthy

Aktivujte ukázkovou aplikaci, aby se odstranila databáze. Vytvořte žádost na /deletedatabase . Aplikace odpoví:

Deleting the database...
Done!
Navigate to /health to see the health status.

Vytvořte požadavek na /health koncový bod. Aplikace poskytuje poškozenou reakci:

Unhealthy

Samostatné sondy pro připravenost a živý provoz

V některých scénářích hostování se používá pár kontrol stavu, který rozlišuje dva stavy aplikace:

  • Připravenost indikuje, jestli je aplikace spuštěná normálně, ale není připravená na příjem požadavků.
  • Živý vyjadřuje, jestli došlo k chybě aplikace a že se musí restartovat.

Vezměte v úvahu následující příklad: aplikace musí stáhnout rozsáhlý konfigurační soubor předtím, než bude připraveno zpracovat požadavky. Nechceme, aby se aplikace restartovala v případě, že se prvotní stažení nepovede, protože aplikace může zkusit znovu stáhnout soubor několikrát. K popsání živého procesu používáme test živého života . neprovádí se žádné další kontroly. Chceme také zabránit posílání požadavků do aplikace před tím, než stahování konfiguračního souboru proběhlo úspěšně. K označení "Nepřipraveno" se používá test připravenosti , dokud se stahování nezdaří a aplikace je připravená přijímat požadavky.

Ukázková aplikace obsahuje kontrolu stavu, která oznamuje dokončení dlouhotrvající úlohy po spuštění v hostované službě. StartupHostedServiceHealthCheckZpřístupňuje vlastnost, StartupTaskCompleted která hostovaná služba může nastavit na hodnotu true po dokončení její dlouhotrvající úlohy ( StartupHostedServiceHealthCheck.cs ):

public class StartupHostedServiceHealthCheck : IHealthCheck
{
    private volatile bool _startupTaskCompleted = false;

    public string Name => "slow_dependency_check";

    public bool StartupTaskCompleted
    {
        get => _startupTaskCompleted;
        set => _startupTaskCompleted = value;
    }

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

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

Dlouhodobě běžící úloha na pozadí je spuštěna hostovanou službou ( Services/StartupHostedService ). Při uzavírání úkolu StartupHostedServiceHealthCheck.StartupTaskCompleted je nastaveno na true :

public class StartupHostedService : IHostedService, IDisposable
{
    private readonly int _delaySeconds = 15;
    private readonly ILogger _logger;
    private readonly StartupHostedServiceHealthCheck _startupHostedServiceHealthCheck;

    public StartupHostedService(ILogger<StartupHostedService> logger, 
        StartupHostedServiceHealthCheck startupHostedServiceHealthCheck)
    {
        _logger = logger;
        _startupHostedServiceHealthCheck = startupHostedServiceHealthCheck;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("Startup Background Service is starting.");

        // Simulate the effect of a long-running startup task.
        Task.Run(async () =>
        {
            await Task.Delay(_delaySeconds * 1000);

            _startupHostedServiceHealthCheck.StartupTaskCompleted = true;

            _logger.LogInformation("Startup Background Service has started.");
        });

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("Startup Background Service is stopping.");

        return Task.CompletedTask;
    }

    public void Dispose()
    {
    }
}

Kontroly stavu jsou registrovány AddCheck ve Startup.ConfigureServices službě společně s hostovanou službou. Vzhledem k tomu, že hostovaná služba musí nastavit vlastnost pro kontrolu stavu, je tato kontrolu také zaregistrována v kontejneru služby ( LivenessProbeStartup.cs ):

services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();

services.AddHealthChecks()
    .AddCheck<StartupHostedServiceHealthCheck>(
        "hosted_service_startup", 
        failureStatus: HealthStatus.Degraded, 
        tags: new[] { "ready" });

services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = (check) => check.Tags.Contains("ready");
});

services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();

Koncový bod kontroly stavu je vytvořen voláním MapHealthChecks v Startup.Configure . V ukázkové aplikaci jsou koncové body kontroly stavu vytvořeny v:

  • /health/ready pro kontrolu připravenosti. Kontrola připravenosti filtruje kontrolu stavu na kontrolu stavu se ready značkou.
  • /health/live pro kontrolu živého provozu. Kontrola živého odfiltruje StartupHostedServiceHealthCheck vrácení se změnami false v HealthCheckOptions.Predicate (Další informace najdete v tématu filtrování kontrol stavu).

V následujícím příkladu kódu:

  • Kontrola připravenosti používá všechny registrované kontroly se značkou ' Read '.
  • PredicateVyloučí všechny kontroly a vrátí 200 – OK.
app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("ready"),
    });

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

Pokud chcete spustit scénář konfigurace připravenosti/živých aplikací pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario liveness

V prohlížeči navštivte několikrát, /health/ready dokud neuplyne 15 sekund. Sestavy kontroly stavu Unhealthy za prvních 15 sekund. Po 15 sekundách koncový bod sestaví Healthy , který odráží dokončení dlouhotrvající úlohy hostovanou službou.

tento příklad také vytvoří kontrolu stavu Publisher ( IHealthCheckPublisher implementace), která spouští první kontrolu připravenosti se dvěma sekundovým zpožděním. další informace najdete v části Publisher kontroly stavu .

Příklad Kubernetes

Používání samostatné kontroly připravenosti a živých kontrol je užitečné v prostředí, jako je Kubernetes. V Kubernetes může být aplikace nutná k provádění časově náročné práce při spuštění před přijetím požadavků, jako je například test dostupnosti podkladové databáze. Použití samostatných kontrol umožňuje nástroji Orchestrator rozlišit, jestli aplikace funguje, ale ještě není připravená, nebo jestli se aplikace nedala spustit. Další informace o testování připravenosti a provozní sondy v Kubernetes najdete v tématu Konfigurace živých a připravených sond v dokumentaci k Kubernetes.

Následující příklad ukazuje konfiguraci testu připravenosti na Kubernetes:

spec:
  template:
  spec:
    readinessProbe:
      # an http probe
      httpGet:
        path: /health/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

Test založený na metrikách s vlastním zapisovačem odpovědí

Ukázková aplikace ukazuje kontrolu stavu paměti pomocí vlastního zapisovače odpovědí.

MemoryHealthCheck hlásí snížený stav, pokud aplikace používá více než určenou prahovou hodnotu paměti (1 GB v ukázkové aplikaci). HealthCheckResultZahrnuje informace o uvolňování paměti (GC) pro aplikaci ( MemoryHealthCheck.cs ):

public class MemoryHealthCheck : IHealthCheck
{
    private readonly IOptionsMonitor<MemoryCheckOptions> _options;

    public MemoryHealthCheck(IOptionsMonitor<MemoryCheckOptions> options)
    {
        _options = options;
    }

    public string Name => "memory_check";

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, 
        CancellationToken cancellationToken = default(CancellationToken))
    {
        var options = _options.Get(context.Registration.Name);

        // Include GC information in the reported diagnostics.
        var allocated = GC.GetTotalMemory(forceFullCollection: false);
        var data = new Dictionary<string, object>()
        {
            { "AllocatedBytes", allocated },
            { "Gen0Collections", GC.CollectionCount(0) },
            { "Gen1Collections", GC.CollectionCount(1) },
            { "Gen2Collections", GC.CollectionCount(2) },
        };
        var status = (allocated < options.Threshold) ? 
            HealthStatus.Healthy : context.Registration.FailureStatus;

        return Task.FromResult(new HealthCheckResult(
            status,
            description: "Reports degraded status if allocated bytes " +
                $">= {options.Threshold} bytes.",
            exception: null,
            data: data));
    }
}

Registrovat služby kontroly stavu AddHealthChecks v nástroji v Startup.ConfigureServices . Místo povolení kontroly stavu předáním AddCheck MemoryHealthCheck jako služby je zaregistrována jako služba. Všechny IHealthCheck registrované služby jsou k dispozici pro služby kontroly stavu a middleware. Službu pro kontrolu stavu doporučujeme zaregistrovat jako služby typu singleton.

V CustomWriterStartup.cs ukázkové aplikaci:

services.AddHealthChecks()
    .AddMemoryHealthCheck("memory");

Koncový bod kontroly stavu je vytvořen voláním MapHealthChecks v Startup.Configure . WriteResponseDelegát je k dispozici pro ResponseWriter pro výstup vlastní odpovědi JSON, když se spustí kontroly stavu:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health", new HealthCheckOptions()
    {
        ResponseWriter = WriteResponse
    });
}

WriteResponseDelegát naformátuje CompositeHealthCheckResult objekt do objektu JSON a pro odpověď na kontrolu stavu vrátí výstup JSON. Další informace najdete v části přizpůsobení výstupu .

Pokud chcete spustit test založený na metrikách s vlastním výstupem zapisovače odpovědí pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario writer

Poznámka

AspNetCore.Diagnostics.HealthChecks zahrnuje scénáře kontroly stavu založené na metrikách, včetně diskového úložiště a maximálního počtu kontrol živých hodnot.

AspNetCore.Diagnostics.HealthChecks není spravován nebo není podporován společností Microsoft.

Filtrovat podle portu

Zavolejte RequireHost MapHealthChecks pomocí vzoru adresy URL, který určuje port pro omezení požadavků na kontrolu stavu na zadaný port. Obvykle se používá v prostředí kontejneru k vystavení portu pro monitorovací služby.

Ukázková aplikace nakonfiguruje port pomocí poskytovatele konfigurace proměnné prostředí. Port je nastaven v launchSettings.json souboru a předán poskytovateli konfigurace prostřednictvím proměnné prostředí. Také je nutné nakonfigurovat server tak, aby naslouchal žádosti na portu pro správu.

Pokud chcete ukázkovou aplikaci použít k předvedení konfigurace portů pro správu, vytvořte launchSettings.json soubor ve Properties složce.

Následující Properties/launchSettings.json soubor v ukázkové aplikaci není zahrnutý v souborech projektu ukázkové aplikace a musí se vytvořit ručně:

{
  "profiles": {
    "SampleApp": {
      "commandName": "Project",
      "commandLineArgs": "",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "ASPNETCORE_URLS": "http://localhost:5000/;http://localhost:5001/",
        "ASPNETCORE_MANAGEMENTPORT": "5001"
      },
      "applicationUrl": "http://localhost:5000/"
    }
  }
}

Registrovat služby kontroly stavu AddHealthChecks v nástroji v Startup.ConfigureServices . Vytvořte koncový bod kontroly stavu voláním MapHealthChecks v Startup.Configure .

V ukázkové aplikaci volání RequireHost na koncový bod v Startup.Configure Určuje port pro správu z konfigurace:

endpoints.MapHealthChecks("/health")
    .RequireHost($"*:{Configuration["ManagementPort"]}");

Koncové body se vytvoří v ukázkové aplikaci v Startup.Configure . V následujícím příkladu kódu:

  • Kontrola připravenosti používá všechny registrované kontroly se značkou ' Read '.
  • PredicateVyloučí všechny kontroly a vrátí 200 – OK.
app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("ready"),
    });

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

Poznámka

Vytvoření launchSettings.json souboru v ukázkové aplikaci se vyhnete nastavením portu pro správu explicitně v kódu. V Program.cs místě HostBuilder , kde je vytvořena, přidejte volání do ListenAnyIP a poskytněte koncový bod portu pro správu aplikace. V Configure nástroji ManagementPortStartup.cs Zadejte port pro správu s RequireHost :

Program.cs:

return new HostBuilder()
    .ConfigureWebHostDefaults(webBuilder =>
    {
        webBuilder.UseKestrel()
            .ConfigureKestrel(serverOptions =>
            {
                serverOptions.ListenAnyIP(5001);
            })
            .UseStartup(startupType);
    })
    .Build();

ManagementPortStartup.cs:

app.UseEndpoints(endpoints =>
{
    endpoints.MapHealthChecks("/health").RequireHost("*:5001");
});

Pokud chcete spustit scénář konfigurace portu pro správu pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario port

Distribuce knihovny kontroly stavu

Postup při distribuci kontroly stavu jako knihovny:

  1. Zapište kontrolu stavu, která implementuje IHealthCheck rozhraní jako samostatnou třídu. Třída může spoléhat na vkládání závislostí (di), aktivovat typ a pojmenované možnosti pro přístup k datům konfigurace.

    V logice kontroly stavu pro CheckHealthAsync :

    • data1 a data2 jsou použity v metodě pro spuštění logiky kontroly stavu testu.
    • AccessViolationException je zpracována.

    V případě AccessViolationException , že dojde k chybě, se FailureStatus vrátí s a HealthCheckResult umožní uživatelům konfigurovat stav selhání kontroly stavu.

    using System;
    using System.Threading;
    using System.Threading.Tasks;
    using Microsoft.Extensions.Diagnostics.HealthChecks;
    
    namespace SampleApp
    {
        public class ExampleHealthCheck : IHealthCheck
        {
            private readonly string _data1;
            private readonly int? _data2;
    
            public ExampleHealthCheck(string data1, int? data2)
            {
                _data1 = data1 ?? throw new ArgumentNullException(nameof(data1));
                _data2 = data2 ?? throw new ArgumentNullException(nameof(data2));
            }
    
            public async Task<HealthCheckResult> CheckHealthAsync(
                HealthCheckContext context, CancellationToken cancellationToken)
            {
                try
                {
                    return HealthCheckResult.Healthy();
                }
                catch (AccessViolationException ex)
                {
                    return new HealthCheckResult(
                        context.Registration.FailureStatus,
                        description: "An access violation occurred during the check.",
                        exception: ex,
                        data: null);
                }
            }
        }
    }
    
  2. Zapište metodu rozšíření s parametry, které aplikace spotřebovávají ve své Startup.Configure metodě. V následujícím příkladu předpokládejme následující signatura metody kontroly stavu:

    ExampleHealthCheck(string, string, int )
    

    Předchozí signatura indikuje, že ExampleHealthCheck pro zpracování logiky sondy kontroly stavu vyžaduje další data. Data jsou k dispozici delegátovi použitému k vytvoření instance kontroly stavu při registraci kontroly stavu s metodou rozšíření. V následujícím příkladu volající určuje nepovinné:

    • název kontroly stavu ( name ). Pokud null se example_health_check používá.
    • datový bod řetězce pro kontrolu stavu ( data1 ).
    • celočíselný datový bod pro kontrolu stavu ( data2 ). Pokud null se 1 používá.
    • stav selhání ( HealthStatus ). Výchozí formát je null. V případě null , že HealthStatus.Unhealthy je hlášen stav selhání.
    • značky ( IEnumerable<string> ).
    using System.Collections.Generic;
    using Microsoft.Extensions.Diagnostics.HealthChecks;
    
    public static class ExampleHealthCheckBuilderExtensions
    {
        const string DefaultName = "example_health_check";
    
        public static IHealthChecksBuilder AddExampleHealthCheck(
            this IHealthChecksBuilder builder,
            string name = default,
            string data1,
            int data2 = 1,
            HealthStatus? failureStatus = default,
            IEnumerable<string> tags = default)
        {
            return builder.Add(new HealthCheckRegistration(
                name ?? DefaultName,
                sp => new ExampleHealthCheck(data1, data2),
                failureStatus,
                tags));
        }
    }
    

Publisher kontroly stavu

Když IHealthCheckPublisher se přidá do kontejneru služby, systém kontroly stavu pravidelně spouští kontroly stavu a volání PublishAsync s výsledkem. To je užitečné ve scénáři sledování stavu založeném na nabízených oznámeních, který očekává, že každý proces bude pravidelně volat monitorovací systém, aby se zjistil stav.

IHealthCheckPublisherRozhraní má jedinou metodu:

Task PublishAsync(HealthReport report, CancellationToken cancellationToken);

HealthCheckPublisherOptions umožňuje nastavit:

  • Delay: Počáteční zpoždění použité po spuštění aplikace před spuštěním IHealthCheckPublisher instancí. Zpoždění se použije jednou při spuštění a nevztahuje se na další iterace. Výchozí hodnota je pět sekund.
  • Period: Období IHealthCheckPublisher provádění. Výchozí hodnota je 30 sekund.
  • Predicate: Pokud Predicate je null (výchozí), služba Vydavatel kontroly stavu spustí všechny zaregistrované kontroly stavu. Chcete-li spustit podmnožinu kontrol stavu, zadejte funkci, která filtruje sadu kontrol. Predikát je vyhodnocen každou periodu.
  • Timeout: Časový limit pro spuštění kontrol stavu pro všechny IHealthCheckPublisher instance. Použijte InfiniteTimeSpan k provedení bez časového limitu. Výchozí hodnota je 30 sekund.

V ukázkové aplikaci ReadinessPublisher je IHealthCheckPublisher implementace. Stav kontroly stavu se protokoluje pro každou kontrolu na úrovni protokolu:

public class ReadinessPublisher : IHealthCheckPublisher
{
    private readonly ILogger _logger;

    public ReadinessPublisher(ILogger<ReadinessPublisher> logger)
    {
        _logger = logger;
    }

    // The following example is for demonstration purposes only. Health Checks 
    // Middleware already logs health checks results. A real-world readiness 
    // check in a production app might perform a set of more expensive or 
    // time-consuming checks to determine if other resources are responding 
    // properly.
    public Task PublishAsync(HealthReport report, 
        CancellationToken cancellationToken)
    {
        if (report.Status == HealthStatus.Healthy)
        {
            _logger.LogInformation("{Timestamp} Readiness Probe Status: {Result}", 
                DateTime.UtcNow, report.Status);
        }
        else
        {
            _logger.LogError("{Timestamp} Readiness Probe Status: {Result}", 
                DateTime.UtcNow, report.Status);
        }

        cancellationToken.ThrowIfCancellationRequested();

        return Task.CompletedTask;
    }
}

V příkladu ukázkové aplikace LivenessProbeStartup StartupHostedService má kontroler připravenosti dvě sekundy na spuštění a spustí kontrolu každých 30 sekund. Chcete-li aktivovat IHealthCheckPublisher implementaci, ukázka se registruje ReadinessPublisher jako služba s jedním prvkem v kontejneru Injektáže (di) pro vkládání závislostí :

services.AddHostedService<StartupHostedService>();
services.AddSingleton<StartupHostedServiceHealthCheck>();

services.AddHealthChecks()
    .AddCheck<StartupHostedServiceHealthCheck>(
        "hosted_service_startup", 
        failureStatus: HealthStatus.Degraded, 
        tags: new[] { "ready" });

services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = (check) => check.Tags.Contains("ready");
});

services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();

Poznámka

AspNetCore.Diagnostics.HealthCheckszahrnuje vydavatele pro několik systémů, včetně Application Insights.

AspNetCore.Diagnostics.HealthChecks není spravován nebo není podporován společností Microsoft.

Omezení kontrol stavu pomocí MapWhen

Použijte MapWhen k podmíněně větvení kanálu žádostí pro koncové body kontroly stavu.

V následujícím příkladu MapWhen větví kanál žádosti o aktivaci middlewaru pro kontrolu stavu, pokud se pro koncový bod přijme požadavek Get api/HealthCheck :

app.MapWhen(
    context => context.Request.Method == HttpMethod.Get.Method && 
        context.Request.Path.StartsWith("/api/HealthCheck"),
    builder => builder.UseHealthChecks());

app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
});

Další informace naleznete v tématu ASP.NET Core Jiné.

ASP.NET Core nabízí kontrolu stavu middlewaru a knihovny pro vytváření sestav stavu součástí infrastruktury aplikace.

Kontroly stavu jsou zpřístupněné aplikací jako koncové body HTTP. Koncové body kontroly stavu je možné nakonfigurovat pro nejrůznější scénáře monitorování v reálném čase:

  • Sondy stavu můžou použít orchestrace kontejnerů a nástroje pro vyrovnávání zatížení ke kontrole stavu aplikace. Například produkt Orchestrator může reagovat na selhání kontroly stavu zastavením zavedení nasazení nebo restartováním kontejneru. Nástroj pro vyrovnávání zatížení může reagovat na poškozenou aplikaci směrováním provozu mimo instanci selhání do stavu v pořádku.
  • Použití paměti, disku a dalších prostředků fyzického serveru se dá monitorovat v dobrém stavu.
  • Kontroly stavu můžou testovat závislosti aplikace, jako jsou databáze a externí koncové body služby, aby se potvrdila dostupnost a normální fungování.

Zobrazit nebo stáhnout ukázkový kód (Jak stáhnout)

Ukázková aplikace obsahuje příklady scénářů popsaných v tomto tématu. Pokud chcete pro daný scénář spustit ukázkovou aplikaci, použijte příkaz dotnet Run ze složky projektu v příkazovém prostředí. Podrobnosti o tom, jak používat ukázkovou aplikaci, najdete v souboru Readme.MD ukázkové aplikace a v popisech scénářů v tomto tématu.

Požadavky

Kontroly stavu se obvykle používají s externí službou monitorování nebo nástrojem Orchestrator Container Service ke kontrole stavu aplikace. Před přidáním kontrol stavu do aplikace se rozhodněte, který monitorovací systém se má použít. Monitorovací systém vyhodnotí, jaké typy kontrol stavu se mají vytvořit a jak nakonfigurovat jejich koncové body.

Odkazujte na Microsoft.AspNetCore.App Metapackage nebo přidejte do balíčku odkaz na balíček Microsoft.AspNetCore.Diagnostics.HealthChecks .

Ukázková aplikace poskytuje spouštěcí kód k předvedení kontrol stavu pro několik scénářů. Scénář testu databáze kontroluje stav připojení k databázi pomocí AspNetCore.Diagnostics.HealthChecks . Scénář testu DbContext zkontroluje databázi pomocí EF Core DbContext . K prozkoumání scénářů databáze se jedná o ukázkovou aplikaci:

Poznámka

AspNetCore.Diagnostics.HealthChecks není spravován nebo není podporován společností Microsoft.

Další scénář kontroly stavu ukazuje, jak filtrovat kontroly stavu na port pro správu. Ukázková aplikace vyžaduje, abyste v souboru, který obsahuje adresu URL pro správu a port pro správu, vytvořili vlastnosti nebo launchSettings.js . Další informace naleznete v části Filter by port .

Základní sonda stavu

U mnoha aplikací je základní konfigurace sondy stavu, která oznamuje dostupnost aplikace pro zpracování požadavků (živý), ke zjištění stavu aplikace dostačující.

Základní konfigurace registruje služby kontroly stavu a volá middleware kontroly stavu, aby reagovala na koncový bod adresy URL s odpovědí na stav. Ve výchozím nastavení nejsou k otestování konkrétní závislosti nebo subsystému registrovány žádné konkrétní kontroly stavu. Aplikace se považuje za v pořádku, pokud dokáže reagovat na adresu URL koncového bodu stavu. Výchozí zapisovač odpovědí zapíše stav ( HealthStatus ) jako odpověď ve formátu prostého textu zpátky klientovi a uvede buď HealthStatus.Healthy stav, HealthStatus.Degraded nebo HealthStatus.Unhealthy .

Registrovat služby kontroly stavu AddHealthChecks v nástroji v Startup.ConfigureServices . Přidejte koncový bod pro kontrolu stavu middleware s UseHealthChecks v kanálu zpracování požadavků Startup.Configure .

V ukázkové aplikaci se koncový bod kontroly stavu vytvoří v /health (BasicStartup. cs):

public class BasicStartup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddHealthChecks();
    }

    public void Configure(IApplicationBuilder app)
    {
        app.UseHealthChecks("/health");
    }
}

Pokud chcete spustit scénář základní konfigurace pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario basic

Ukázka Docker

Docker nabízí vestavěnou HEALTHCHECK direktivu, která se dá použít ke kontrole stavu aplikace, která používá konfiguraci základní kontroly stavu:

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

Vytvořit kontroly stavu

Kontroly stavu jsou vytvářeny implementací IHealthCheck rozhraní. CheckHealthAsyncMetoda vrátí hodnotu HealthCheckResult , která označuje stav jako Healthy , Degraded nebo Unhealthy . Výsledek je napsaný jako odpověď prostého textu s konfigurovatelným stavový kódem (konfigurace je popsaná v části Možnosti kontroly stavu). HealthCheckResult může také vracet volitelné páry klíč-hodnota.

Příklad kontroly stavu

Následující ExampleHealthCheck třída ukazuje rozložení kontroly stavu. Logika kontrol stavu je umístěna v CheckHealthAsync metodě . Následující příklad nastaví fiktivní proměnnou healthCheckResultHealthy na true . Pokud je hodnota healthCheckResultHealthy nastavená na false , vrátí se HealthCheckResult.Unhealthy stav .

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

        if (healthCheckResultHealthy)
        {
            return Task.FromResult(
                HealthCheckResult.Healthy("The check indicates a healthy result."));
        }

        return Task.FromResult(
            HealthCheckResult.Unhealthy("The check indicates an unhealthy result."));
    }
}

Registrace služeb kontroly stavu

Typ ExampleHealthCheck se přidá do služeb kontroly stavu v pomocí Startup.ConfigureServices AddCheck :

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>("example_health_check");

Přetížení znázorněné v následujícím příkladu nastaví stav selhání ( ) tak, aby se nahlásí, když kontrola stavu AddCheck HealthStatus nahlásí selhání. Pokud je stav selhání nastavený null na (výchozí), je HealthStatus.Unhealthy hlášen. Toto přetížení je užitečný scénář pro autory knihoven, kde stav selhání označený knihovnou vynucuje aplikace, když dojde k selhání kontroly stavu, pokud implementace kontroly stavu respektuje toto nastavení.

Značky lze použít k filtrování kontrol stavu (popsaných dále v části Kontroly stavu filtru).

services.AddHealthChecks()
    .AddCheck<ExampleHealthCheck>(
        "example_health_check",
        failureStatus: HealthStatus.Degraded,
        tags: new[] { "example" });

AddCheck může také spustit funkci lambda. V následujícím příkladu je název kontroly stavu Startup.ConfigureServices zadaný jako a kontrola vždy vrátí stav V Example pořádku:

services.AddHealthChecks()
    .AddCheck("Example", () =>
        HealthCheckResult.Healthy("Example is OK!"), tags: new[] { "example" });

Použití middlewaru kontroly stavu

V Startup.Configure kanálu UseHealthChecks zpracování volejte s adresou URL koncového bodu nebo relativní cestou:

app.UseHealthChecks("/health");

Pokud by kontroly stavu měly naslouchat na určitém portu, nastavte port pomocí přetížení metody (popsaných dále v UseHealthChecks části Filtrování podle portu):

app.UseHealthChecks("/health", port: 8000);

Možnosti kontroly stavu

HealthCheckOptions poskytnout příležitost k přizpůsobení chování kontroly stavu:

Filtrování kontrol stavu

Middleware pro kontroly stavu ve výchozím nastavení spouští všechny zaregistrované kontroly stavu. Pokud chcete spustit podmnožinu kontrol stavu, zadejte funkci, která k možnosti vrátí logickou Predicate hodnotu. V následujícím příkladu se kontrola stavu vyfiltruje podle značky ( ) v podmíněném příkazu funkce, kde se vrátí pouze v případě, že se vlastnost kontroly stavu shoduje s Bar bar_tag true Tags foo_tag vlastností nebo baz_tag :

using System.Threading.Tasks;
using Microsoft.AspNetCore.Diagnostics.HealthChecks;
using Microsoft.Extensions.Diagnostics.HealthChecks;

public void ConfigureServices(IServiceCollection services)
{
    services.AddHealthChecks()
        .AddCheck("Foo", () =>
            HealthCheckResult.Healthy("Foo is OK!"), tags: new[] { "foo_tag" })
        .AddCheck("Bar", () =>
            HealthCheckResult.Unhealthy("Bar is unhealthy!"), 
                tags: new[] { "bar_tag" })
        .AddCheck("Baz", () =>
            HealthCheckResult.Healthy("Baz is OK!"), tags: new[] { "baz_tag" });
}

public void Configure(IApplicationBuilder app)
{
    app.UseHealthChecks("/health", new HealthCheckOptions()
    {
        Predicate = (check) => check.Tags.Contains("foo_tag") ||
            check.Tags.Contains("baz_tag")
    });
}

Přizpůsobení stavového kódu HTTP

Slouží ResultStatusCodes k přizpůsobení mapování stavu na stavové kódy HTTP. Následující StatusCodes přiřazení jsou výchozí hodnoty používané middlewarem. Změňte hodnoty stavového kódu tak, aby splňovaly vaše požadavky.

V Startup.Configure:

//using Microsoft.AspNetCore.Diagnostics.HealthChecks;
//using Microsoft.Extensions.Diagnostics.HealthChecks;

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

Potlačení hlaviček mezipaměti

AllowCachingResponses určuje, jestli middleware kontroly stavu přidá hlavičky HTTP do odpovědi sondy, aby se zabránilo ukládání odpovědí do mezipaměti. Pokud je hodnota (výchozí), middleware nastaví nebo přepíše hlavičky , a , aby se zabránilo false Cache-Control ukládání odpovědí do Expires Pragma mezipaměti. Pokud je hodnota true , middleware neupraví hlavičky mezipaměti odpovědi.

V Startup.Configure:

//using Microsoft.AspNetCore.Diagnostics.HealthChecks;
//using Microsoft.Extensions.Diagnostics.HealthChecks;

app.UseHealthChecks("/health", new HealthCheckOptions()
{
    AllowCachingResponses = false
});

Přizpůsobení výstupu

Možnost ResponseWriter získá nebo nastaví delegáta použitého k zápisu odpovědi. Výchozí delegát zapíše minimální odpověď ve formátu prostého textu s řetězcovou hodnotou HealthReport.Status .

V Startup.Configure:

// using Microsoft.AspNetCore.Diagnostics.HealthChecks;
// using Microsoft.Extensions.Diagnostics.HealthChecks;

app.UseHealthChecks("/health", new HealthCheckOptions()
{
    ResponseWriter = WriteResponse
});

Výchozí delegát zapíše minimální odpověď ve formátu prostého textu s řetězcovou hodnotou HealthReport.Status . Následující vlastní delegát WriteResponse vynese vlastní odpověď JSON:

private static Task WriteResponse(HttpContext httpContext, HealthReport result)
{
    httpContext.Response.ContentType = "application/json";

    var json = new JObject(
        new JProperty("status", result.Status.ToString()),
        new JProperty("results", new JObject(result.Entries.Select(pair =>
            new JProperty(pair.Key, new JObject(
                new JProperty("status", pair.Value.Status.ToString()),
                new JProperty("description", pair.Value.Description),
                new JProperty("data", new JObject(pair.Value.Data.Select(
                    p => new JProperty(p.Key, p.Value))))))))));
    return httpContext.Response.WriteAsync(
        json.ToString(Formatting.Indented));
}

Systém kontrol stavu neposkytuje integrovanou podporu složitých návratových formátů JSON, protože formát je specifický pro váš výběr monitorovacího systému. V předchozím příkladu si můžete podle potřeby přizpůsobit , JObject aby to splňovalo vaše potřeby.

Test databáze

Kontrola stavu může určit databázový dotaz, který se má spustit jako logický test, který bude indikovat, jestli databáze normálně reaguje.

Ukázková aplikace používá knihovnu kontroly stavu pro ASP.NET Core aplikací k provedení kontroly stavu AspNetCore.Diagnostics.HealthChecks u SQL Server databáze. AspNetCore.Diagnostics.HealthChecks provede dotaz na databázi a potvrdí, že je připojení SELECT 1 k databázi v pořádku.

Upozornění

Při kontrole připojení k databázi pomocí dotazu zvolte dotaz, který se vrátí rychle. Přístup k dotazům riskuje přetížení databáze a snížení jejího výkonu. Ve většině případů není spuštění testovacího dotazu nezbytné. Pouhé vytvoření úspěšného připojení k databázi je dostačující. Pokud zjistíte, že je nutné spustit dotaz, zvolte jednoduchý dotaz SELECT, například SELECT 1 .

Zahrnout odkaz na balíček na AspNetCore.HealthChecks.SqlServer .

Do souboru ukázkové aplikace zadejte platný připojovací appsettings.json řetězec databáze. Aplikace používá databázi SQL Server s názvem HealthCheckSample :

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(localdb)\\MSSQLLocalDB;Database=HealthCheckSample;Trusted_Connection=True;MultipleActiveResultSets=true;ConnectRetryCount=0"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Debug"
    },
    "Console": {
      "IncludeScopes": "true"
    }
  }
}

Zaregistrujte služby kontroly stavu pomocí AddHealthChecks v Startup.ConfigureServices . Ukázková aplikace volá AddSqlServer metodu s připojovacím řetězcem databáze (DbHealthStartup.cs):

public void ConfigureServices(IServiceCollection services)
{
    services.AddHealthChecks()
        .AddSqlServer(Configuration["ConnectionStrings:DefaultConnection"]);
}

Volejte middleware pro kontroly stavu v kanálu zpracování aplikace v Startup.Configure :

app.UseHealthChecks("/health");

Pokud chcete spustit scénář sondy databáze pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario db

Poznámka

AspNetCore.Diagnostics.HealthChecks není udržováno ani podporováno společností Microsoft.

Entity Framework Core dbContext

Kontrola DbContext potvrzuje, že aplikace může komunikovat s databází nakonfigurovanou pro EF Core DbContext . Kontrola DbContext se podporuje v aplikacích, které:

AddDbContextCheck<TContext> zaregistruje kontrolu stavu pro DbContext . se DbContext dodá TContext jako pro metodu . Přetížení je k dispozici ke konfiguraci stavu selhání, značek a vlastního testovacího dotazu.

Ve výchozím nastavení:

  • Volání DbContextHealthCheck EF Core metody CanConnectAsync . To, jaká operace se spustí, můžete přizpůsobit při kontrole stavu pomocí AddDbContextCheck přetížení metody.
  • Název kontroly stavu je název TContext typu.

V ukázkové aplikaci je k dispozici a zaregistrován AppDbContext jako služba v ( AddDbContextCheck Startup.ConfigureServices DbContextHealthStartup.cs):

public void ConfigureServices(IServiceCollection services)
{
    services.AddHealthChecks()
        .AddDbContextCheck<AppDbContext>();

    services.AddDbContext<AppDbContext>(options =>
    {
        options.UseSqlServer(
            Configuration["ConnectionStrings:DefaultConnection"]);
    });
}

V ukázkové aplikaci přidá UseHealthChecks middleware kontroly stavu v Startup.Configure souboru .

app.UseHealthChecks("/health");

Pokud chcete spustit DbContext scénář testu pomocí ukázkové aplikace, ověřte, že databáze zadaná připojovacím řetězcem v instanci SQL Server databáze. Pokud databáze existuje, odstraňte ji.

V příkazovém prostředí spusťte ze složky projektu následující příkaz:

dotnet run --scenario dbcontext

Po spuštění aplikace zkontrolujte stav vytvořením požadavku na koncový /health bod v prohlížeči. Databáze a AppDbContext neexistují, takže aplikace poskytuje následující odpověď:

Unhealthy

Aktivujte ukázkovou aplikaci a vytvořte databázi. Vytvořte požadavek na /createdatabase . Aplikace odpoví:

Creating the database...
Done!
Navigate to /health to see the health status.

Vytvořte požadavek na koncový /health bod. Databáze a kontext existují, takže aplikace reaguje:

Healthy

Aktivujte ukázkovou aplikaci, která databázi odstraní. Vytvořte požadavek na /deletedatabase . Aplikace odpoví:

Deleting the database...
Done!
Navigate to /health to see the health status.

Vytvořte požadavek na koncový /health bod. Aplikace poskytne odpověď, která není v pořádku:

Unhealthy

Samostatné testy připravenosti a živého stavu

V některých scénářích hostování se používá dvojice kontrol stavu, které rozlišují dva stavy aplikací:

  • Připravenost značí, jestli aplikace běží normálně, ale není připravená přijímat požadavky.
  • Živá hodnota značí, jestli aplikace havaruje a je nutné ji restartovat.

Představte si následující příklad: Aplikace musí před zpracováním požadavků stáhnout velký konfigurační soubor. Nechceme, aby se aplikace restartoval, pokud počáteční stažení selže, protože aplikace může soubor několikrát znovu stáhnout. Sonda aktivity používáme k popisu aktivity procesu, žádné další kontroly se nesníží. Chceme také zabránit odeslání požadavků do aplikace před úspěšným stažením konfiguračního souboru. Sondu připravenosti používáme k označení nepřipravenosti stavu, dokud stahování neprovede a aplikace nebude připravená přijímat požadavky.

Ukázková aplikace obsahuje kontrolu stavu, která hlásí dokončení dlouhotrvá spouštěcí úlohy v hostované službě. Zpřístupňuje vlastnost , na kterou může hostovaná služba nastavit po dokončení dlouho běžící úlohy StartupHostedServiceHealthCheck StartupTaskCompleted true (StartupHostedServiceHealthCheck.cs):

public class StartupHostedServiceHealthCheck : IHealthCheck
{
    private volatile bool _startupTaskCompleted = false;

    public string Name => "slow_dependency_check";

    public bool StartupTaskCompleted
    {
        get => _startupTaskCompleted;
        set => _startupTaskCompleted = value;
    }

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

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

Dlouhotrvá úloha na pozadí je spuštěna hostovanou službou (Services/StartupHostedService). Na závěr úlohy je StartupHostedServiceHealthCheck.StartupTaskCompleted nastavena na true :

public class StartupHostedService : IHostedService, IDisposable
{
    private readonly int _delaySeconds = 15;
    private readonly ILogger _logger;
    private readonly StartupHostedServiceHealthCheck _startupHostedServiceHealthCheck;

    public StartupHostedService(ILogger<StartupHostedService> logger, 
        StartupHostedServiceHealthCheck startupHostedServiceHealthCheck)
    {
        _logger = logger;
        _startupHostedServiceHealthCheck = startupHostedServiceHealthCheck;
    }

    public Task StartAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("Startup Background Service is starting.");

        // Simulate the effect of a long-running startup task.
        Task.Run(async () =>
        {
            await Task.Delay(_delaySeconds * 1000);

            _startupHostedServiceHealthCheck.StartupTaskCompleted = true;

            _logger.LogInformation("Startup Background Service has started.");
        });

        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        _logger.LogInformation("Startup Background Service is stopping.");

        return Task.CompletedTask;
    }

    public void Dispose()
    {
    }
}

Kontrola stavu je zaregistrovaná v AddCheck spolu Startup.ConfigureServices s hostovanou službou. Vzhledem k tomu, že hostovaná služba musí nastavit vlastnost kontroly stavu, je kontrola stavu zaregistrovaná také v kontejneru služby (LivenessProbeStartup.cs):

public void ConfigureServices(IServiceCollection services)
{
    services.AddHostedService<StartupHostedService>();
    services.AddSingleton<StartupHostedServiceHealthCheck>();

    services.AddHealthChecks()
        .AddCheck<StartupHostedServiceHealthCheck>(
            "hosted_service_startup", 
            failureStatus: HealthStatus.Degraded, 
            tags: new[] { "ready" });

    services.Configure<HealthCheckPublisherOptions>(options =>
    {
        options.Delay = TimeSpan.FromSeconds(2);
        options.Predicate = (check) => check.Tags.Contains("ready");
    });

    // The following workaround permits adding an IHealthCheckPublisher 
    // instance to the service container when one or more other hosted 
    // services have already been added to the app. This workaround
    // won't be required with the release of ASP.NET Core 3.0. For more 
    // information, see: https://github.com/aspnet/Extensions/issues/639.
    services.TryAddEnumerable(
        ServiceDescriptor.Singleton(typeof(IHostedService), 
            typeof(HealthCheckPublisherOptions).Assembly
                .GetType(HealthCheckServiceAssembly)));

    services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();
}

Volejte middleware pro kontroly stavu v kanálu zpracování aplikace v Startup.Configure . V ukázkové aplikaci se pro kontrolu připravenosti a kontrolu aktivity vytvoří koncové body kontroly stavu na /health/ready /health/live adrese . Kontrola připravenosti filtruje kontroly stavu na kontrolu stavu se ready značkou . Kontrola aktivity filtruje hodnotu tak, že se vrátí v části (další informace StartupHostedServiceHealthCheck najdete v tématu Kontrola stavu false HealthCheckOptions.Predicate filtru):

app.UseHealthChecks("/health/ready", new HealthCheckOptions()
{
    Predicate = (check) => check.Tags.Contains("ready"), 
});

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

Pokud chcete scénář konfigurace připravenosti/aktivity spustit pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario liveness

V prohlížeči několikrát navštivte /health/ready stránku, dokud neuplyly 15 sekund. Kontrola stavu na prvních 15 sekund hlásí, že není v pořádku. Po 15 sekundách koncový bod na sestaví stav V pořádku , který odráží dokončení dlouhotrjící úlohy hostovanou službou.

V tomto příkladu se také vytvoří Publisher stavu (implementace), která spustí první kontrolu připravenosti IHealthCheckPublisher se dvěmasekudovou prodlevou. Další informace najdete v části Kontrola Publisher stavu.

Příklad Kubernetes

Použití samostatných kontrol připravenosti a aktivity je užitečné v prostředí, jako je Kubernetes. V Kubernetes může být nutné, aby aplikace před přijetím požadavků časově náročně pracovala na spuštění, například test dostupnosti podkladové databáze. Použití samostatných kontrol umožňuje orchestrátoru rozlišit, jestli aplikace funguje, ale ještě není připravená, nebo jestli se aplikaci nepodařilo spustit. Další informace o testech připravenosti a aktivity v Kubernetes najdete v tématu Konfigurace sond aktivity a připravenosti v dokumentaci ke Kubernetes.

Následující příklad ukazuje konfiguraci sondy připravenosti Kubernetes:

spec:
  template:
  spec:
    readinessProbe:
      # an http probe
      httpGet:
        path: /health/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

Sonda založená na metrikách s vlastním zapisovačem odpovědí

Ukázková aplikace předvede kontrolu stavu paměti pomocí vlastního zapisovače odpovědí.

MemoryHealthCheck hlásí stav Není v pořádku, pokud aplikace používá více než danou prahovou hodnotu paměti (1 GB v ukázkové aplikaci). Zahrnuje informace o systému uvolňování paměti HealthCheckResult pro aplikaci (MemoryHealthCheck.cs):

public class MemoryHealthCheck : IHealthCheck
{
    private readonly IOptionsMonitor<MemoryCheckOptions> _options;

    public MemoryHealthCheck(IOptionsMonitor<MemoryCheckOptions> options)
    {
        _options = options;
    }

    public string Name => "memory_check";

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, 
        CancellationToken cancellationToken = default(CancellationToken))
    {
        var options = _options.Get(context.Registration.Name);

        // Include GC information in the reported diagnostics.
        var allocated = GC.GetTotalMemory(forceFullCollection: false);
        var data = new Dictionary<string, object>()
        {
            { "AllocatedBytes", allocated },
            { "Gen0Collections", GC.CollectionCount(0) },
            { "Gen1Collections", GC.CollectionCount(1) },
            { "Gen2Collections", GC.CollectionCount(2) },
        };

        var status = (allocated < options.Threshold) ? 
            HealthStatus.Healthy : HealthStatus.Unhealthy;

        return Task.FromResult(new HealthCheckResult(
            status,
            description: "Reports degraded status if allocated bytes " +
                $">= {options.Threshold} bytes.",
            exception: null,
            data: data));
    }
}

Zaregistrujte služby kontroly stavu pomocí AddHealthChecks v Startup.ConfigureServices . Místo toho, aby se kontrola stavu povoluje předáním do AddCheck , MemoryHealthCheck je zaregistrovaný jako služba. Všechny IHealthCheck zaregistrované služby jsou dostupné pro služby kontroly stavu a middleware. Doporučujeme zaregistrovat služby kontroly stavu jako služby Singleton.

V ukázkové aplikaci (CustomWriterStartup.cs):

public void ConfigureServices(IServiceCollection services)
{
    services.AddHealthChecks()
        .AddMemoryHealthCheck("memory");
}

Volejte middleware pro kontroly stavu v kanálu zpracování aplikace v Startup.Configure . Delegát je do vlastnosti k výstupu vlastní odpovědi JSON po provedení WriteResponse ResponseWriter kontroly stavu k dispozici:

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseHealthChecks("/health", new HealthCheckOptions()
    {
        // This custom writer formats the detailed status as JSON.
        ResponseWriter = WriteResponse
    });
}

Metoda WriteResponse CompositeHealthCheckResult naformátuje do objektu JSON a vrátí výstup JSON pro odpověď kontroly stavu:

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

    var json = new JObject(
        new JProperty("status", result.Status.ToString()),
        new JProperty("results", new JObject(result.Entries.Select(pair =>
            new JProperty(pair.Key, new JObject(
                new JProperty("status", pair.Value.Status.ToString()),
                new JProperty("description", pair.Value.Description),
                new JProperty("data", new JObject(pair.Value.Data.Select(
                    p => new JProperty(p.Key, p.Value))))))))));
    return httpContext.Response.WriteAsync(
        json.ToString(Formatting.Indented));
}

Pokud chcete spustit sondu založenou na metrice s výstupem vlastního zapisovače odpovědí pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario writer

Poznámka

AspNetCore.Diagnostics.HealthChecks zahrnuje scénáře kontroly stavu na základě metrik, včetně diskového úložiště a kontrol maximální hodnoty.

AspNetCore.Diagnostics.HealthChecks není udržováno ani podporováno společností Microsoft.

Filtrovat podle portu

Volání UseHealthChecks s portem omezuje žádosti o kontrolu stavu na zadaný port. To se obvykle používá v prostředí kontejneru ke vystavení portu pro monitorovací služby.

Ukázková aplikace nakonfiguruje port pomocí zprostředkovatele konfigurace proměnných prostředí. Port se nastaví v souboru launchSettings.json a předá se zprostředkovateli konfigurace prostřednictvím proměnné prostředí. Musíte také nakonfigurovat server tak, aby naslouchal požadavkům na portu pro správu.

Pokud chcete ukázkovou aplikaci použít k předvedení konfigurace portů pro správu,launchSettings.jssoubor ve složce Vlastnosti.

Následující vlastnosti/launchSettings.jsv souboru v ukázkové aplikaci nejsou zahrnuté v souborech projektu ukázkové aplikace a musí se vytvořit ručně:

{
  "profiles": {
    "SampleApp": {
      "commandName": "Project",
      "commandLineArgs": "",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "ASPNETCORE_URLS": "http://localhost:5000/;http://localhost:5001/",
        "ASPNETCORE_MANAGEMENTPORT": "5001"
      },
      "applicationUrl": "http://localhost:5000/"
    }
  }
}

Zaregistrujte služby kontroly stavu pomocí AddHealthChecks v Startup.ConfigureServices . Volání určuje UseHealthChecks port pro správu (ManagementPortStartup.cs):

public class ManagementPortStartup
{
    public ManagementPortStartup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddHealthChecks();
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        app.UseHealthChecks("/health", port: Configuration["ManagementPort"]);

        app.Run(async (context) =>
        {
            await context.Response.WriteAsync(
                "Navigate to " + 
                $"http://localhost:{Configuration["ManagementPort"]}/health " +
                "to see the health status.");
        });
    }
}

Poznámka

Můžete se vyhnout vytváření launchSettings.jssouboru v ukázkové aplikaci explicitním nastavením adres URL a portu pro správu v kódu. V souboru Program.cs, kde se vytvoří , přidejte volání a zadejte koncový bod normální odpovědi aplikace WebHostBuilder a koncový bod portu pro UseUrls správu. V souboru ManagementPortStartup.cs, kde je volána, UseHealthChecks explicitně zadejte port pro správu.

Program.cs:

return new WebHostBuilder()
    .UseConfiguration(config)
    .UseUrls("http://localhost:5000/;http://localhost:5001/")
    .ConfigureLogging(builder =>
    {
        builder.SetMinimumLevel(LogLevel.Trace);
        builder.AddConfiguration(config);
        builder.AddConsole();
    })
    .UseKestrel()
    .UseStartup(startupType)
    .Build();

ManagementPortStartup.cs:

app.UseHealthChecks("/health", port: 5001);

Pokud chcete spustit scénář konfigurace portu pro správu pomocí ukázkové aplikace, spusťte následující příkaz ze složky projektu v příkazovém prostředí:

dotnet run --scenario port

Distribuce knihovny kontroly stavu

Distribuce kontroly stavu jako knihovny:

  1. Napište kontrolu stavu, která implementuje IHealthCheck rozhraní jako samostatnou třídu. Pro přístup ke konfiguračním datům se třída může spoléhat na injektáž závislostí (DI),aktivaci typu a pojmenované možnosti.

    V logice kontrol stavu pro CheckHealthAsync :

    • data1 a data2 se používají v metodě ke spuštění logiky kontroly stavu sondy.
    • AccessViolationException se zpracovává.

    Když nastane, vrátí se s , aby uživatelé těmto uživatelům umožnili AccessViolationException nakonfigurovat stav selhání kontrol FailureStatus HealthCheckResult stavu.

    using System;
    using System.Threading;
    using System.Threading.Tasks;
    using Microsoft.Extensions.Diagnostics.HealthChecks;
    
    public class ExampleHealthCheck : IHealthCheck
    {
        private readonly string _data1;
        private readonly int? _data2;
    
        public ExampleHealthCheck(string data1, int? data2)
        {
            _data1 = data1 ?? throw new ArgumentNullException(nameof(data1));
            _data2 = data2 ?? throw new ArgumentNullException(nameof(data2));
        }
    
        public async Task<HealthCheckResult> CheckHealthAsync(
            HealthCheckContext context, CancellationToken cancellationToken)
        {
            try
            {
                return HealthCheckResult.Healthy();
            }
            catch (AccessViolationException ex)
            {
                return new HealthCheckResult(
                    context.Registration.FailureStatus,
                    description: "An access violation occurred during the check.",
                    exception: ex,
                    data: null);
            }
        }
    }
    
  2. Napište rozšiřující metodu s parametry, které spotřebovávající aplikace volá ve své Startup.Configure metodě. V následujícím příkladu předpokládejme následující signaturu metody kontroly stavu:

    ExampleHealthCheck(string, string, int )
    

    Předchozí signatura označuje, že ke zpracování logiky sondy kontroly stavu vyžaduje další ExampleHealthCheck data. Data se předá delegátovi použitému k vytvoření instance kontroly stavu při registraci kontroly stavu pomocí metody rozšíření. V následujícím příkladu volající určuje volitelné:

    • název kontroly stavu ( name ). Pokud null se example_health_check použije ,
    • datový bod řetězce pro kontrolu stavu ( data1 ).
    • celočíselný datový bod pro kontrolu stavu ( data2 ). Pokud null se 1 použije ,
    • failure status ( HealthStatus ). Výchozí formát je null. Pokud null , je hlášen stav HealthStatus.Unhealthy selhání.
    • tags ( IEnumerable<string> ).
    using System.Collections.Generic;
    using Microsoft.Extensions.Diagnostics.HealthChecks;
    
    public static class ExampleHealthCheckBuilderExtensions
    {
        const string DefaultName = "example_health_check";
    
        public static IHealthChecksBuilder AddExampleHealthCheck(
            this IHealthChecksBuilder builder,
            string name = default,
            string data1,
            int data2 = 1,
            HealthStatus? failureStatus = default,
            IEnumerable<string> tags = default)
        {
            return builder.Add(new HealthCheckRegistration(
                name ?? DefaultName,
                sp => new ExampleHealthCheck(data1, data2),
                failureStatus,
                tags));
        }
    }
    

Kontrola stavu Publisher

Když se do kontejneru služby přidá , systém kontroly stavu pravidelně provádí kontroly stavu a volá s IHealthCheckPublisher PublishAsync výsledkem. To je užitečné ve scénáři systému monitorování stavu založeném na nabízených oznámeních, který očekává, že každý proces bude pravidelně volat monitorovací systém za účelem zjištění stavu.

Rozhraní IHealthCheckPublisher má jednu metodu:

Task PublishAsync(HealthReport report, CancellationToken cancellationToken);

HealthCheckPublisherOptions umožňuje nastavit:

  • Delay: Počáteční zpoždění, ke kterým došlo po spuštění aplikace před spuštěním IHealthCheckPublisher instancí. Zpoždění se použije jednou při spuštění a nevztahuje se na následné iterace. Výchozí hodnota je pět sekund.
  • Period: Doba IHealthCheckPublisher provádění. Výchozí hodnota je 30 sekund.
  • Predicate: Pokud Predicate je null (výchozí), služba vydavatele kontroly stavu spustí všechny registrované kontroly stavu. Pokud chcete spustit podmnožinu kontrol stavu, zadejte funkci, která filtruje sadu kontrol. Predikátu se vyhodnocuje každé období.
  • Timeout: Časový limit pro provádění kontrol stavu pro IHealthCheckPublisher všechny instance. Příkaz InfiniteTimeSpan slouží k provedení bez časového limitu. Výchozí hodnota je 30 sekund.

Upozornění

Ve verzi ASP.NET Core 2.2 není nastavení implementací ctěné; nastavuje Period IHealthCheckPublisher hodnotu Delay . Tento problém byl vyřešen ve ASP.NET Core 3.0.

V ukázkové aplikaci ReadinessPublisher je IHealthCheckPublisher implementace. Stav kontroly stavu se zaprotokoluje pro každou kontrolu jako:

public class ReadinessPublisher : IHealthCheckPublisher
{
    private readonly ILogger _logger;

    public ReadinessPublisher(ILogger<ReadinessPublisher> logger)
    {
        _logger = logger;
    }

    // The following example is for demonstration purposes only. Health Checks 
    // Middleware already logs health checks results. A real-world readiness 
    // check in a production app might perform a set of more expensive or 
    // time-consuming checks to determine if other resources are responding 
    // properly.
    public Task PublishAsync(HealthReport report, 
        CancellationToken cancellationToken)
    {
        if (report.Status == HealthStatus.Healthy)
        {
            _logger.LogInformation("{Timestamp} Readiness Probe Status: {Result}", 
                DateTime.UtcNow, report.Status);
        }
        else
        {
            _logger.LogError("{Timestamp} Readiness Probe Status: {Result}", 
                DateTime.UtcNow, report.Status);
        }

        cancellationToken.ThrowIfCancellationRequested();

        return Task.CompletedTask;
    }
}

V příkladu ukázkové aplikace má kontrola připravenosti dvě sekundy zpoždění při spuštění a spouští kontrolu LivenessProbeStartup StartupHostedService každých 30 sekund. K IHealthCheckPublisher aktivaci implementace se ukázka zaregistruje jako jednosměnná služba v kontejneru injektáže ReadinessPublisher závislostí:

public void ConfigureServices(IServiceCollection services)
{
    services.AddHostedService<StartupHostedService>();
    services.AddSingleton<StartupHostedServiceHealthCheck>();

    services.AddHealthChecks()
        .AddCheck<StartupHostedServiceHealthCheck>(
            "hosted_service_startup", 
            failureStatus: HealthStatus.Degraded, 
            tags: new[] { "ready" });

    services.Configure<HealthCheckPublisherOptions>(options =>
    {
        options.Delay = TimeSpan.FromSeconds(2);
        options.Predicate = (check) => check.Tags.Contains("ready");
    });

    // The following workaround permits adding an IHealthCheckPublisher 
    // instance to the service container when one or more other hosted 
    // services have already been added to the app. This workaround
    // won't be required with the release of ASP.NET Core 3.0. For more 
    // information, see: https://github.com/aspnet/Extensions/issues/639.
    services.TryAddEnumerable(
        ServiceDescriptor.Singleton(typeof(IHostedService), 
            typeof(HealthCheckPublisherOptions).Assembly
                .GetType(HealthCheckServiceAssembly)));

    services.AddSingleton<IHealthCheckPublisher, ReadinessPublisher>();
}

Poznámka

Následující alternativní řešení umožňuje přidat instanci do kontejneru služby, pokud už byla do aplikace přidána jedna nebo více IHealthCheckPublisher hostovaných služeb. Toto alternativní řešení se ve ASP.NET Core 3.0 nevyžaduje.

private const string HealthCheckServiceAssembly =
    "Microsoft.Extensions.Diagnostics.HealthChecks.HealthCheckPublisherHostedService";

services.TryAddEnumerable(
    ServiceDescriptor.Singleton(typeof(IHostedService),
        typeof(HealthCheckPublisherOptions).Assembly
            .GetType(HealthCheckServiceAssembly)));

Poznámka

AspNetCore.Diagnostics.HealthChecksobsahuje vydavatele pro několik systémů, včetně aplikací Přehledy.

AspNetCore.Diagnostics.HealthChecks není udržováno ani podporováno společností Microsoft.

Omezení kontrol stavu pomocí mapyKdyž

Pomocí MapWhen můžete podmíněně rozvětvení kanálu žádosti o koncové body kontroly stavu.

V následujícím příkladu vytvoří větve kanálu požadavku pro aktivaci middlewaru kontroly stavu, pokud je pro koncový bod MapWhen přijat api/HealthCheck požadavek GET:

app.MapWhen(
    context => context.Request.Method == HttpMethod.Get.Method && 
        context.Request.Path.StartsWith("/api/HealthCheck"),
    builder => builder.UseHealthChecks());

app.UseMvc();

Další informace naleznete v tématu ASP.NET Core Jiné.