Hälsokontroller i ASP.NET Core

ASP.NET Core erbjuder middleware för hälsokontroller och bibliotek för rapportering av infrastrukturen för appkomponenter.

Hälsokontroller exponeras av en app som HTTP-slutpunkter. Slutpunkter för hälsokontroll kan konfigureras för olika scenarier för realtidsövervakning:

• Hälsokontroller kan användas av containerorkestreringsverktyg och lastutjämnare för att kontrollera en apps status. En containerorkestrerare kan till exempel svara på en misslyckad hälsokontroll genom att stoppa en rullande distribution eller starta om en container. En lastbalanserare kan reagera på en felaktig app genom att dirigera trafik bort från den misslyckade instansen till en felfri instans.
• Användning av minne, disk och andra fysiska serverresurser kan övervakas för felfri status.
• Hälsokontroller kan testa en apps beroenden, till exempel databaser och externa tjänstslutpunkter, för att bekräfta tillgänglighet och normal funktion.

Hälsokontroller används vanligtvis med en extern övervakningstjänst eller containerorkestreringsverktyg för att kontrollera statusen för en app. Innan du lägger till hälsokontroller i en app ska du bestämma vilket övervakningssystem som ska användas. Övervakningssystemet avgör vilka typer av hälsokontroller som ska skapas och hur deras slutpunkter ska konfigureras.

Grundläggande hälsoavsökning

För många appar räcker det med en grundläggande konfiguration av hälsoavsökningar som rapporterar appens tillgänglighet för att bearbeta begäranden (liveness) för att identifiera appens status.

Den grundläggande konfigurationen registrerar hälsokontrolltjänster och anropar mellanprogrammet Hälsokontroller för att svara på en URL-slutpunkt med ett hälsosvar. Som standard registreras inga specifika hälsokontroller för att testa ett visst beroende eller undersystem. Appen anses vara felfri om den kan svara på url:en för hälsoslutpunkten. Standardsvarsskrivaren skriver HealthStatus som ett klartextsvar till klienten. HealthStatus är HealthStatus.Healthy, HealthStatus.Degradedeller HealthStatus.Unhealthy.

Registrera hälsokontrolltjänster med AddHealthChecks i Program.cs. Skapa en slutpunkt för hälsokontroll genom att anropa MapHealthChecks.

I följande exempel skapas en slutpunkt för hälsokontroll på /healthz:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Stuveriarbetare HEALTHCHECK

Docker erbjuder ett inbyggt HEALTHCHECK direktiv som kan användas för att kontrollera statusen för en app som använder den grundläggande konfigurationen för hälsokontroll:

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

I föregående exempel används curl för att göra en HTTP-begäran till slutpunkten för hälsokontroll på /healthz. curl ingår inte i .NET Linux-containeravbildningarna, men det kan läggas till genom att installera det nödvändiga paketet i Dockerfile. Container som använder bilder baserade på Alpine Linux kan använda den medföljande wget i stället för curl.

Skapa hälsokontroller

Hälsokontroller skapas genom att implementera gränssnittet IHealthCheck. Metoden CheckHealthAsync returnerar ett HealthCheckResult som anger hälsotillståndet som Healthy, Degradedeller Unhealthy. Resultatet skrivs som ett klartextsvar med en konfigurerbar statuskod. Konfigurationen beskrivs i avsnittet Alternativ för hälsokontroll . HealthCheckResult kan också returnera valfria nyckel/värde-par.

I följande exempel visas layouten för en hälsokontroll:

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

        // ...

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

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

Hälsokontrollens logik placeras i CheckHealthAsync -metoden. I föregående exempel anges en dummyvariabel, isHealthy, till true. Om värdet isHealthy för är inställt på falsereturneras statusen HealthCheckRegistration.FailureStatus .

Om CheckHealthAsync genererar ett undantag under kontrollen returneras en ny HealthReportEntry med dess HealthReportEntry.Status inställd på FailureStatus. Den här statusen definieras av AddCheck (se avsnittet Registrera hälsokontrolltjänster ) och innehåller det inre undantag som orsakade kontrollfelet. Description är inställt på undantagets meddelande.

Registrera hälsokontrolltjänster

Om du vill registrera en hälsokontrolltjänst anropar du AddCheck :Program.cs

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

Den AddCheck överlagring som visas i följande exempel anger felstatus (HealthStatus) som ska rapporteras när hälsokontrollen rapporterar ett fel. Om felstatusen är inställd på null (standard) HealthStatus.Unhealthy rapporteras. Den här överbelastningen är ett användbart scenario för biblioteksförfattare, där felstatusen som biblioteket anger tvingas fram av appen när ett hälsokontrollfel uppstår, om hälsokontrollimplementeringen följer inställningen.

Taggar kan användas för att filtrera hälsokontroller. Taggar beskrivs i avsnittet Filterhälsokontroller .

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

AddCheck kan också köra en lambda-funktion. I följande exempel returnerar hälsokontrollen alltid ett felfritt resultat:

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

Anropa AddTypeActivatedCheck för att skicka argument till en hälsokontrollimplementation. I följande exempel accepterar en typaktiverad hälsokontroll ett heltal och en sträng i konstruktorn:

public class SampleHealthCheckWithArgs : IHealthCheck
{
    private readonly int _arg1;
    private readonly string _arg2;

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

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

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

Om du vill registrera föregående hälsokontroll anropar du AddTypeActivatedCheck med heltal och sträng som skickas som argument:

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

Använd ruttning av hälsokontroller

I Program.csanropar du MapHealthChecks på slutpunktsverktyget med slutpunkts-URL:en eller den relativa sökvägen:

app.MapHealthChecks("/healthz");

Kräv värd

Anropa RequireHost för att ange en eller flera tillåtna värdar för slutpunkten för hälsokontroll. Värdar bör vara Unicode i stället för punycode och kan innehålla en port. Om en samling inte tillhandahålls godkänns någon värd:

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

Om du vill begränsa hälsokontrollslutpunkten så att den endast svarar på en specifik port anger du en port i anropet till RequireHost. Den här metoden används vanligtvis i en containermiljö för att exponera en port för övervakningstjänster:

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

Om du vill förhindra att obehöriga klienter förfalskar porten anropar du RequireAuthorization:

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

För mer information, se Värdmatchning i rutter med RequireHost.

Kräv auktorisering

Anropa RequireAuthorization för att köra Authorization Middleware på slutpunkten för hälsokontrollbegäran. En RequireAuthorization överbelastning accepterar en eller flera auktoriseringspolicys. Om en princip inte anges används standardauktoriseringsprincipen:

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

Aktivera CORS (Cross-Origin-förfrågningar)

Även om det inte är vanligt att köra hälsokontroller manuellt från en webbläsare kan CORS Middleware aktiveras genom att anropa RequireCors slutpunkterna för hälsokontroller. Överlagringen RequireCors accepterar ett CORS-policybyggardelegat (CorsPolicyBuilder) eller ett policy-namn. Mer information finns i Aktivera CORS (Cross-Origin Requests) i ASP.NET Core.

Alternativ för hälsokontroll

HealthCheckOptions ge en möjlighet att anpassa beteendet för hälsokontroll:

• Filtrera hälsokontroller
• Anpassa HTTP-statuskoden
• Ignorera cachehuvuden
• Anpassa utdata

Filtrera hälsokontroller

Som standard kör Health Checks Middleware alla registrerade hälsokontroller. Om du vill köra en delmängd av hälsokontroller anger du en funktion som returnerar ett booleskt värde till Predicate alternativet.

I följande exempel visas hur hälsokontrollerna filtreras så att endast de som är taggade med sample körs.

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

Anpassa HTTP-statuskoden

Använd ResultStatusCodes för att anpassa mappningen av hälsostatus till HTTP-statuskoder. Följande StatusCodes tilldelningar är standardvärdena som används av mellanprogrammet. Ändra statuskodvärdena så att de uppfyller dina krav:

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

Ignorera cachehuvuden

AllowCachingResponses styr om Health Checks Middleware lägger till HTTP-huvuden i ett avsökningssvar för att förhindra cachelagring av svar. Om värdet är false (standard) anger eller åsidosätter mellanprogrammet rubrikerna Cache-Control, Expiresoch Pragma för att förhindra cachelagring av svar. Om värdet är trueändrar inte mellanprogrammet cachehuvudena för svaret:

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

Anpassa utdata

Om du vill anpassa utdata från en hälsokontrollrapport anger du HealthCheckOptions.ResponseWriter egenskapen till ett ombud som skriver svaret:

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

Standarddelegaten skriver ett minimalt svar i klartext med strängvärdet HealthReport.Status. Följande anpassade delegat genererar ett anpassat JSON-svar med hjälp av System.Text.Json.

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

    var options = new JsonWriterOptions { Indented = true };

    using var memoryStream = new MemoryStream();
    using (var jsonWriter = new Utf8JsonWriter(memoryStream, options))
    {
        jsonWriter.WriteStartObject();
        jsonWriter.WriteString("status", healthReport.Status.ToString());
        jsonWriter.WriteStartObject("results");

        foreach (var healthReportEntry in healthReport.Entries)
        {
            jsonWriter.WriteStartObject(healthReportEntry.Key);
            jsonWriter.WriteString("status",
                healthReportEntry.Value.Status.ToString());
            jsonWriter.WriteString("description",
                healthReportEntry.Value.Description);
            jsonWriter.WriteStartObject("data");

            foreach (var item in healthReportEntry.Value.Data)
            {
                jsonWriter.WritePropertyName(item.Key);

                JsonSerializer.Serialize(jsonWriter, item.Value,
                    item.Value?.GetType() ?? typeof(object));
            }

            jsonWriter.WriteEndObject();
            jsonWriter.WriteEndObject();
        }

        jsonWriter.WriteEndObject();
        jsonWriter.WriteEndObject();
    }

    return context.Response.WriteAsync(
        Encoding.UTF8.GetString(memoryStream.ToArray()));
}

API:et för hälsokontroller ger inte inbyggt stöd för komplexa JSON-returformat eftersom formatet är specifikt för ditt val av övervakningssystem. Anpassa svaret i föregående exempel efter behov. Mer information om JSON-serialisering med System.Text.Jsonfinns i Serialisera och deserialisera JSON i .NET.

Databasavsökning

En hälsokontroll kan ange en databasfråga som ska köras som ett booleskt test för att ange om databasen svarar normalt.

AspNetCore.Diagnostics.HealthChecksinnehåller ett hälsokontrollbibliotek för ASP.NET Core-appar en hälsokontroll som körs mot en SQL Server-databas. AspNetCore.Diagnostics.HealthChecks kör en SELECT 1 fråga mot databasen för att bekräfta att anslutningen till databasen är felfri.

Om du vill använda den här SQL Server-hälsokontrollen inkluderar du en paketreferens till AspNetCore.HealthChecks.SqlServer NuGet-paketet. I följande exempel registreras SQL Server-hälsokontrollen:

var conStr = builder.Configuration.GetConnectionString("DefaultConnection");
if (string.IsNullOrEmpty(conStr))
{
    throw new InvalidOperationException(
                       "Could not find a connection string named 'DefaultConnection'.");
}
builder.Services.AddHealthChecks()
    .AddSqlServer(conStr);

Entity Framework Core DbContext-avsökning

Kontrollen DbContext bekräftar att appen kan kommunicera med databasen som har konfigurerats för en EF CoreDbContext. Kontrollen DbContext stöds i appar som:

• Använd Entity Framework (EF) Core.
• Inkludera en paketreferens till Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore NuGet-paketet.

AddDbContextCheck registrerar en hälsokontroll för en DbContext. DbContext levereras till metoden som TContext. Det finns en överlagring för att konfigurera felstatus, taggar och en anpassad testfråga.

Som standard:

• Anropar DbContextHealthChecks EF Core-metod i CanConnectAsync. Du kan anpassa vilken åtgärd som körs när du kontrollerar hälsotillståndet med hjälp av AddDbContextCheck metodöverbelastningar.
• Namnet på hälsokontrollen är namnet på typen TContext.

