Kontroly stavu v ASP.NET Core

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:

• Vytvoří databázi a v souboru poskytne připojovací řetězec appsettings.json .
• Obsahuje následující odkazy na balíček v souboru projektu:
  • AspNetCore.HealthChecks.SqlServer
  • Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

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
• Přizpůsobení stavového kódu HTTP
• Potlačit hlavičky mezipaměti
• Přizpůsobení výstupu

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.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 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.

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

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é:

• Použijte jádro Entity Framework (EF).
• Zahrnout odkaz na balíček do Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore .

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

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

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

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:

• Informace ( LogInformation ), pokud je stav kontrol stavu Healthy .
• Error ( LogError ), pokud je stav buď Degraded nebo Unhealthy .

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

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:

• Vytvoří databázi a v souboru poskytne připojovací řetězec appsettings.json .
• Obsahuje následující odkazy na balíček v souboru projektu:
  • AspNetCore.HealthChecks.SqlServer
  • Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

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
• Přizpůsobení stavového kódu HTTP
• Potlačit hlavičky mezipaměti
• Přizpůsobení výstupu

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žívat 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 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.

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

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é:

• Použijte jádro Entity Framework (EF).
• Zahrnout odkaz na balíček do Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore .

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

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 vytvářejí v ukázkové aplikaci v Startup.Configure . 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
    });
}

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

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

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

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

• Informace ( LogInformation ), pokud je stav kontroly stavu Healthy .
• Chyba ( LogError ), pokud je stav nebo Degraded Unhealthy .

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í:

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

Omezení kontrol stavu pomocí mapyKdyž

Slouží MapWhen k podmíněnému 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.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
});

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

ASP.NET Core nabízí middleware a knihovny kontroly stavu pro hlášení stavu komponent infrastruktury aplikací.

Kontroly stavu aplikace zveřejňuje jako koncové body HTTP. Koncové body kontroly stavu je možné nakonfigurovat pro celou řadu scénářů monitorování v reálném čase:

• Sondy stavu mohou používat orchestrátory kontejnerů a nástroje pro vyrovnávání zatížení ke kontrole stavu aplikace. Orchestrátor kontejnerů může například reagovat na neúspěšnou kontrolu stavu zastavením postupného nasazení nebo restartováním kontejneru. Nástroj pro vyrovnávání zatížení může reagovat na aplikaci, která není v pořádku, tím, že směruje provoz z instance, která selhává, do instance, která je v pořádku.
• U prostředků paměti, disku a dalších fyzických serverů je možné monitorovat stav, který je v pořádku.
• Kontroly stavu mohou testovat závislosti aplikace, jako jsou databáze a externí koncové body služby, a potvrdit tak dostupnost a normální fungování.

Zobrazení nebo stažení ukázkového kódu (stažení)

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

Požadavky

Kontroly stavu se obvykle používají s externí monitorovací službou nebo orchestrátorem kontejnerů ke kontrole stavu aplikace. Před přidáním kontrol stavu do aplikace se rozhodněte, který systém monitorování se má použít. Monitorovací systém určuje, jaké typy kontrol stavu se mají vytvořit a jak nakonfigurovat koncové body.

Odkazovat Microsoft.AspNetCore.App na metabalíčky nebo přidat odkaz na Microsoft.AspNetCore.Diagnostics.HealthChecks balíček.

Ukázková aplikace poskytuje spouštěcí kód pro předvedení kontrol stavu pro několik scénářů. Scénář sondy databáze kontroluje stav připojení k databázi pomocí AspNetCore.Diagnostics.HealthChecks . Scénář sondy DbContext kontroluje databázi pomocí EF Core DbContext . Pokud chcete prozkoumat databázové scénáře, ukázková aplikace:

• Vytvoří databázi a poskytne její připojovací řetězec v appsettings.json souboru .
• Obsahuje v souboru projektu následující odkazy na balíček:
  • AspNetCore.HealthChecks.SqlServer
  • Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

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

Základní sonda stavu

Pro mnoho aplikací stačí ke zjištění stavu aplikace základní konfiguracesondy stavu, která hlásí dostupnost aplikace ke zpracování požadavků (aktivity).

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

Zaregistrujte služby kontroly stavu pomocí AddHealthChecks v Startup.ConfigureServices . Do kanálu zpracování požadavků v přidejte koncový bod middlewaru UseHealthChecks kontroly stavu pomocí Startup.Configure .

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

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

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

Pokud chcete spustit základní scénář 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

Příklad Dockeru

Docker nabízí integrovanou direktivu, kterou je možné použít ke kontrole stavu aplikace, která používá HEALTHCHECK základní konfiguraci kontroly stavu:

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

Vytvoření kontrol stavu

Kontroly stavu se vytvářejí implementací IHealthCheck rozhraní . Metoda CheckHealthAsync vrátí , která označuje stav jako , nebo HealthCheckResult Healthy Degraded 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.

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 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("The check indicates a healthy result."));
        }

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

Registrovat služby kontroly stavu

ExampleHealthCheckTyp se přidá do služby kontroly stavu v Startup.ConfigureServices nástroji AddCheck :

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

Použití middlewaru pro kontroly stavu

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

app.UseHealthChecks("/health");

Pokud by kontroly stavu měly naslouchat na konkrétním portu, použijte přetížení UseHealthChecks pro nastavení portu (popsáno dále v části Filter by port ):

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

Možnosti kontroly stavu

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

• Filtrovat kontroly stavu
• Přizpůsobení stavového kódu HTTP
• Potlačit hlavičky mezipaměti
• Přizpůsobení výstupu

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 :

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č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:

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

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

Přizpůsobení výstupu

ResponseWriterMožnost Získá nebo nastaví delegáta použitý k zápisu odpovědi. Výchozí delegát zapisuje minimální odpověď ve formátu prostého textu s hodnotou řetězce 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 zapisuje minimální odpověď ve formátu prostého textu s hodnotou řetězce HealthReport.Status . Následující vlastní delegát WriteResponse vytvoří výstup vlastní odpovědi 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 kontroly stavu neposkytuje integrovanou 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í. V předchozím příkladu si můžete přizpůsobit, JObject jak je to nutné pro splnění vašich požadavků.

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.

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": "Debug"
    },
    "Console": {
      "IncludeScopes": "true"
    }
  }
}

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

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

Ověřování stavu volání middlewaru v kanálu zpracování aplikace v Startup.Configure :

app.UseHealthChecks("/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

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é:

• Použijte jádro Entity Framework (EF).
• Zahrnout odkaz na balíček do Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore .

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 je součástí AppDbContext AddDbContextCheck služby Startup.ConfigureServices (DbContextHealthStartup. cs) a zaregistruje se jako služba:

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

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

V ukázkové aplikaci UseHealthChecks přidá modul pro kontrolu stavu middleware v Startup.Configure .

app.UseHealthChecks("/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ě. 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.

Tento příklad také vytvoří instanci Publisher (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

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 poskytovateli 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, vytvořte soubor launchSettings.json ve složce Properties.

Následující soubor Properties/launchSettings.json v ukázkové aplikaci není součástí souborů 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.");
        });
    }
}

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

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 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 ,
   • stav selhání ( 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

Při přidání do kontejneru služby 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.

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

• Informace ( LogInformation ), pokud je stav kontroly stavu Healthy .
• Chyba ( LogError ), pokud je stav nebo Degraded Unhealthy .

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

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

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

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 přijat MapWhen 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é.