I följande exempel registreras en DbContext och en associerad DbContextHealthCheck:

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

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

Separata beredskaps- och liveness-avsökningar

I vissa värdscenarier används ett par hälsokontroller för att skilja mellan två apptillstånd:

• Beredskap anger om appen körs normalt men inte är redo att ta emot begäranden.
• Liveness anger om en app har kraschat och måste startas om.

Tänk på följande exempel: En app måste ladda ned en stor konfigurationsfil innan den är redo att bearbeta begäranden. Vi vill inte att appen ska startas om om den första nedladdningen misslyckas eftersom appen kan försöka ladda ned filen igen flera gånger. Vi använder en liveness-prob för att beskriva processens aktivitet, inga andra kontroller körs. Vi vill också förhindra att begäranden skickas till appen innan nedladdningen av konfigurationsfilen har slutförts. Vi använder en beredskapsavsökning för att ange tillståndet "inte redo" förrän nedladdningen har slutförts och appen är redo att ta emot begäranden.

Följande bakgrundsaktivitet simulerar en startprocess som tar ungefär 15 sekunder. När uppgiften är klar ställer StartupHealthCheck.StartupCompleted in egenskapen till true.

public class StartupBackgroundService : BackgroundService
{
    private readonly StartupHealthCheck _healthCheck;

    public StartupBackgroundService(StartupHealthCheck healthCheck)
        => _healthCheck = healthCheck;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Simulate the effect of a long-running task.
        await Task.Delay(TimeSpan.FromSeconds(15), stoppingToken);

        _healthCheck.StartupCompleted = true;
    }
}

StartupHealthCheck Rapporterar slutförandet av den långvariga startuppgiften och exponerar egenskapen StartupCompleted som anges av bakgrundstjänsten:

public class StartupHealthCheck : IHealthCheck
{
    private volatile bool _isReady;

    public bool StartupCompleted
    {
        get => _isReady;
        set => _isReady = value;
    }

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

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

Hälsokontrollen registreras med AddCheck i Program.cs tillsammans med den värdtjänsten. Eftersom den värdbaserade tjänsten måste ange egenskapen för hälsokontrollen registreras hälsokontrollen också i tjänstcontainern som en singleton:

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

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

Om du vill skapa två olika slutpunkter för hälsokontroll anropar du MapHealthChecks två gånger:

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

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

I föregående exempel skapas följande slutpunkter för hälsokontroll:

• /healthz/ready för beredskapskontrollen. Beredskapskontrollen filtrerar hälsokontroller till dem som är taggade med ready.
• /healthz/live för liveness-kontrollen. Livskontrollen filtrerar ut alla hälsokontroller genom att returnera false i delegeringen HealthCheckOptions.Predicate. Mer information om hur du filtrerar hälsokontroller finns i Filtrera hälsokontroller i den här artikeln.

Innan startaktiviteten /healthz/ready är klar rapporterar slutpunkten status Unhealthy . När startaktiviteten är klar rapporterar slutpunkten status Healthy . Slutpunkten /healthz/live exkluderar alla kontroller och rapporterar status Healthy för alla anrop.

Kubernetes-exempel

Att använda separata beredskaps- och liveness-kontroller är användbart i en miljö som Kubernetes. I Kubernetes kan en app behöva köra tidskrävande startarbete innan begäranden accepteras, till exempel ett test av den underliggande databastillgängligheten. Med hjälp av separata kontroller kan orkestratorn skilja mellan om appen fungerar men ännu inte är klar eller om appen inte har startats. Mer information om beredskaps- och livenessavsökningar i Kubernetes finns i Konfigurera liveness- och beredskapsavsökningar i Kubernetes-dokumentationen.

Följande exempel visar en konfiguration av en Kubernetes readiness probe:

spec:
  template:
  spec:
    readinessProbe:
      # an http probe
      httpGet:
        path: /healthz/ready
        port: 80
      # length of time to wait for a pod to initialize
      # after pod startup, before applying health checking
      initialDelaySeconds: 30
      timeoutSeconds: 1
    ports:
      - containerPort: 80

Distribuera ett hälsokontrollbibliotek

Så här distribuerar du en hälsokontroll som ett bibliotek:

1. Skriv en hälsokontroll som implementerar IHealthCheck gränssnittet som en fristående klass. Klassen kan förlita sig på beroendeinmatning (DI), typaktivering och namngivna alternativ för åtkomst till konfigurationsdata.

2. Skriv en tilläggsmetod med parametrar som den förbrukande appen anropar i sin Program.cs metod. Överväg följande exempel på hälsokontroll, som accepterar arg1 och arg2 som konstruktorparametrar:

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

   Den föregående signaturen anger att hälsokontrollen kräver anpassade data för att bearbeta logiken för hälsokontrollavsökningen. Data tillhandahålls till ombudet som används för att skapa hälsokontrollinstansen när hälsokontrollen registreras med en tilläggsmetod. I följande exempel anger anroparen:

   • arg1: En heltalsdatapunkt för hälsokontrollen.
   • arg2: Ett strängargument för hälsokontrollen.
   • name: Ett valfritt hälsokontrollnamn. Om nullanvänds ett standardvärde.
   • failureStatus: En valfri HealthStatus, vilken rapporteras vid en misslyckandestatus. Om null, HealthStatus.Unhealthy används.
   • tags: En valfri IEnumerable<string> samling taggar.

   public static class SampleHealthCheckBuilderExtensions
   {
       private const string DefaultName = "Sample";
   
       public static IHealthChecksBuilder AddSampleHealthCheck(
           this IHealthChecksBuilder healthChecksBuilder,
           int arg1,
           string arg2,
           string? name = null,
           HealthStatus? failureStatus = null,
           IEnumerable<string>? tags = default)
       {
           return healthChecksBuilder.Add(
               new HealthCheckRegistration(
                   name ?? DefaultName,
                   _ => new SampleHealthCheckWithArgs(arg1, arg2),
                   failureStatus,
                   tags));
       }
   }
   

Hälsokontrollutgivare

När en IHealthCheckPublisher läggs till i tjänstcontainern, kör hälsokontrollsystemet regelbundet dina hälsokontroller och anropar PublishAsync med resultatet. Den här processen är användbar i ett push-baserat system för hälsoövervakning som förväntar sig att varje process regelbundet anropar övervakningssystemet för att fastställa hälsotillståndet.

HealthCheckPublisherOptions gör att du kan ange:

• Delay: Den inledande fördröjningen som tillämpas efter att appen startar innan exekvering av instanser IHealthCheckPublisher. Fördröjningen tillämpas en gång vid start och gäller inte för senare iterationer. Standardvärdet är fem sekunder.
• Period: Utförandeperioden för IHealthCheckPublisher. Standardvärdet är 30 sekunder.
• Predicate: Om Predicate är null (standardläge) kör hälsokontrollens utgivartjänst alla registrerade hälsokontroller. Om du vill köra en delmängd av hälsokontrollerna anger du en funktion som filtrerar uppsättningen kontroller. Predikatet utvärderas varje period.
• Timeout: Tidsgränsen för att köra hälsokontroller för alla IHealthCheckPublisher instanser. Använd InfiniteTimeSpan för att köra utan tidsgräns. Standardvärdet är 30 sekunder.

I följande exempel visas layouten för en hälsoutgivare:

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

        return Task.CompletedTask;
    }
}

Klassen HealthCheckPublisherOptions tillhandahåller egenskaper för att konfigurera beteendet hos hälsokontrollens publicerare.

I följande exempel registreras en hälsokontrollutgivare som en singleton och konfigurerar HealthCheckPublisherOptions:

builder.Services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = healthCheck => healthCheck.Tags.Contains("sample");
});

builder.Services.AddSingleton<IHealthCheckPublisher, SampleHealthCheckPublisher>();

AspNetCore.Diagnostics.HealthChecks:

• Innehåller utgivare för flera system, inklusive Application Insights.
• Underhålls inte eller stöds inte av Microsoft.

Individuella hälsokontroller

Delay och Period kan ställas in individuellt på var och en HealthCheckRegistration. Det här är användbart när du vill köra vissa hälsokontroller med en annan hastighet än den period som anges i HealthCheckPublisherOptions.

Följande kod anger Delay och Period för SampleHealthCheck1:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks()
   .Add(new HealthCheckRegistration(
       name: "SampleHealthCheck1",
       instance: new SampleHealthCheck(),
       failureStatus: null,
       tags: null,
       timeout: default)
   {
       Delay = TimeSpan.FromSeconds(40),
       Period = TimeSpan.FromSeconds(30)
   });

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Beroendeinmatning och hälsokontroller

Du kan använda dependency injection för att använda en instans av en specifik Type i en hälsokontrollklass. Beroendeinmatning kan vara användbart för att mata in alternativ eller en global konfiguration till en hälsokontroll. Att använda beroendeinmatning är inte ett vanligt scenario för att konfigurera hälsokontroller. Vanligtvis är varje hälsokontroll ganska specifik för det faktiska testet och konfigureras med hjälp av IHealthChecksBuilder tilläggsmetoder.

I följande exempel visas ett exempel på hälsokontroll som hämtar ett konfigurationsobjekt via beroendeinmatning:

public class SampleHealthCheckWithDI : IHealthCheck
{
    private readonly SampleHealthCheckWithDiConfig _config;

    public SampleHealthCheckWithDI(SampleHealthCheckWithDiConfig config)
        => _config = config;

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        var isHealthy = true;

        // use _config ...

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

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

SampleHealthCheckWithDiConfig och hälsokontrollen behöver läggas till i tjänstcontainern:

builder.Services.AddSingleton<SampleHealthCheckWithDiConfig>(new SampleHealthCheckWithDiConfig
{
    BaseUriToCheck = new Uri("https://sample.contoso.com/api/")
});
builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheckWithDI>(
        "With Dependency Injection",
        tags: new[] { "inject" });

UseHealthChecks jämfört med MapHealthChecks

Det finns två sätt att göra hälsokontroller tillgängliga för uppringare:

• UseHealthChecks registrerar mellanvara för att hantera hälsokontrollförfrågningar i mellanvarurörledningen.
• MapHealthChecks registrerar en slutpunkt för hälsokontroller. Slutpunkten matchas och körs tillsammans med andra slutpunkter i appen.

Fördelen med att använda MapHealthChecks över UseHealthChecks är möjligheten att använda slutpunktsmedvetna mellanprogram, till exempel auktorisering, och att ha större detaljerad kontroll över matchningsprincipen. Den främsta fördelen med att använda UseHealthChecks över MapHealthChecks är att kontrollera exakt var hälsokontroller körs i pipelinen för mellanprogram.

UseHealthChecks:

• Avslutar pipelinen när en begäran matchar slutpunkten för hälsokontroll. Kortslutning är ofta önskvärt eftersom det undviker onödigt arbete, till exempel loggning och andra mellanprogram.
• Används främst för att konfigurera mellanprogrammet för hälsokontroll i pipelinen.
• Kan matcha valfri sökväg på en port med en null eller tom PathString. Tillåter att du utför en hälsokontroll på alla begäranden som görs till den angivna porten.
• Källkod

MapHealthChecks Tillåter:

• Avsluta pipelinen när en begäran matchar slutpunkten för hälsokontroll genom att anropa ShortCircuit. Till exempel app.MapHealthChecks("/healthz").ShortCircuit();. Mer information finns i Kortslutning mellanprogram efter routning.
• Mappa specifika vägar eller slutpunkter för hälsokontroller.
• Anpassning av URL:en eller sökvägen där slutpunkten för hälsokontroll är tillgänglig.
• Mappa flera slutpunkter för hälsokontroll med olika vägar eller konfigurationer. Stöd för flera slutpunkter:
  • Aktiverar separata slutpunkter för olika typer av hälsokontroller eller komponenter.
  • Används för att skilja mellan olika aspekter av appens hälsa eller tillämpa specifika konfigurationer på delmängder av hälsokontroller.
• Källkod

Ytterligare resurser

• Visa eller ladda ned exempelkod (hur du laddar ned)

ASP.NET Core erbjuder middleware för hälsokontroller och bibliotek för rapportering av infrastrukturen för appkomponenter.

Hälsokontroller exponeras av en app som HTTP-slutpunkter. Slutpunkter för hälsokontroll kan konfigureras för olika scenarier för realtidsövervakning:

• Hälsokontroller kan användas av containerorkestreringsverktyg och lastutjämnare för att kontrollera en apps status. En containerorkestrerare kan till exempel svara på en misslyckad hälsokontroll genom att stoppa en rullande distribution eller starta om en container. En lastbalanserare kan reagera på en felaktig app genom att dirigera trafik bort från den misslyckade instansen till en felfri instans.
• Användning av minne, disk och andra fysiska serverresurser kan övervakas för felfri status.
• Hälsokontroller kan testa en apps beroenden, till exempel databaser och externa tjänstslutpunkter, för att bekräfta tillgänglighet och normal funktion.

Visa eller ladda ned exempelkod (hur du laddar ned)

Exempelappen innehåller exempel på scenarier som beskrivs i den här artikeln. Om du vill köra exempelappen för ett visst scenario använder du kommandot dotnet run från projektets mapp i ett kommandogränssnitt. Mer information om hur du använder exempelappen finns i exempelappens README.md fil och scenariobeskrivningarna i den här artikeln.

Prerequisites

Hälsokontroller används vanligtvis med en extern övervakningstjänst eller containerorkestreringsverktyg för att kontrollera statusen för en app. Innan du lägger till hälsokontroller i en app ska du bestämma vilket övervakningssystem som ska användas. Övervakningssystemet avgör vilka typer av hälsokontroller som ska skapas och hur deras slutpunkter ska konfigureras.

Paketet Microsoft.AspNetCore.Diagnostics.HealthChecks refereras implicit för ASP.NET Core-appar. Om du vill köra hälsokontroller med Entity Framework Core lägger du till en referens till Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore paketet.

Exempelappen tillhandahåller startkod för att demonstrera hälsokontroller för flera scenarier. Scenariot med databasavsökningen kontrollerar hälsotillståndet för en databasanslutning med hjälp av AspNetCore.Diagnostics.HealthChecks. DbContext-avsökningsscenariot kontrollerar en databas med hjälp av en EF CoreDbContext. Exempelappen utforskar databasscenarierna:

• Skapar en databas och tillhandahåller dess anslutningssträng i appsettings.json filen.
• Har följande paketreferenser i projektfilen:
  • AspNetCore.HealthChecks.SqlServer
  • Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

Ett annat hälsogranskningsscenario visar hur du filtrerar hälsogranskningar till en administrationsport. Exempelappen kräver att du skapar en Properties/launchSettings.json fil som innehåller hanterings-URL:en och hanteringsporten. Mer information finns i avsnittet Filtrera efter port .

Grundläggande hälsoavsökning

För många appar räcker det med en grundläggande konfiguration av hälsoavsökningar som rapporterar appens tillgänglighet för att bearbeta begäranden (liveness) för att identifiera appens status.

Den grundläggande konfigurationen registrerar hälsokontrolltjänster och anropar mellanprogrammet Hälsokontroller för att svara på en URL-slutpunkt med ett hälsosvar. Som standard registreras inga specifika hälsokontroller för att testa ett visst beroende eller undersystem. Appen anses vara felfri om den kan svara på url:en för hälsoslutpunkten. Standardsvarsskrivaren skriver statusen (HealthStatus) som ett svar i klartext tillbaka till klienten, vilket anger antingen statusen HealthStatus.Healthy, HealthStatus.Degradedeller HealthStatus.Unhealthy .

Registrera hälsokontrolltjänster med AddHealthChecks i Startup.ConfigureServices. Skapa en slutpunkt för hälsokontroll genom att anropa MapHealthChecks i Startup.Configure.

I exempelappen skapas slutpunkten för hälsokontroll på /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");
        });
    }
}

Kör följande kommando från projektets mapp i ett kommandogränssnitt för att köra det grundläggande konfigurationsscenariot med exempelappen:

dotnet run --scenario basic

Docker-exempel

Docker erbjuder ett inbyggt HEALTHCHECK direktiv som kan användas för att kontrollera statusen för en app som använder den grundläggande konfigurationen för hälsokontroll:

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

Skapa hälsokontroller

Hälsokontroller skapas genom att implementera gränssnittet IHealthCheck. Metoden CheckHealthAsync returnerar ett HealthCheckResult som anger hälsotillståndet som Healthy, Degradedeller Unhealthy. Resultatet skrivs som ett klartextsvar med en konfigurerbar statuskod (konfigurationen beskrivs i avsnittet Hälsokontrollalternativ ). HealthCheckResult kan också returnera valfria nyckel/värde-par.

Följande ExampleHealthCheck klass visar layouten för en hälsokontroll. Logiken för hälsokontroller placeras i CheckHealthAsync -metoden. I följande exempel anges en dummyvariabel, healthCheckResultHealthy, till true. Om värdet healthCheckResultHealthy för är inställt på falsereturneras statusen HealthCheckRegistration.FailureStatus .

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

Om CheckHealthAsync genererar ett undantag under kontrollen returneras en ny HealthReportEntry med dess HealthReportEntry.Status uppsättning till FailureStatus, som definieras av AddCheck (se avsnittet Registrera hälsokontrolltjänster ) och innehåller det inre undantaget som ursprungligen orsakade kontrollfelet. Description är inställt på undantagets meddelande.

Registrera hälsokontrolltjänster

Typen ExampleHealthCheck läggs till i hälsokontrolltjänster med AddCheck i Startup.ConfigureServices:

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

Den AddCheck överlagring som visas i följande exempel anger felstatus (HealthStatus) som ska rapporteras när hälsokontrollen rapporterar ett fel. Om felstatusen är inställd på null (standard) HealthStatus.Unhealthy rapporteras. Den här överbelastningen är ett användbart scenario för biblioteksförfattare, där felstatusen som biblioteket anger tvingas fram av appen när ett hälsokontrollfel uppstår, om hälsokontrollimplementeringen följer inställningen.

Taggar kan användas för att filtrera hälsokontroller (beskrivs ytterligare i avsnittet Filterhälsokontroller ).

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

AddCheck kan också köra en lambda-funktion. I följande exempel anges hälsokontrollnamnet som Example och kontrollen returnerar alltid ett felfritt tillstånd:

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

Anropa AddTypeActivatedCheck för att skicka argument till en hälsokontrollimplementation. I följande exempel TestHealthCheckWithArgs accepterar ett heltal och en sträng för användning när CheckHealthAsync anropas:

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 registreras genom att anropa AddTypeActivatedCheck med heltal och sträng som skickas till implementeringen:

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

Använd ruttning av hälsokontroller

I Startup.Configureanropar du MapHealthChecks på slutpunktsverktyget med slutpunkts-URL:en eller den relativa sökvägen:

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

Kräv värd

Anropa RequireHost för att ange en eller flera tillåtna värdar för slutpunkten för hälsokontroll. Värdar bör vara Unicode i stället för punycode och kan innehålla en port. Om ingen samling tillhandahålls accepteras vilken värd som helst.

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

Mer information finns i avsnittet Filtrera efter port .

Kräv auktorisering

Anropa RequireAuthorization för att köra Authorization Middleware på slutpunkten för hälsokontrollbegäran. En RequireAuthorization överbelastning accepterar en eller flera auktoriseringspolicys. Om en princip inte anges används standardauktoriseringsprincipen.

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

Aktivera CORS (Cross-Origin-förfrågningar)

Även om det inte är vanligt att köra hälsokontroller manuellt från en webbläsare kan CORS Middleware aktiveras genom att anropa RequireCors slutpunkter för hälsokontroller. En RequireCors överbelastning accepterar ett CORS-policybyggardelegat (CorsPolicyBuilder) eller ett policy-namn. Om en princip inte tillhandahålls används standardprincipen för CORS. Mer information finns i Aktivera CORS (Cross-Origin Requests) i ASP.NET Core.

Alternativ för hälsokontroll

HealthCheckOptions ge en möjlighet att anpassa beteendet för hälsokontroll:

• Filtrera hälsokontroller
• Anpassa HTTP-statuskoden
• Ignorera cachehuvuden
• Anpassa utdata

Filtrera hälsokontroller

Som standard kör Health Checks Middleware alla registrerade hälsokontroller. Om du vill köra en delmängd av hälsokontroller anger du en funktion som returnerar ett booleskt värde till Predicate alternativet. I följande exempel Bar filtreras hälsokontrollen ut med dess tagg (bar_tag) i funktionens villkorssats, där true returneras endast om hälsokontrollens Tags egenskap matchar foo_tag eller baz_tag:

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

I Startup.Configure filtreras hälsokontrollen "Bar" bort av Predicate. Endast Foo och Baz kör:

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

Anpassa HTTP-statuskoden

Använd ResultStatusCodes för att anpassa mappningen av hälsostatus till HTTP-statuskoder. Följande StatusCodes tilldelningar är standardvärdena som används av mellanprogrammet. Ändra statuskodvärdena så att de uppfyller dina krav.

I Startup.Configure:

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

Ignorera cachehuvuden

AllowCachingResponses styr om Health Checks Middleware lägger till HTTP-huvuden i ett avsökningssvar för att förhindra cachelagring av svar. Om värdet är false (standard) anger eller åsidosätter mellanprogrammet rubrikerna Cache-Control, Expiresoch Pragma för att förhindra cachelagring av svar. Om värdet är trueändrar inte mellanprogrammet cachehuvudena för svaret.

I Startup.Configure:

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

Anpassa utdata

Ange i Startup.Configure alternativet HealthCheckOptions.ResponseWriter till en ombud för att skriva svaret:

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

Standarddelegaten skriver ett minimalt svar i klartext med strängvärdet HealthReport.Status. Följande anpassade ombud matar ut ett anpassat JSON-svar.

Det första exemplet från exempelappen visar hur du använder 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);
    }
}

Det andra exemplet visar hur du använder 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));
}

I exempelappen kommenterar du ut SYSTEM_TEXT_JSONförprocessordirektivet i CustomWriterStartup.cs för att aktivera Newtonsoft.Json versionen av WriteResponse.

API:et för hälsokontroller ger inte inbyggt stöd för komplexa JSON-returformat eftersom formatet är specifikt för ditt val av övervakningssystem. Anpassa svaret i föregående exempel efter behov. Mer information om JSON-serialisering med System.Text.Jsonfinns i Serialisera och deserialisera JSON i .NET.

Databasavsökning

En hälsokontroll kan ange en databasfråga som ska köras som ett booleskt test för att ange om databasen svarar normalt.

Exempelappen använder AspNetCore.Diagnostics.HealthChecks, ett hälsokontrollbibliotek för ASP.NET Core-appar, för att köra en hälsokontroll på en SQL Server-databas. AspNetCore.Diagnostics.HealthChecks kör en SELECT 1 fråga mot databasen för att bekräfta att anslutningen till databasen är felfri.

Inkludera en paketreferens till AspNetCore.HealthChecks.SqlServer.

Ange en giltig databasanslutningssträng i appsettings.json exempelappens fil. Appen använder en SQL Server-databas med namnet 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": "*"
}

Registrera hälsokontrolltjänster med AddHealthChecks i Startup.ConfigureServices. Exempelappen AddSqlServer anropar metoden med databasens anslutningssträng (DbHealthStartup.cs):

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

En slutpunkt för hälsokontroll skapas genom att anropa MapHealthChecks i Startup.Configure:

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

Kör följande kommando från projektets mapp i ett kommandogränssnitt för att köra scenariot med databasavsökningen med exempelappen:

dotnet run --scenario db

Entity Framework Core DbContext-avsökning

Kontrollen DbContext bekräftar att appen kan kommunicera med databasen som har konfigurerats för en EF CoreDbContext. Kontrollen DbContext stöds i appar som:

• Använd Entity Framework (EF) Core.
• Inkludera en paketreferens till Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore.

AddDbContextCheck<TContext> registrerar en hälsokontroll för en DbContext. DbContext Anges som TContext till -metoden. Det finns en överlagring för att konfigurera felstatus, taggar och en anpassad testfråga.

Som standard:

• Anropar DbContextHealthChecks EF Core-metod i CanConnectAsync. Du kan anpassa vilken åtgärd som körs när du kontrollerar hälsotillståndet med hjälp av AddDbContextCheck metodöverbelastningar.
• Namnet på hälsokontrollen är namnet på typen TContext.

I exempelappen AppDbContext tillhandahålls AddDbContextCheck och registreras som en tjänst i Startup.ConfigureServices (DbContextHealthStartup.cs):

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

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

En slutpunkt för hälsokontroll skapas genom att anropa MapHealthChecks i Startup.Configure:

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

Om du vill köra avsökningsscenariot DbContext med exempelappen kontrollerar du att databasen som anges av anslutningssträngen inte finns i SQL Server-instansen. Om databasen finns tar du bort den.

Kör följande kommando från projektets mapp i ett kommandogränssnitt:

dotnet run --scenario dbcontext

När appen har körts kontrollerar du hälsostatusen genom att göra en begäran till /health slutpunkten i en webbläsare. Databasen och AppDbContext finns inte, så appen ger följande svar:

Unhealthy

Utlös exempelappen för att skapa databasen. Skicka en begäran till /createdatabase. Appen svarar:

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

Skicka en begäran till /health slutpunkten. Databasen och kontexten finns, så appen svarar:

Healthy

Utlös exempelappen för att ta bort databasen. Skicka en begäran till /deletedatabase. Appen svarar:

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

Skicka en begäran till /health slutpunkten. Appen ger ett ohälsosamt svar:

Unhealthy

Separata beredskaps- och liveness-avsökningar

I vissa värdscenarier används ett par hälsokontroller för att skilja mellan två apptillstånd:

• Beredskap anger om appen körs normalt men inte är redo att ta emot begäranden.
• Liveness anger om en app har kraschat och måste startas om.

Tänk på följande exempel: En app måste ladda ned en stor konfigurationsfil innan den är redo att bearbeta begäranden. Vi vill inte att appen ska startas om om den första nedladdningen misslyckas eftersom appen kan försöka ladda ned filen igen flera gånger. Vi använder en liveness-prob för att beskriva processens aktivitet, inga andra kontroller körs. Vi vill också förhindra att begäranden skickas till appen innan nedladdningen av konfigurationsfilen har slutförts. Vi använder en beredskapsavsökning för att ange tillståndet "inte redo" förrän nedladdningen har slutförts och appen är redo att ta emot begäranden.

Exempelappen innehåller en hälsokontroll för att rapportera när en långvarig startuppgift är slutförd i en hostad tjänst. StartupHostedServiceHealthCheck Exponerar en egenskap, StartupTaskCompleted, som den värdbaserade tjänsten kan ställa in på true när dess långvariga uppgift är klar (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."));
    }
}

Den långkörande bakgrundsprocessen startas av en hostad tjänst (Services/StartupHostedService). När arbetsuppgiften är avslutad, ställs StartupHostedServiceHealthCheck.StartupTaskCompleted in på 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()
    {
    }
}

Hälsokontrollen registreras med AddCheck i Startup.ConfigureServices tillsammans med den värdtjänsten. Eftersom den värdbaserade tjänsten måste ange egenskapen för hälsokontrollen registreras även hälsokontrollen i tjänstcontainern (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>();

En slutpunkt för hälsokontroll skapas genom att anropa MapHealthChecks i Startup.Configure. I exempelappen skapas slutpunkterna för hälsokontroll på:

• /health/ready för beredskapskontrollen. Beredskapskontrollen filtrerar hälsokontrollerna till hälsokontrollen med taggen ready.
• /health/live för liveness-kontrollen. Liveness-kontrollen filtrerar ut StartupHostedServiceHealthCheck genom att returnera false i HealthCheckOptions.Predicate (för mer information, se Filtrera hälsokontroller)

I följande exempelkod:

• Beredskapskontrollen använder alla registrerade kontroller med taggen "klar".
• Predicate utesluter alla kontroller och returnerar 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
    });
}

För att köra konfigurationsscenariot för beredskap/livbarhet med hjälp av exempelappen, kör följande kommando från projektets mapp i ett kommandoskal:

dotnet run --scenario liveness

I en webbläsare besöker du /health/ready flera gånger tills 15 sekunder har passerat. Hälsokontrollrapporter visas Unhealthy under de första 15 sekunderna. Efter 15 sekunder rapporterar slutpunkten Healthy, vilket återspeglar slutförandet av den långvariga uppgiften av värdtjänsten.

Det här exemplet skapar också en Health Check Publisher (IHealthCheckPublisher implementering) som kör den första beredskapskontrollen med två sekunders fördröjning. Mer information finns i avsnittet Hälsokontrollutgivare .

Kubernetes-exempel

Att använda separata beredskaps- och liveness-kontroller är användbart i en miljö som Kubernetes. I Kubernetes kan en app behöva köra tidskrävande startarbete innan begäranden accepteras, till exempel ett test av den underliggande databastillgängligheten. Med hjälp av separata kontroller kan orkestratorn skilja mellan om appen fungerar men ännu inte är klar eller om appen inte har startats. Mer information om beredskaps- och livenessavsökningar i Kubernetes finns i Konfigurera liveness- och beredskapsavsökningar i Kubernetes-dokumentationen.

Följande exempel visar en konfiguration av en Kubernetes readiness probe:

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

Måttbaserad avsökning med en anpassad svarsskrivare

Exempelappen visar en minneshälsokontroll med en anpassad svarsskrivare.

MemoryHealthCheck rapporterar en degraderad status om appen använder mer än ett visst tröskelvärde för minne (1 GB i exempelappen). HealthCheckResult innehåller information om Garbage Collector (GC) för appen (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));
    }
}

Registrera hälsokontrolltjänster med AddHealthChecks i Startup.ConfigureServices. I stället för att aktivera hälsokontrollen genom att skicka den till AddCheckregistreras den MemoryHealthCheck som en tjänst. Alla IHealthCheck registrerade tjänster är tillgängliga för hälsokontrolltjänster och mellanprogram. Vi rekommenderar att du registrerar hälsokontrolltjänster som Singleton-tjänster.

Inom CustomWriterStartup.cs exempelappen:

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

En slutpunkt för hälsokontroll skapas genom att anropa MapHealthChecks i Startup.Configure. Ett WriteResponse ombud tillhandahålls till ResponseWriter egenskapen för att mata ut ett anpassat JSON-svar när hälsokontrollen körs:

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

Ombudet WriteResponse formaterar CompositeHealthCheckResult till ett JSON-objekt och ger JSON-utdata för hälsokontrollsvaret. Mer information finns i avsnittet Anpassa utdata .

Kör följande kommando från projektets mapp i ett kommandogränssnitt för att köra den måttbaserade avsökningen med anpassade svarsskrivareutdata med hjälp av exempelappen:

dotnet run --scenario writer

Filtrera efter port

RequireHost Anropa MapHealthChecks med ett URL-mönster som anger en port för att begränsa hälsokontrollbegäranden till den angivna porten. Den här metoden används vanligtvis i en containermiljö för att exponera en port för övervakningstjänster.

Exempelappen konfigurerar porten med hjälp av miljövariabelkonfigurationsprovidern. Porten anges i launchSettings.json filen och skickas till konfigurationsprovidern via en miljövariabel. Du måste också konfigurera servern för att lyssna på begäranden på hanteringsporten.

Om du vill använda exempelappen för att demonstrera konfigurationen av hanteringsporten skapar du launchSettings.json filen i en Properties mapp.

Följande Properties/launchSettings.json fil i exempelappen ingår inte i exempelappens projektfiler och måste skapas manuellt:

{
  "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/"
    }
  }
}

Registrera hälsokontrolltjänster med AddHealthChecks i Startup.ConfigureServices. Skapa en slutpunkt för hälsokontroll genom att anropa MapHealthChecks i Startup.Configure.

I exempelappen anger ett anrop till RequireHost på slutpunkten i Startup.Configure hanteringsporten från konfigurationen:

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

Slutpunkter skapas i exempelappen i Startup.Configure. I följande exempelkod:

• Beredskapskontrollen använder alla registrerade kontroller med taggen "klar".
• Predicate utesluter alla kontroller och returnerar 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");
});

Kör följande kommando från projektets mapp i ett kommandogränssnitt för att köra konfigurationsscenariot för hanteringsporten med hjälp av exempelappen:

dotnet run --scenario port

Distribuera ett hälsokontrollbibliotek

Så här distribuerar du en hälsokontroll som ett bibliotek:

1. Skriv en hälsokontroll som implementerar IHealthCheck gränssnittet som en fristående klass. Klassen kan förlita sig på beroendeinmatning (DI), typaktivering och namngivna alternativ för åtkomst till konfigurationsdata.

   I logiken för hälsokontroller i CheckHealthAsync:

   • data1 och data2 används i metoden för att köra probens hälsokontrolllogik.
   • AccessViolationException hanteras.

   När ett AccessViolationException inträffar, så returneras FailureStatus med HealthCheckResult för att låta användare konfigurera statusen för hälsokontroller.

   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. Skriv en tilläggsmetod med parametrar som den förbrukande appen anropar i sin Startup.Configure metod. I följande exempel antar du följande signatur för hälsokontrollmetoden:

   ExampleHealthCheck(string, string, int )
   

   Den föregående signaturen anger att ExampleHealthCheck kräver ytterligare data för att bearbeta logiken för hälsokontrollen. Data tillhandahålls till ombudet som används för att skapa hälsokontrollinstansen när hälsokontrollen registreras med en tilläggsmetod. I följande exempel anger anroparen valfritt:

   • hälsokontrollnamn (name). Om null, example_health_check används.
   • strängdatapunkt för hälsokontrollen (data1).
   • heltalsdatapunkt för hälsokontrollen (data2). Om null, 1 används.
   • felstatus (HealthStatus). Standardvärdet är null. Om null, HealthStatus.Unhealthy rapporteras för en felstatus.
   • taggar (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));
       }
   }
   

Hälsokontrollutgivare

När en IHealthCheckPublisher läggs till i tjänstcontainern, kör hälsokontrollsystemet regelbundet dina hälsokontroller och anropar PublishAsync med resultatet. Detta är användbart i ett push-baserat system för hälsoövervakning som förväntar sig att varje process anropar övervakningssystemet regelbundet för att fastställa hälsotillståndet.

Gränssnittet IHealthCheckPublisher har en enda metod:

Task PublishAsync(HealthReport report, CancellationToken cancellationToken);

HealthCheckPublisherOptions gör att du kan ange:

• Delay: Den inledande fördröjningen som tillämpas efter att appen startar innan exekvering av instanser IHealthCheckPublisher. Fördröjningen tillämpas en gång vid start och gäller inte för efterföljande iterationer. Standardvärdet är fem sekunder.
• Period: Utförandeperioden för IHealthCheckPublisher. Standardvärdet är 30 sekunder.
• Predicate: Om Predicate är null (standardläge) kör hälsokontrollens utgivartjänst alla registrerade hälsokontroller. Om du vill köra en delmängd av hälsokontrollerna anger du en funktion som filtrerar uppsättningen kontroller. Predikatet utvärderas varje period.
• Timeout: Tidsgränsen för att köra hälsokontroller för alla IHealthCheckPublisher instanser. Använd InfiniteTimeSpan för att köra utan tidsgräns. Standardvärdet är 30 sekunder.

I exempelappen är ReadinessPublisher en IHealthCheckPublisher implementation. Hälsokontrollstatusen loggas för varje kontroll på loggnivå:

• Information (LogInformation) om hälsokontrollstatusen är Healthy.
• Fel (LogError) om statusen är antingen Degraded eller 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;
    }
}

I exempelappens exempel LivenessProbeStartup har beredskapskontrollen två sekunders StartupHostedService startfördröjning och kör kontrollen var 30:e sekund. För att aktivera IHealthCheckPublisher-implementationen registrerar provet ReadinessPublisher som en singleton-tjänst i beroendeinjektionscontainern (DI):

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

Begränsa hälsokontroller med MapWhen

Använd MapWhen för att villkorsstyrt förgrena begärandepipelinen för hälsokontrollpunkter.

I följande exempel MapWhen förgrenar du pipelinen för begäran för att aktivera Mellanprogram för hälsokontroller om en GET-begäran tas emot för api/HealthCheck slutpunkten:

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

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

Mer information finns i ASP.NET Core Middleware.

ASP.NET Core erbjuder middleware för hälsokontroller och bibliotek för rapportering av infrastrukturen för appkomponenter.

Hälsokontroller exponeras av en app som HTTP-slutpunkter. Slutpunkter för hälsokontroll kan konfigureras för olika scenarier för realtidsövervakning:

• Hälsokontroller kan användas av containerorkestreringsverktyg och lastutjämnare för att kontrollera en apps status. En containerorkestrerare kan till exempel svara på en misslyckad hälsokontroll genom att stoppa en rullande distribution eller starta om en container. En lastbalanserare kan reagera på en felaktig app genom att dirigera trafik bort från den misslyckade instansen till en felfri instans.
• Användning av minne, disk och andra fysiska serverresurser kan övervakas för felfri status.
• Hälsokontroller kan testa en apps beroenden, till exempel databaser och externa tjänstslutpunkter, för att bekräfta tillgänglighet och normal funktion.

Visa eller ladda ned exempelkod (hur du laddar ned)

Exempelappen innehåller exempel på scenarier som beskrivs i den här artikeln. Om du vill köra exempelappen för ett visst scenario använder du kommandot dotnet run från projektets mapp i ett kommandogränssnitt. Mer information om hur du använder exempelappen finns i exempelappens README.md fil och scenariobeskrivningarna i den här artikeln.

Prerequisites

Hälsokontroller används vanligtvis med en extern övervakningstjänst eller containerorkestreringsverktyg för att kontrollera statusen för en app. Innan du lägger till hälsokontroller i en app ska du bestämma vilket övervakningssystem som ska användas. Övervakningssystemet avgör vilka typer av hälsokontroller som ska skapas och hur deras slutpunkter ska konfigureras.

Paketet Microsoft.AspNetCore.Diagnostics.HealthChecks refereras implicit för ASP.NET Core-appar. Om du vill köra hälsokontroller med Entity Framework Core lägger du till en paketreferens till Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore paketet.

Exempelappen tillhandahåller startkod för att demonstrera hälsokontroller för flera scenarier. Scenariot med databasavsökningen kontrollerar hälsotillståndet för en databasanslutning med hjälp av AspNetCore.Diagnostics.HealthChecks. DbContext-avsökningsscenariot kontrollerar en databas med hjälp av en EF CoreDbContext. Exempelappen utforskar databasscenarierna:

• Skapar en databas och tillhandahåller dess anslutningssträng i appsettings.json filen.
• Har följande paketreferenser i projektfilen:
  • AspNetCore.HealthChecks.SqlServer
  • Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore

Ett annat hälsogranskningsscenario visar hur du filtrerar hälsogranskningar till en administrationsport. Exempelappen kräver att du skapar en Properties/launchSettings.json fil som innehåller hanterings-URL:en och hanteringsporten. Mer information finns i avsnittet Filtrera efter port .

Grundläggande hälsoavsökning

För många appar räcker det med en grundläggande konfiguration av hälsoavsökningar som rapporterar appens tillgänglighet för att bearbeta begäranden (liveness) för att identifiera appens status.

Den grundläggande konfigurationen registrerar hälsokontrolltjänster och anropar mellanprogrammet Hälsokontroller för att svara på en URL-slutpunkt med ett hälsosvar. Som standard registreras inga specifika hälsokontroller för att testa ett visst beroende eller undersystem. Appen anses vara felfri om den kan svara på url:en för hälsoslutpunkten. Standardsvarsskrivaren skriver statusen (HealthStatus) som ett svar i klartext tillbaka till klienten, vilket anger antingen statusen HealthStatus.Healthy, HealthStatus.Degradedeller HealthStatus.Unhealthy .

Registrera hälsokontrolltjänster med AddHealthChecks i Startup.ConfigureServices. Skapa en slutpunkt för hälsokontroll genom att anropa MapHealthChecks i Startup.Configure.

I exempelappen skapas slutpunkten för hälsokontroll på /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");
        });
    }
}

Kör följande kommando från projektets mapp i ett kommandogränssnitt för att köra det grundläggande konfigurationsscenariot med exempelappen:

dotnet run --scenario basic

Docker-exempel

Docker erbjuder ett inbyggt HEALTHCHECK direktiv som kan användas för att kontrollera statusen för en app som använder den grundläggande konfigurationen för hälsokontroll:

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

Skapa hälsokontroller

Hälsokontroller skapas genom att implementera gränssnittet IHealthCheck. Metoden CheckHealthAsync returnerar ett HealthCheckResult som anger hälsotillståndet som Healthy, Degradedeller Unhealthy. Resultatet skrivs som ett klartextsvar med en konfigurerbar statuskod (konfigurationen beskrivs i avsnittet Hälsokontrollalternativ ). HealthCheckResult kan också returnera valfria nyckel/värde-par.

Följande ExampleHealthCheck klass visar layouten för en hälsokontroll. Logiken för hälsokontroller placeras i CheckHealthAsync -metoden. I följande exempel anges en dummyvariabel, healthCheckResultHealthy, till true. Om värdet healthCheckResultHealthy för är inställt på falsereturneras statusen HealthCheckResult.Unhealthy .

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

Registrera hälsokontrolltjänster

Typen ExampleHealthCheck läggs till i hälsokontrolltjänster med AddCheck i Startup.ConfigureServices:

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

Den AddCheck överlagring som visas i följande exempel anger felstatus (HealthStatus) som ska rapporteras när hälsokontrollen rapporterar ett fel. Om felstatusen är inställd på null (standard) HealthStatus.Unhealthy rapporteras. Den här överbelastningen är ett användbart scenario för biblioteksförfattare, där felstatusen som biblioteket anger tvingas fram av appen när ett hälsokontrollfel uppstår, om hälsokontrollimplementeringen följer inställningen.

Taggar kan användas för att filtrera hälsokontroller (beskrivs ytterligare i avsnittet Filterhälsokontroller ).

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

AddCheck kan också köra en lambda-funktion. I följande exempel anges hälsokontrollnamnet som Example och kontrollen returnerar alltid ett felfritt tillstånd:

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

Anropa AddTypeActivatedCheck för att skicka argument till en hälsokontrollimplementation. I följande exempel TestHealthCheckWithArgs accepterar ett heltal och en sträng för användning när CheckHealthAsync anropas:

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 registreras genom att anropa AddTypeActivatedCheck med heltal och sträng som skickas till implementeringen:

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

Använd ruttning av hälsokontroller

I Startup.Configureanropar du MapHealthChecks på slutpunktsverktyget med slutpunkts-URL:en eller den relativa sökvägen:

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

Kräv värd

Anropa RequireHost för att ange en eller flera tillåtna värdar för slutpunkten för hälsokontroll. Värdar bör vara Unicode i stället för punycode och kan innehålla en port. Om ingen samling tillhandahålls accepteras vilken värd som helst.

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

Mer information finns i avsnittet Filtrera efter port .

Kräv auktorisering

Anropa RequireAuthorization för att köra Authorization Middleware på slutpunkten för hälsokontrollbegäran. En RequireAuthorization överbelastning accepterar en eller flera auktoriseringspolicys. Om en princip inte anges används standardauktoriseringsprincipen.

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

Aktivera CORS (Cross-Origin-förfrågningar)

Även om det inte är vanligt att köra hälsokontroller manuellt från en webbläsare kan CORS Middleware aktiveras genom att anropa RequireCors slutpunkter för hälsokontroller. En RequireCors överbelastning accepterar ett CORS-policybyggardelegat (CorsPolicyBuilder) eller ett policy-namn. Om en princip inte tillhandahålls används standardprincipen för CORS. Mer information finns i Aktivera CORS (Cross-Origin Requests) i ASP.NET Core.

Alternativ för hälsokontroll

HealthCheckOptions ge en möjlighet att anpassa beteendet för hälsokontroll:

• Filtrera hälsokontroller
• Anpassa HTTP-statuskoden
• Ignorera cachehuvuden
• Anpassa utdata

Filtrera hälsokontroller

Som standard kör Health Checks Middleware alla registrerade hälsokontroller. Om du vill köra en delmängd av hälsokontroller anger du en funktion som returnerar ett booleskt värde till Predicate alternativet. I följande exempel Bar filtreras hälsokontrollen ut med dess tagg (bar_tag) i funktionens villkorssats, där true returneras endast om hälsokontrollens Tags egenskap matchar foo_tag eller baz_tag:

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

I Startup.Configure filtreras hälsokontrollen "Bar" bort av Predicate. Endast Foo och Baz kör:

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

Anpassa HTTP-statuskoden

Använd ResultStatusCodes för att anpassa mappningen av hälsostatus till HTTP-statuskoder. Följande StatusCodes tilldelningar är standardvärdena som används av mellanprogrammet. Ändra statuskodvärdena så att de uppfyller dina krav.

I Startup.Configure:

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

Ignorera cachehuvuden

AllowCachingResponses styr om Health Checks Middleware lägger till HTTP-huvuden i ett avsökningssvar för att förhindra cachelagring av svar. Om värdet är false (standard) anger eller åsidosätter mellanprogrammet rubrikerna Cache-Control, Expiresoch Pragma för att förhindra cachelagring av svar. Om värdet är trueändrar inte mellanprogrammet cachehuvudena för svaret.

I Startup.Configure:

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

Anpassa utdata

Ange i Startup.Configure alternativet HealthCheckOptions.ResponseWriter till en ombud för att skriva svaret:

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

Standarddelegaten skriver ett minimalt svar i klartext med strängvärdet HealthReport.Status. Följande anpassade ombud matar ut ett anpassat JSON-svar.

Det första exemplet från exempelappen visar hur du använder 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);
    }
}

Det andra exemplet visar hur du använder 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));
}

I exempelappen kommenterar du ut SYSTEM_TEXT_JSONförprocessordirektivet i CustomWriterStartup.cs för att aktivera Newtonsoft.Json versionen av WriteResponse.

API:et för hälsokontroller ger inte inbyggt stöd för komplexa JSON-returformat eftersom formatet är specifikt för ditt val av övervakningssystem. Anpassa svaret i föregående exempel efter behov. Mer information om JSON-serialisering med System.Text.Jsonfinns i Serialisera och deserialisera JSON i .NET.

Databasavsökning

En hälsokontroll kan ange en databasfråga som ska köras som ett booleskt test för att ange om databasen svarar normalt.

Exempelappen använder AspNetCore.Diagnostics.HealthChecks, ett hälsokontrollbibliotek för ASP.NET Core-appar, för att köra en hälsokontroll på en SQL Server-databas. AspNetCore.Diagnostics.HealthChecks kör en SELECT 1 fråga mot databasen för att bekräfta att anslutningen till databasen är felfri.

Inkludera en paketreferens till AspNetCore.HealthChecks.SqlServer.

Ange en giltig databasanslutningssträng i appsettings.json exempelappens fil. Appen använder en SQL Server-databas med namnet 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": "*"
}

Registrera hälsokontrolltjänster med AddHealthChecks i Startup.ConfigureServices. Exempelappen AddSqlServer anropar metoden med databasens anslutningssträng (DbHealthStartup.cs):

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

En slutpunkt för hälsokontroll skapas genom att anropa MapHealthChecks i Startup.Configure:

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

Kör följande kommando från projektets mapp i ett kommandogränssnitt för att köra scenariot med databasavsökningen med exempelappen:

dotnet run --scenario db

Entity Framework Core DbContext-avsökning

Kontrollen DbContext bekräftar att appen kan kommunicera med databasen som har konfigurerats för en EF CoreDbContext. Kontrollen DbContext stöds i appar som:

• Använd Entity Framework (EF) Core.
• Inkludera en paketreferens till Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore.

AddDbContextCheck<TContext> registrerar en hälsokontroll för en DbContext. DbContext Anges som TContext till -metoden. Det finns en överlagring för att konfigurera felstatus, taggar och en anpassad testfråga.

Som standard:

• Anropar DbContextHealthChecks EF Core-metod i CanConnectAsync. Du kan anpassa vilken åtgärd som körs när du kontrollerar hälsotillståndet med hjälp av AddDbContextCheck metodöverbelastningar.
• Namnet på hälsokontrollen är namnet på typen TContext.

I exempelappen AppDbContext tillhandahålls AddDbContextCheck och registreras som en tjänst i Startup.ConfigureServices (DbContextHealthStartup.cs):

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

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

En slutpunkt för hälsokontroll skapas genom att anropa MapHealthChecks i Startup.Configure:

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

Om du vill köra avsökningsscenariot DbContext med exempelappen kontrollerar du att databasen som anges av anslutningssträngen inte finns i SQL Server-instansen. Om databasen finns tar du bort den.

Kör följande kommando från projektets mapp i ett kommandogränssnitt:

dotnet run --scenario dbcontext

När appen har körts kontrollerar du hälsostatusen genom att göra en begäran till /health slutpunkten i en webbläsare. Databasen och AppDbContext finns inte, så appen ger följande svar:

Unhealthy

Utlös exempelappen för att skapa databasen. Skicka en begäran till /createdatabase. Appen svarar:

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

Skicka en begäran till /health slutpunkten. Databasen och kontexten finns, så appen svarar:

Healthy

Utlös exempelappen för att ta bort databasen. Skicka en begäran till /deletedatabase. Appen svarar:

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

Skicka en begäran till /health slutpunkten. Appen ger ett ohälsosamt svar:

Unhealthy

Separata beredskaps- och liveness-avsökningar

I vissa värdscenarier används ett par hälsokontroller för att skilja mellan två apptillstånd:

• Beredskap anger om appen körs normalt men inte är redo att ta emot begäranden.
• Liveness anger om en app har kraschat och måste startas om.

Tänk på följande exempel: En app måste ladda ned en stor konfigurationsfil innan den är redo att bearbeta begäranden. Vi vill inte att appen ska startas om om den första nedladdningen misslyckas eftersom appen kan försöka ladda ned filen igen flera gånger. Vi använder en liveness-prob för att beskriva processens aktivitet, inga andra kontroller körs. Vi vill också förhindra att begäranden skickas till appen innan nedladdningen av konfigurationsfilen har slutförts. Vi använder en beredskapsavsökning för att ange tillståndet "inte redo" förrän nedladdningen har slutförts och appen är redo att ta emot begäranden.

Exempelappen innehåller en hälsokontroll för att rapportera när en långvarig startuppgift är slutförd i en hostad tjänst. StartupHostedServiceHealthCheck Exponerar en egenskap, StartupTaskCompleted, som den värdbaserade tjänsten kan ställa in på true när dess långvariga uppgift är klar (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."));
    }
}

Den långkörande bakgrundsprocessen startas av en hostad tjänst (Services/StartupHostedService). När arbetsuppgiften är avslutad, ställs StartupHostedServiceHealthCheck.StartupTaskCompleted in på 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()
    {
    }
}

Hälsokontrollen registreras med AddCheck i Startup.ConfigureServices tillsammans med den värdtjänsten. Eftersom den värdbaserade tjänsten måste ange egenskapen för hälsokontrollen registreras även hälsokontrollen i tjänstcontainern (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>();

En slutpunkt för hälsokontroll skapas genom att anropa MapHealthChecks i Startup.Configure. I exempelappen skapas slutpunkterna för hälsokontroll på:

• /health/ready för beredskapskontrollen. Beredskapskontrollen filtrerar hälsokontrollerna till hälsokontrollen med taggen ready.
• /health/live för liveness-kontrollen. Liveness-kontrollen filtrerar ut StartupHostedServiceHealthCheck genom att returnera false i HealthCheckOptions.Predicate (för mer information, se Filtrera hälsokontroller)

I följande exempelkod:

• Beredskapskontrollen använder alla registrerade kontroller med taggen "klar".
• Predicate utesluter alla kontroller och returnerar 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
    });
}

För att köra konfigurationsscenariot för beredskap/livbarhet med hjälp av exempelappen, kör följande kommando från projektets mapp i ett kommandoskal:

dotnet run --scenario liveness

I en webbläsare besöker du /health/ready flera gånger tills 15 sekunder har passerat. Hälsokontrollrapporter visas Unhealthy under de första 15 sekunderna. Efter 15 sekunder rapporterar slutpunkten Healthy, vilket återspeglar slutförandet av den långvariga uppgiften av värdtjänsten.

Det här exemplet skapar också en Health Check Publisher (IHealthCheckPublisher implementering) som kör den första beredskapskontrollen med två sekunders fördröjning. Mer information finns i avsnittet Hälsokontrollutgivare .

Kubernetes-exempel

Att använda separata beredskaps- och liveness-kontroller är användbart i en miljö som Kubernetes. I Kubernetes kan en app behöva köra tidskrävande startarbete innan begäranden accepteras, till exempel ett test av den underliggande databastillgängligheten. Med hjälp av separata kontroller kan orkestratorn skilja mellan om appen fungerar men ännu inte är klar eller om appen inte har startats. Mer information om beredskaps- och livenessavsökningar i Kubernetes finns i Konfigurera liveness- och beredskapsavsökningar i Kubernetes-dokumentationen.

Följande exempel visar en konfiguration av en Kubernetes readiness probe:

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

Måttbaserad avsökning med en anpassad svarsskrivare

Exempelappen visar en minneshälsokontroll med en anpassad svarsskrivare.

MemoryHealthCheck rapporterar en degraderad status om appen använder mer än ett visst tröskelvärde för minne (1 GB i exempelappen). HealthCheckResult innehåller information om Garbage Collector (GC) för appen (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));
    }
}

Registrera hälsokontrolltjänster med AddHealthChecks i Startup.ConfigureServices. I stället för att aktivera hälsokontrollen genom att skicka den till AddCheckregistreras den MemoryHealthCheck som en tjänst. Alla IHealthCheck registrerade tjänster är tillgängliga för hälsokontrolltjänster och mellanprogram. Vi rekommenderar att du registrerar hälsokontrolltjänster som Singleton-tjänster.

Inom CustomWriterStartup.cs exempelappen:

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

En slutpunkt för hälsokontroll skapas genom att anropa MapHealthChecks i Startup.Configure. Ett WriteResponse ombud tillhandahålls till ResponseWriter egenskapen för att mata ut ett anpassat JSON-svar när hälsokontrollen körs:

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

Ombudet WriteResponse formaterar CompositeHealthCheckResult till ett JSON-objekt och ger JSON-utdata för hälsokontrollsvaret. Mer information finns i avsnittet Anpassa utdata .

Kör följande kommando från projektets mapp i ett kommandogränssnitt för att köra den måttbaserade avsökningen med anpassade svarsskrivareutdata med hjälp av exempelappen:

dotnet run --scenario writer

Filtrera efter port

RequireHost Anropa MapHealthChecks med ett URL-mönster som anger en port för att begränsa hälsokontrollbegäranden till den angivna porten. Den här metoden används vanligtvis i en containermiljö för att exponera en port för övervakningstjänster.

Exempelappen konfigurerar porten med hjälp av miljövariabelkonfigurationsprovidern. Porten anges i launchSettings.json filen och skickas till konfigurationsprovidern via en miljövariabel. Du måste också konfigurera servern för att lyssna på begäranden på hanteringsporten.

Om du vill använda exempelappen för att demonstrera konfigurationen av hanteringsporten skapar du launchSettings.json filen i en Properties mapp.

Följande Properties/launchSettings.json fil i exempelappen ingår inte i exempelappens projektfiler och måste skapas manuellt:

{
  "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/"
    }
  }
}

Registrera hälsokontrolltjänster med AddHealthChecks i Startup.ConfigureServices. Skapa en slutpunkt för hälsokontroll genom att anropa MapHealthChecks i Startup.Configure.

I exempelappen anger ett anrop till RequireHost på slutpunkten i Startup.Configure hanteringsporten från konfigurationen:

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

Slutpunkter skapas i exempelappen i Startup.Configure. I följande exempelkod:

• Beredskapskontrollen använder alla registrerade kontroller med taggen "klar".
• Predicate utesluter alla kontroller och returnerar 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");
});

Kör följande kommando från projektets mapp i ett kommandogränssnitt för att köra konfigurationsscenariot för hanteringsporten med hjälp av exempelappen:

dotnet run --scenario port

Distribuera ett hälsokontrollbibliotek

Så här distribuerar du en hälsokontroll som ett bibliotek:

1. Skriv en hälsokontroll som implementerar IHealthCheck gränssnittet som en fristående klass. Klassen kan förlita sig på beroendeinmatning (DI), typaktivering och namngivna alternativ för åtkomst till konfigurationsdata.

   I logiken för hälsokontroller i CheckHealthAsync:

   • data1 och data2 används i metoden för att köra probens hälsokontrolllogik.
   • AccessViolationException hanteras.

   När ett AccessViolationException inträffar, så returneras FailureStatus med HealthCheckResult för att låta användare konfigurera statusen för hälsokontroller.

   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. Skriv en tilläggsmetod med parametrar som den förbrukande appen anropar i sin Startup.Configure metod. I följande exempel antar du följande signatur för hälsokontrollmetoden:

   ExampleHealthCheck(string, string, int )
   

   Den föregående signaturen anger att ExampleHealthCheck kräver ytterligare data för att bearbeta logiken för hälsokontrollen. Data tillhandahålls till ombudet som används för att skapa hälsokontrollinstansen när hälsokontrollen registreras med en tilläggsmetod. I följande exempel anger anroparen valfritt:

   • hälsokontrollnamn (name). Om null, example_health_check används.
   • strängdatapunkt för hälsokontrollen (data1).
   • heltalsdatapunkt för hälsokontrollen (data2). Om null, 1 används.
   • felstatus (HealthStatus). Standardvärdet är null. Om null, HealthStatus.Unhealthy rapporteras för en felstatus.
   • taggar (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));
       }
   }
   

Hälsokontrollutgivare

När en IHealthCheckPublisher läggs till i tjänstcontainern, kör hälsokontrollsystemet regelbundet dina hälsokontroller och anropar PublishAsync med resultatet. Detta är användbart i ett push-baserat system för hälsoövervakning som förväntar sig att varje process anropar övervakningssystemet regelbundet för att fastställa hälsotillståndet.

Gränssnittet IHealthCheckPublisher har en enda metod:

Task PublishAsync(HealthReport report, CancellationToken cancellationToken);

HealthCheckPublisherOptions gör att du kan ange:

• Delay: Den inledande fördröjningen som tillämpas efter att appen startar innan exekvering av instanser IHealthCheckPublisher. Fördröjningen tillämpas en gång vid start och gäller inte för efterföljande iterationer. Standardvärdet är fem sekunder.
• Period: Utförandeperioden för IHealthCheckPublisher. Standardvärdet är 30 sekunder.
• Predicate: Om Predicate är null (standardläge) kör hälsokontrollens utgivartjänst alla registrerade hälsokontroller. Om du vill köra en delmängd av hälsokontrollerna anger du en funktion som filtrerar uppsättningen kontroller. Predikatet utvärderas varje period.
• Timeout: Tidsgränsen för att köra hälsokontroller för alla IHealthCheckPublisher instanser. Använd InfiniteTimeSpan för att köra utan tidsgräns. Standardvärdet är 30 sekunder.

I exempelappen är ReadinessPublisher en IHealthCheckPublisher implementation. Hälsokontrollstatusen loggas för varje kontroll på loggnivå:

• Information (LogInformation) om hälsokontrollstatusen är Healthy.
• Fel (LogError) om statusen är antingen Degraded eller 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;
    }
}

I exempelappens exempel LivenessProbeStartup har beredskapskontrollen två sekunders StartupHostedService startfördröjning och kör kontrollen var 30:e sekund. För att aktivera IHealthCheckPublisher-implementationen registrerar provet ReadinessPublisher som en singleton-tjänst i beroendeinjektionscontainern (DI):

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

Begränsa hälsokontroller med MapWhen

Använd MapWhen för att villkorsstyrt förgrena begärandepipelinen för hälsokontrollpunkter.

I följande exempel MapWhen förgrenar du pipelinen för begäran för att aktivera Mellanprogram för hälsokontroller om en GET-begäran tas emot för api/HealthCheck slutpunkten:

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

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

Mer information finns i ASP.NET Core Middleware.

ASP.NET Core erbjuder middleware för hälsokontroller och bibliotek för rapportering av infrastrukturen för appkomponenter.

Hälsokontroller exponeras av en app som HTTP-slutpunkter. Slutpunkter för hälsokontroll kan konfigureras för olika scenarier för realtidsövervakning:

• Hälsokontroller kan användas av containerorkestreringsverktyg och lastutjämnare för att kontrollera en apps status. En containerorkestrerare kan till exempel svara på en misslyckad hälsokontroll genom att stoppa en rullande distribution eller starta om en container. En lastbalanserare kan reagera på en felaktig app genom att dirigera trafik bort från den misslyckade instansen till en felfri instans.
• Användning av minne, disk och andra fysiska serverresurser kan övervakas för felfri status.
• Hälsokontroller kan testa en apps beroenden, till exempel databaser och externa tjänstslutpunkter, för att bekräfta tillgänglighet och normal funktion.

Hälsokontroller används vanligtvis med en extern övervakningstjänst eller containerorkestreringsverktyg för att kontrollera statusen för en app. Innan du lägger till hälsokontroller i en app ska du bestämma vilket övervakningssystem som ska användas. Övervakningssystemet avgör vilka typer av hälsokontroller som ska skapas och hur deras slutpunkter ska konfigureras.

Grundläggande hälsoavsökning

För många appar räcker det med en grundläggande konfiguration av hälsoavsökningar som rapporterar appens tillgänglighet för att bearbeta begäranden (liveness) för att identifiera appens status.

Den grundläggande konfigurationen registrerar hälsokontrolltjänster och anropar mellanprogrammet Hälsokontroller för att svara på en URL-slutpunkt med ett hälsosvar. Som standard registreras inga specifika hälsokontroller för att testa ett visst beroende eller undersystem. Appen anses vara felfri om den kan svara på url:en för hälsoslutpunkten. Standardsvarsskrivaren skriver HealthStatus som ett klartextsvar till klienten. HealthStatus är HealthStatus.Healthy, HealthStatus.Degradedeller HealthStatus.Unhealthy.

Registrera hälsokontrolltjänster med AddHealthChecks i Program.cs. Skapa en slutpunkt för hälsokontroll genom att anropa MapHealthChecks.

I följande exempel skapas en slutpunkt för hälsokontroll på /healthz:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Stuveriarbetare HEALTHCHECK

Docker erbjuder ett inbyggt HEALTHCHECK direktiv som kan användas för att kontrollera statusen för en app som använder den grundläggande konfigurationen för hälsokontroll:

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

I föregående exempel används curl för att göra en HTTP-begäran till slutpunkten för hälsokontroll på /healthz. curl ingår inte i .NET Linux-containeravbildningarna, men det kan läggas till genom att installera det nödvändiga paketet i Dockerfile. Container som använder bilder baserade på Alpine Linux kan använda den medföljande wget i stället för curl.

Skapa hälsokontroller

Hälsokontroller skapas genom att implementera gränssnittet IHealthCheck. Metoden CheckHealthAsync returnerar ett HealthCheckResult som anger hälsotillståndet som Healthy, Degradedeller Unhealthy. Resultatet skrivs som ett klartextsvar med en konfigurerbar statuskod. Konfigurationen beskrivs i avsnittet Alternativ för hälsokontroll . HealthCheckResult kan också returnera valfria nyckel/värde-par.

I följande exempel visas layouten för en hälsokontroll:

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

        // ...

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

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

Hälsokontrollens logik placeras i CheckHealthAsync -metoden. I föregående exempel anges en dummyvariabel, isHealthy, till true. Om värdet isHealthy för är inställt på falsereturneras statusen HealthCheckRegistration.FailureStatus .

Om CheckHealthAsync genererar ett undantag under kontrollen returneras en ny HealthReportEntry med dess HealthReportEntry.Status inställd på FailureStatus. Den här statusen definieras av AddCheck (se avsnittet Registrera hälsokontrolltjänster ) och innehåller det inre undantag som orsakade kontrollfelet. Description är inställt på undantagets meddelande.

Registrera hälsokontrolltjänster

Om du vill registrera en hälsokontrolltjänst anropar du AddCheck :Program.cs

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

Den AddCheck överlagring som visas i följande exempel anger felstatus (HealthStatus) som ska rapporteras när hälsokontrollen rapporterar ett fel. Om felstatusen är inställd på null (standard) HealthStatus.Unhealthy rapporteras. Den här överbelastningen är ett användbart scenario för biblioteksförfattare, där felstatusen som biblioteket anger tvingas fram av appen när ett hälsokontrollfel uppstår, om hälsokontrollimplementeringen följer inställningen.

Taggar kan användas för att filtrera hälsokontroller. Taggar beskrivs i avsnittet Filterhälsokontroller .

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

AddCheck kan också köra en lambda-funktion. I följande exempel returnerar hälsokontrollen alltid ett felfritt resultat:

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

Anropa AddTypeActivatedCheck för att skicka argument till en hälsokontrollimplementation. I följande exempel accepterar en typaktiverad hälsokontroll ett heltal och en sträng i konstruktorn:

public class SampleHealthCheckWithArgs : IHealthCheck
{
    private readonly int _arg1;
    private readonly string _arg2;

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

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

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

Om du vill registrera föregående hälsokontroll anropar du AddTypeActivatedCheck med heltal och sträng som skickas som argument:

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

Använd ruttning av hälsokontroller

I Program.csanropar du MapHealthChecks på slutpunktsverktyget med slutpunkts-URL:en eller den relativa sökvägen:

app.MapHealthChecks("/healthz");

Kräv värd

Anropa RequireHost för att ange en eller flera tillåtna värdar för slutpunkten för hälsokontroll. Värdar bör vara Unicode i stället för punycode och kan innehålla en port. Om en samling inte tillhandahålls godkänns någon värd:

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

Om du vill begränsa hälsokontrollslutpunkten så att den endast svarar på en specifik port anger du en port i anropet till RequireHost. Den här metoden används vanligtvis i en containermiljö för att exponera en port för övervakningstjänster:

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

Om du vill förhindra att obehöriga klienter förfalskar porten anropar du RequireAuthorization:

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

För mer information, se Värdmatchning i rutter med RequireHost.

Kräv auktorisering

Anropa RequireAuthorization för att köra Authorization Middleware på slutpunkten för hälsokontrollbegäran. En RequireAuthorization överbelastning accepterar en eller flera auktoriseringspolicys. Om en princip inte anges används standardauktoriseringsprincipen:

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

Aktivera CORS (Cross-Origin-förfrågningar)

Även om det inte är vanligt att köra hälsokontroller manuellt från en webbläsare kan CORS Middleware aktiveras genom att anropa RequireCors slutpunkterna för hälsokontroller. Överlagringen RequireCors accepterar ett CORS-policybyggardelegat (CorsPolicyBuilder) eller ett policy-namn. Mer information finns i Aktivera CORS (Cross-Origin Requests) i ASP.NET Core.

Alternativ för hälsokontroll

HealthCheckOptions ge en möjlighet att anpassa beteendet för hälsokontroll:

• Filtrera hälsokontroller
• Anpassa HTTP-statuskoden
• Ignorera cachehuvuden
• Anpassa utdata

Filtrera hälsokontroller

Som standard kör Health Checks Middleware alla registrerade hälsokontroller. Om du vill köra en delmängd av hälsokontroller anger du en funktion som returnerar ett booleskt värde till Predicate alternativet.

I följande exempel visas hur hälsokontrollerna filtreras så att endast de som är taggade med sample körs.

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

Anpassa HTTP-statuskoden

Använd ResultStatusCodes för att anpassa mappningen av hälsostatus till HTTP-statuskoder. Följande StatusCodes tilldelningar är standardvärdena som används av mellanprogrammet. Ändra statuskodvärdena så att de uppfyller dina krav:

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

Ignorera cachehuvuden

AllowCachingResponses styr om Health Checks Middleware lägger till HTTP-huvuden i ett avsökningssvar för att förhindra cachelagring av svar. Om värdet är false (standard) anger eller åsidosätter mellanprogrammet rubrikerna Cache-Control, Expiresoch Pragma för att förhindra cachelagring av svar. Om värdet är trueändrar inte mellanprogrammet cachehuvudena för svaret:

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

Anpassa utdata

Om du vill anpassa utdata från en hälsokontrollrapport anger du HealthCheckOptions.ResponseWriter egenskapen till ett ombud som skriver svaret:

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

Standarddelegaten skriver ett minimalt svar i klartext med strängvärdet HealthReport.Status. Följande anpassade delegat genererar ett anpassat JSON-svar med hjälp av System.Text.Json.

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

    var options = new JsonWriterOptions { Indented = true };

    using var memoryStream = new MemoryStream();
    using (var jsonWriter = new Utf8JsonWriter(memoryStream, options))
    {
        jsonWriter.WriteStartObject();
        jsonWriter.WriteString("status", healthReport.Status.ToString());
        jsonWriter.WriteStartObject("results");

        foreach (var healthReportEntry in healthReport.Entries)
        {
            jsonWriter.WriteStartObject(healthReportEntry.Key);
            jsonWriter.WriteString("status",
                healthReportEntry.Value.Status.ToString());
            jsonWriter.WriteString("description",
                healthReportEntry.Value.Description);
            jsonWriter.WriteStartObject("data");

            foreach (var item in healthReportEntry.Value.Data)
            {
                jsonWriter.WritePropertyName(item.Key);

                JsonSerializer.Serialize(jsonWriter, item.Value,
                    item.Value?.GetType() ?? typeof(object));
            }

            jsonWriter.WriteEndObject();
            jsonWriter.WriteEndObject();
        }

        jsonWriter.WriteEndObject();
        jsonWriter.WriteEndObject();
    }

    return context.Response.WriteAsync(
        Encoding.UTF8.GetString(memoryStream.ToArray()));
}

API:et för hälsokontroller ger inte inbyggt stöd för komplexa JSON-returformat eftersom formatet är specifikt för ditt val av övervakningssystem. Anpassa svaret i föregående exempel efter behov. Mer information om JSON-serialisering med System.Text.Jsonfinns i Serialisera och deserialisera JSON i .NET.

Databasavsökning

En hälsokontroll kan ange en databasfråga som ska köras som ett booleskt test för att ange om databasen svarar normalt.

AspNetCore.Diagnostics.HealthChecksinnehåller ett hälsokontrollbibliotek för ASP.NET Core-appar en hälsokontroll som körs mot en SQL Server-databas. AspNetCore.Diagnostics.HealthChecks kör en SELECT 1 fråga mot databasen för att bekräfta att anslutningen till databasen är felfri.

Om du vill använda den här SQL Server-hälsokontrollen inkluderar du en paketreferens till AspNetCore.HealthChecks.SqlServer NuGet-paketet. I följande exempel registreras SQL Server-hälsokontrollen:

builder.Services.AddHealthChecks()
    .AddSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection"));

Entity Framework Core DbContext-avsökning

Kontrollen DbContext bekräftar att appen kan kommunicera med databasen som har konfigurerats för en EF CoreDbContext. Kontrollen DbContext stöds i appar som:

• Använd Entity Framework (EF) Core.
• Inkludera en paketreferens till Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore NuGet-paketet.

AddDbContextCheck registrerar en hälsokontroll för en DbContext. DbContext levereras till metoden som TContext. Det finns en överlagring för att konfigurera felstatus, taggar och en anpassad testfråga.

Som standard:

• Anropar DbContextHealthChecks EF Core-metod i CanConnectAsync. Du kan anpassa vilken åtgärd som körs när du kontrollerar hälsotillståndet med hjälp av AddDbContextCheck metodöverbelastningar.
• Namnet på hälsokontrollen är namnet på typen TContext.

I följande exempel registreras en DbContext och en associerad DbContextHealthCheck:

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

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

Separata beredskaps- och liveness-avsökningar

I vissa värdscenarier används ett par hälsokontroller för att skilja mellan två apptillstånd:

• Beredskap anger om appen körs normalt men inte är redo att ta emot begäranden.
• Liveness anger om en app har kraschat och måste startas om.

Tänk på följande exempel: En app måste ladda ned en stor konfigurationsfil innan den är redo att bearbeta begäranden. Vi vill inte att appen ska startas om om den första nedladdningen misslyckas eftersom appen kan försöka ladda ned filen igen flera gånger. Vi använder en liveness-prob för att beskriva processens aktivitet, inga andra kontroller körs. Vi vill också förhindra att begäranden skickas till appen innan nedladdningen av konfigurationsfilen har slutförts. Vi använder en beredskapsavsökning för att ange tillståndet "inte redo" förrän nedladdningen har slutförts och appen är redo att ta emot begäranden.

Följande bakgrundsaktivitet simulerar en startprocess som tar ungefär 15 sekunder. När uppgiften är klar ställer StartupHealthCheck.StartupCompleted in egenskapen till true.

public class StartupBackgroundService : BackgroundService
{
    private readonly StartupHealthCheck _healthCheck;

    public StartupBackgroundService(StartupHealthCheck healthCheck)
        => _healthCheck = healthCheck;

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        // Simulate the effect of a long-running task.
        await Task.Delay(TimeSpan.FromSeconds(15), stoppingToken);

        _healthCheck.StartupCompleted = true;
    }
}

StartupHealthCheck Rapporterar slutförandet av den långvariga startuppgiften och exponerar egenskapen StartupCompleted som anges av bakgrundstjänsten:

public class StartupHealthCheck : IHealthCheck
{
    private volatile bool _isReady;

    public bool StartupCompleted
    {
        get => _isReady;
        set => _isReady = value;
    }

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

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

Hälsokontrollen registreras med AddCheck i Program.cs tillsammans med den värdtjänsten. Eftersom den värdbaserade tjänsten måste ange egenskapen för hälsokontrollen registreras hälsokontrollen också i tjänstcontainern som en singleton:

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

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

Om du vill skapa två olika slutpunkter för hälsokontroll anropar du MapHealthChecks två gånger:

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

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

I föregående exempel skapas följande slutpunkter för hälsokontroll:

• /healthz/ready för beredskapskontrollen. Beredskapskontrollen filtrerar hälsokontroller till dem som är taggade med ready.
• /healthz/live för liveness-kontrollen. Livskontrollen filtrerar ut alla hälsokontroller genom att returnera false i delegeringen HealthCheckOptions.Predicate. Mer information om hur du filtrerar hälsokontroller finns i Filtrera hälsokontroller i den här artikeln.

Innan startaktiviteten /healthz/ready är klar rapporterar slutpunkten status Unhealthy . När startaktiviteten är klar rapporterar slutpunkten status Healthy . Slutpunkten /healthz/live exkluderar alla kontroller och rapporterar status Healthy för alla anrop.

Kubernetes-exempel

Att använda separata beredskaps- och liveness-kontroller är användbart i en miljö som Kubernetes. I Kubernetes kan en app behöva köra tidskrävande startarbete innan begäranden accepteras, till exempel ett test av den underliggande databastillgängligheten. Med hjälp av separata kontroller kan orkestratorn skilja mellan om appen fungerar men ännu inte är klar eller om appen inte har startats. Mer information om beredskaps- och livenessavsökningar i Kubernetes finns i Konfigurera liveness- och beredskapsavsökningar i Kubernetes-dokumentationen.

Följande exempel visar en konfiguration av en Kubernetes readiness probe:

spec:
  template:
  spec:
    readinessProbe:
      # an http probe
      httpGet:
        path: /healthz/ready
        port: 80
      # length of time to wait for a pod to initialize
      # after pod startup, before applying health checking
      initialDelaySeconds: 30
      timeoutSeconds: 1
    ports:
      - containerPort: 80

Distribuera ett hälsokontrollbibliotek

Så här distribuerar du en hälsokontroll som ett bibliotek:

1. Skriv en hälsokontroll som implementerar IHealthCheck gränssnittet som en fristående klass. Klassen kan förlita sig på beroendeinmatning (DI), typaktivering och namngivna alternativ för åtkomst till konfigurationsdata.

2. Skriv en tilläggsmetod med parametrar som den förbrukande appen anropar i sin Program.cs metod. Överväg följande exempel på hälsokontroll, som accepterar arg1 och arg2 som konstruktorparametrar:

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

   Den föregående signaturen anger att hälsokontrollen kräver anpassade data för att bearbeta logiken för hälsokontrollavsökningen. Data tillhandahålls till ombudet som används för att skapa hälsokontrollinstansen när hälsokontrollen registreras med en tilläggsmetod. I följande exempel anger anroparen:

   • arg1: En heltalsdatapunkt för hälsokontrollen.
   • arg2: Ett strängargument för hälsokontrollen.
   • name: Ett valfritt hälsokontrollnamn. Om nullanvänds ett standardvärde.
   • failureStatus: En valfri HealthStatus, vilken rapporteras vid en misslyckandestatus. Om null, HealthStatus.Unhealthy används.
   • tags: En valfri IEnumerable<string> samling taggar.

   public static class SampleHealthCheckBuilderExtensions
   {
       private const string DefaultName = "Sample";
   
       public static IHealthChecksBuilder AddSampleHealthCheck(
           this IHealthChecksBuilder healthChecksBuilder,
           int arg1,
           string arg2,
           string? name = null,
           HealthStatus? failureStatus = null,
           IEnumerable<string>? tags = default)
       {
           return healthChecksBuilder.Add(
               new HealthCheckRegistration(
                   name ?? DefaultName,
                   _ => new SampleHealthCheckWithArgs(arg1, arg2),
                   failureStatus,
                   tags));
       }
   }
   

Hälsokontrollutgivare

När en IHealthCheckPublisher läggs till i tjänstcontainern, kör hälsokontrollsystemet regelbundet dina hälsokontroller och anropar PublishAsync med resultatet. Den här processen är användbar i ett push-baserat system för hälsoövervakning som förväntar sig att varje process regelbundet anropar övervakningssystemet för att fastställa hälsotillståndet.

HealthCheckPublisherOptions gör att du kan ange:

• Delay: Den inledande fördröjningen som tillämpas efter att appen startar innan exekvering av instanser IHealthCheckPublisher. Fördröjningen tillämpas en gång vid start och gäller inte för senare iterationer. Standardvärdet är fem sekunder.
• Period: Utförandeperioden för IHealthCheckPublisher. Standardvärdet är 30 sekunder.
• Predicate: Om Predicate är null (standardläge) kör hälsokontrollens utgivartjänst alla registrerade hälsokontroller. Om du vill köra en delmängd av hälsokontrollerna anger du en funktion som filtrerar uppsättningen kontroller. Predikatet utvärderas varje period.
• Timeout: Tidsgränsen för att köra hälsokontroller för alla IHealthCheckPublisher instanser. Använd InfiniteTimeSpan för att köra utan tidsgräns. Standardvärdet är 30 sekunder.

I följande exempel visas layouten för en hälsoutgivare:

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

        return Task.CompletedTask;
    }
}

Klassen HealthCheckPublisherOptions tillhandahåller egenskaper för att konfigurera beteendet hos hälsokontrollens publicerare.

I följande exempel registreras en hälsokontrollutgivare som en singleton och konfigurerar HealthCheckPublisherOptions:

builder.Services.Configure<HealthCheckPublisherOptions>(options =>
{
    options.Delay = TimeSpan.FromSeconds(2);
    options.Predicate = healthCheck => healthCheck.Tags.Contains("sample");
});

builder.Services.AddSingleton<IHealthCheckPublisher, SampleHealthCheckPublisher>();

Beroendeinmatning och hälsokontroller

Du kan använda dependency injection för att använda en instans av en specifik Type i en hälsokontrollklass. Beroendeinmatning kan vara användbart för att mata in alternativ eller en global konfiguration till en hälsokontroll. Att använda beroendeinmatning är inte ett vanligt scenario för att konfigurera hälsokontroller. Vanligtvis är varje hälsokontroll ganska specifik för det faktiska testet och konfigureras med hjälp av IHealthChecksBuilder tilläggsmetoder.

I följande exempel visas ett exempel på hälsokontroll som hämtar ett konfigurationsobjekt via beroendeinmatning:

public class SampleHealthCheckWithDI : IHealthCheck
{
    private readonly SampleHealthCheckWithDiConfig _config;

    public SampleHealthCheckWithDI(SampleHealthCheckWithDiConfig config)
        => _config = config;

    public Task<HealthCheckResult> CheckHealthAsync(
        HealthCheckContext context, CancellationToken cancellationToken = default)
    {
        var isHealthy = true;

        // use _config ...

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

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

SampleHealthCheckWithDiConfig och hälsokontrollen behöver läggas till i tjänstcontainern:

builder.Services.AddSingleton<SampleHealthCheckWithDiConfig>(new SampleHealthCheckWithDiConfig
{
    BaseUriToCheck = new Uri("https://sample.contoso.com/api/")
});
builder.Services.AddHealthChecks()
    .AddCheck<SampleHealthCheckWithDI>(
        "With Dependency Injection",
        tags: new[] { "inject" });

UseHealthChecks jämfört med MapHealthChecks

Det finns två sätt att göra hälsokontroller tillgängliga för uppringare:

• UseHealthChecks registrerar mellanvara för att hantera hälsokontrollförfrågningar i mellanvarurörledningen.
• MapHealthChecks registrerar en slutpunkt för hälsokontroller. Slutpunkten matchas och körs tillsammans med andra slutpunkter i appen.

Fördelen med att använda MapHealthChecks över UseHealthChecks är möjligheten att använda slutpunktsmedvetna mellanprogram, till exempel auktorisering, och att ha större detaljerad kontroll över matchningsprincipen. Den främsta fördelen med att använda UseHealthChecks över MapHealthChecks är att kontrollera exakt var hälsokontroller körs i pipelinen för mellanprogram.

UseHealthChecks:

• Avslutar pipelinen när en begäran matchar slutpunkten för hälsokontroll. Kortslutning är ofta önskvärt eftersom det undviker onödigt arbete, till exempel loggning och andra mellanprogram.
• Används främst för att konfigurera mellanprogrammet för hälsokontroll i pipelinen.
• Kan matcha valfri sökväg på en port med en null eller tom PathString. Tillåter att du utför en hälsokontroll på alla begäranden som görs till den angivna porten.
• Källkod

MapHealthChecks Tillåter:

• Mappa specifika vägar eller slutpunkter för hälsokontroller.
• Anpassning av URL:en eller sökvägen där slutpunkten för hälsokontroll är tillgänglig.
• Mappa flera slutpunkter för hälsokontroll med olika vägar eller konfigurationer. Stöd för flera slutpunkter:
  • Aktiverar separata slutpunkter för olika typer av hälsokontroller eller komponenter.
  • Används för att skilja mellan olika aspekter av appens hälsa eller tillämpa specifika konfigurationer på delmängder av hälsokontroller.
• Källkod

Ytterligare resurser

• Visa eller ladda ned exempelkod (hur du laddar ned)