Controlli di integrità in ASP.NET Core

Di Glenn Condron e Juergen Gutsch

ASP.NET Core offre il middleware e le librerie di controlli di integrità per segnalare l'integrità dei componenti dell'infrastruttura delle app.

I controlli di integrità vengono esposti da un'app come endpoint HTTP. Gli endpoint di controllo integrità possono essere configurati per vari scenari di monitoraggio in tempo reale:

• I probe di integrità possono essere usati dagli agenti di orchestrazione e dai servizi di bilanciamento del carico per controllare lo stato di un'app. Ad esempio, un agente di orchestrazione potrebbe rispondere a controllo di integrità non superato arrestando una distribuzione in sequenza o riavviando un contenitore. Un servizio di bilanciamento del carico potrebbe reagire a un'app non integra trasferendo il traffico dall'istanza con errori a un'istanza integra.
• È possibile monitorare lo stato di integrità di memoria, disco e altre risorse fisiche del server.
• I controlli di integrità possono testare le dipendenze di un'app, ad esempio i database e gli endpoint di servizio esterni, per verificare la disponibilità e il normale funzionamento.

I controlli di integrità vengono in genere usati con un servizio di monitoraggio esterno o un agente di orchestrazione del contenitore per controllare lo stato di un'app. Prima di aggiungere i controlli di integrità a un'app, decidere quale sistema di monitoraggio usare. Il sistema di monitoraggio determina quali tipi di controlli di integrità creare e come configurare i relativi endpoint.

Probe di integrità di base

Per molte app, una configurazione del probe di integrità di base, che segnala la disponibilità dell'app per elaborare le richieste (attività), è sufficiente per individuare lo stato dell'app.

La configurazione di base registra i servizi di controllo integrità e chiama il middleware controlli di integrità per rispondere a un endpoint URL con una risposta di integrità. Per impostazione predefinita, non vengono registrati controlli di integrità specifici per testare particolari dipendenze o sottosistemi. L'app viene considerata integra se può rispondere all'URL dell'endpoint di integrità. Il writer di risposta predefinito scrive HealthStatus come risposta in testo non crittografato al client. è HealthStatus HealthStatus.Healthy, HealthStatus.Degradedo HealthStatus.Unhealthy.

Registrare i servizi dei controlli di integrità con AddHealthChecks in Program.cs. Creare un endpoint di controllo dell'integrità chiamando MapHealthChecks.

L'esempio seguente crea un endpoint di controllo integrità in /healthz:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Docker HEALTHCHECK

Docker offre una direttiva HEALTHCHECK predefinita che può essere usata per controllare lo stato di un'app che usa la configurazione dei controlli di integrità di base:

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

Nell'esempio precedente viene curl usato per effettuare una richiesta HTTP all'endpoint del controllo integrità in /healthz. curl non è incluso nelle immagini del contenitore .NET Linux, ma può essere aggiunto installando il pacchetto necessario nel Dockerfile. I contenitori che usano immagini basate su Alpine Linux possono usare l'oggetto incluso wget al posto di curl.

Creare controlli di integrità

I controlli di integrità vengono creati implementando l'interfaccia IHealthCheck. Il metodo CheckHealthAsync restituisce HealthCheckResult che indica l'integrità come Healthy, Degraded o Unhealthy. Il risultato viene scritto come risposta in testo non crittografato con un codice di stato configurabile. La configurazione è descritta nella sezione Opzioni controllo integrità. HealthCheckResult può anche restituire coppie chiave-valore facoltative.

Nell'esempio seguente viene illustrato il layout di un controllo integrità:

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

La logica del controllo integrità viene inserita nel CheckHealthAsync metodo . Nell'esempio precedente viene impostata una variabile fittizia, , isHealthysu true. Se il valore di isHealthy è impostato su false, viene restituito lo HealthCheckRegistration.FailureStatus stato .

Se CheckHealthAsync genera un'eccezione durante il controllo, viene restituito un nuovo HealthReportEntry oggetto con il relativo HealthReportEntry.Status set su FailureStatus. Questo stato è definito da AddCheck (vedere la sezione Registrare i servizi di controllo integrità) e include l'eccezione interna che ha causato l'errore di controllo. l'oggetto Description è impostato sul messaggio dell'eccezione.

Registrare i servizi di controllo dell'integrità

Per registrare un servizio di controllo integrità, chiamare AddCheck in Program.cs:

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

L'overload AddCheck illustrato nell'esempio seguente imposta lo stato di errore (HealthStatus) per segnalare quando il controllo di integrità indica un errore. Se lo stato di errore è impostato su null (impostazione predefinita), viene segnalato HealthStatus.Unhealthy. Questo overload è uno scenario utile per gli autori di librerie, in cui lo stato di errore indicato dalla libreria viene applicato dall'app quando si verifica un errore di controllo dell'integrità se l'implementazione del controllo dell'integrità rispetta l'impostazione.

I tag possono essere usati per filtrare i controlli di integrità. I tag sono descritti nella sezione Filtri controlli di integrità.

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

AddCheck può anche eseguire una funzione lambda. Nell'esempio seguente il controllo integrità restituisce sempre un risultato integro:

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

Chiamare AddTypeActivatedCheck per passare argomenti a un'implementazione del controllo integrità. Nell'esempio seguente un controllo di integrità attivato dal tipo accetta un numero intero e una stringa nel relativo costruttore:

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

Per registrare il controllo integrità precedente, chiamare AddTypeActivatedCheck con l'intero e la stringa passati come argomenti:

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

Usare il routing dei controlli di integrità

In Program.cschiamare MapHealthChecks sul generatore di endpoint con l'URL dell'endpoint o il percorso relativo:

app.MapHealthChecks("/healthz");

Richiedi host

Chiamare RequireHost per specificare uno o più host consentiti per l'endpoint di controllo integrità. Gli host devono essere Unicode anziché punycode e possono includere una porta. Se non viene fornita una raccolta, viene accettato qualsiasi host:

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

Per limitare la risposta dell'endpoint del controllo integrità solo su una porta specifica, specificare una porta nella chiamata a RequireHost. Questo approccio viene in genere usato in un ambiente contenitore per esporre una porta per i servizi di monitoraggio:

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

Avviso

L'API che si basa sull'intestazione Host, ad esempio HttpRequest.Host e RequireHost, è soggetta a potenziali spoofing da parte dei client.

Per evitare lo spoofing di host e porta, usare uno degli approcci seguenti:

• Usare HttpContext.Connection (ConnectionInfo.LocalPort) in cui vengono controllate le porte.
• Usare il filtro host.

Per impedire ai client non autorizzati di eseguire lo spoofing della porta, chiamare RequireAuthorization:

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

Per altre informazioni, vedere Corrispondenza host nelle route con RequireHost.

Richiedi autorizzazione

Chiamare RequireAuthorization per eseguire il middleware di autorizzazione nell'endpoint della richiesta di controllo integrità. Un RequireAuthorization overload accetta uno o più criteri di autorizzazione. Se non viene specificato un criterio, vengono usati i criteri di autorizzazione predefiniti:

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

Abilitare richieste tra le origini (CORS)

Anche se l'esecuzione manuale dei controlli di integrità da un browser non è uno scenario comune, il middleware CORS può essere abilitato chiamando RequireCors gli endpoint dei controlli di integrità. L'overload RequireCors accetta un delegato del generatore di criteri CORS (CorsPolicyBuilder) o un nome di criteri. Per altre informazioni, vedere Abilitare le richieste tra le origini (CORS) in ASP.NET Core.

Opzioni dei controlli di integrità

HealthCheckOptions consente di personalizzare il comportamento dei controlli di integrità:

• Filtrare i controlli di integrità
• Personalizzare il codice di stato HTTP
• Eliminare le intestazioni della cache
• Personalizzare l'output

Filtrare i controlli di integrità

Per impostazione predefinita, il middleware controlli di integrità esegue tutti i controlli di integrità registrati. Per eseguire un subset dei controlli di integrità, specificare una funzione che restituisce un valore booleano all'opzione Predicate.

Nell'esempio seguente vengono filtrati i controlli di integrità in modo che solo quelli contrassegnati con l'esecuzione sample :

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

Personalizzare il codice di stato HTTP

Usare ResultStatusCodes per personalizzare il mapping dello stato di integrità dei codici di stato HTTP. Le assegnazioni StatusCodes seguenti sono i valori predefiniti usati dal middleware. Modificare i valori del codice di stato per soddisfare i requisiti:

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

Eliminare le intestazioni della cache

AllowCachingResponses controlla se il middleware controlli di integrità aggiunge intestazioni HTTP a una risposta probe per impedire la memorizzazione nella cache delle risposte. Se il valore è false (impostazione predefinita), il middleware imposta le intestazioni Cache-Control, Expires e Pragma o ne esegue l'override per impedire la memorizzazione della risposta nella cache. Se il valore è true, il middleware non modifica le intestazioni della cache della risposta:

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

Personalizzare l'output

Per personalizzare l'output di un report dei controlli di integrità, impostare la HealthCheckOptions.ResponseWriter proprietà su un delegato che scrive la risposta:

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

Il delegato predefinito scrive una risposta in testo non crittografato minima con il valore di stringa HealthReport.Status. Il delegato personalizzato seguente restituisce una risposta JSON personalizzata usando 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()));
}

L'API dei controlli di integrità non fornisce il supporto predefinito per i formati restituiti JSON complessi perché il formato è specifico della scelta del sistema di monitoraggio. Personalizzare la risposta negli esempi precedenti in base alle esigenze. Per altre informazioni sulla serializzazione JSON con System.Text.Json, vedere Come serializzare e deserializzare JSON in .NET.

Probe del database

Un controllo di integrità può specificare una query di database da eseguire come test booleano per indicare se il database sta rispondendo normalmente.

AspNetCore.Diagnostics.HealthChecks, una libreria di controllo dell'integrità per le app core ASP.NET, include un controllo integrità eseguito su un database di SQL Server. AspNetCore.Diagnostics.HealthChecks esegue una query SELECT 1 sul database per confermare che la connessione al database sia integra.

Avviso

Quando si controlla una connessione di database con una query, scegliere una query che viene restituita rapidamente. Dall'approccio alla query possono derivare il sovraccarico del database e il degrado delle prestazioni. Nella maggior parte dei casi, l'esecuzione di una query di test non è necessaria. È sufficiente stabilire una connessione al database. Se invece è necessario eseguire una query, scegliere una semplice query SELECT, ad esempio SELECT 1.

Per usare questo controllo integrità di SQL Server, includere un riferimento al AspNetCore.HealthChecks.SqlServer pacchetto NuGet. Nell'esempio seguente viene registrato il controllo integrità di SQL Server:

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

Nota

AspNetCore.Diagnostics.HealthChecks non è gestito o supportato da Microsoft.

Probe DbContext di Entity Framework Core

Il DbContext controllo conferma che l'app può comunicare con il database configurato per un oggetto EF CoreDbContext. Il controllo DbContext è supportato nelle app che:

• Usano Entity Framework (EF) Core.
• Includere un riferimento al Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore pacchetto NuGet.

AddDbContextCheck registra un controllo di integrità per un DbContext. L'oggetto DbContext viene fornito al metodo come TContext. È disponibile un overload per configurare lo stato di errore, i tag e una query di test personalizzata.

Per impostazione predefinita:

• Il DbContextHealthCheck metodo chiama EF Coreil metodo .CanConnectAsync È possibile determinare l'operazione da eseguire quando si controlla l'integrità usando gli overload del metodo AddDbContextCheck.
• Il nome del controllo di integrità è il nome del tipo TContext.

Nell'esempio seguente viene registrato un DbContext oggetto e un oggetto associato DbContextHealthCheck:

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

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

Separare i probe di idoneità e di attività

In alcuni scenari di hosting viene usata una coppia di controlli di integrità per distinguere due stati dell'app:

• Idoneità indica se l'app è in esecuzione normalmente, ma non è pronta per ricevere le richieste.
• Liveness indica se un'app si è arrestata in modo anomalo e deve essere riavviata.

Si consideri l'esempio seguente: un'app deve scaricare un file di configurazione di grandi dimensioni prima che sia pronto per elaborare le richieste. Non si vuole riavviare l'app se il download iniziale non riesce perché l'app può riprovare a scaricare il file più volte. Viene usato un probe di attività per descrivere la durata del processo, non vengono eseguiti altri controlli. Si vuole anche impedire che le richieste vengano inviate all'app prima che il download del file di configurazione abbia avuto esito positivo. Usiamo un probe di idoneità per indicare uno stato "non pronto" fino a quando il download non riesce e l'app è pronta per ricevere le richieste.

L'attività in background seguente simula un processo di avvio che richiede circa 15 secondi. Al termine, l'attività imposta la StartupHealthCheck.StartupCompleted proprietà su 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;
    }
}

Segnala StartupHealthCheck il completamento dell'attività di avvio a esecuzione prolungata ed espone la StartupCompleted proprietà che viene impostata dal servizio in background:

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

Il controllo di integrità viene registrato con AddCheck in Program.cs insieme al servizio ospitato. Poiché il servizio ospitato deve impostare la proprietà nel controllo integrità, il controllo integrità viene registrato anche nel contenitore del servizio come singleton:

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

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

Per creare due endpoint di controllo integrità diversi, chiamare MapHealthChecks due volte:

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

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

L'esempio precedente crea gli endpoint di controllo integrità seguenti:

• /healthz/ready per il controllo di conformità. Il controllo di conformità filtra i controlli di integrità a quelli contrassegnati con ready.
• /healthz/live per il controllo del liveness. Il controllo attività filtra tutti i controlli di integrità restituendo false nel HealthCheckOptions.Predicate delegato. Per altre informazioni sul filtro dei controlli di integrità, vedere Filtrare i controlli di integrità in questo articolo.

Prima del completamento dell'attività di avvio, l'endpoint /healthz/ready segnala uno Unhealthy stato. Al termine dell'attività di avvio, questo endpoint segnala uno Healthy stato. L'endpoint /healthz/live esclude tutti i controlli e segnala uno Healthy stato per tutte le chiamate.

Esempio di Kubernetes

L'uso di controlli di idoneità e attività separati è utile in un ambiente come Kubernetes. In Kubernetes potrebbe essere necessaria un'app per eseguire operazioni di avvio che richiedono molto tempo prima di accettare richieste, ad esempio un test della disponibilità del database sottostante. L'uso di controlli separati consente all'agente di orchestrazione di distinguere se l'app è funzionante, ma non è ancora pronta o se l'app non è stata avviata. Per altre informazioni sui probe di idoneità e di attività in Kubernetes, vedere Configure Liveness and Readiness Probes (Configurare i probe di attività e di idoneità in Kubernetes) nella documentazione di Kubernetes.

L'esempio seguente illustra la configurazione di un probe di idoneità di Kubernetes:

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

Distribuire una libreria di controllo di integrità

Per distribuire un controllo di integrità come libreria:

1. Scrivere un controllo di integrità che implementa l'interfaccia IHealthCheck come classe autonoma. La classe può basarsi su inserimento delle dipendenze, attivazione del tipo e opzioni denominate per accedere ai dati di configurazione.

2. Scrivere un metodo di estensione con i parametri che l'app chiama nel metodo Program.cs. Si consideri il controllo integrità di esempio seguente, che accetta arg1 e arg2 come parametri del costruttore:

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

   La firma precedente indica che il controllo integrità richiede dati personalizzati per elaborare la logica del probe del controllo integrità. I dati vengono forniti al delegato usato per creare l'istanza del controllo di integrità quando il controllo di integrità viene registrato con un metodo di estensione. Nell'esempio seguente il chiamante specifica:

   • arg1: punto dati integer per il controllo integrità.
   • arg2: argomento stringa per il controllo integrità.
   • name: nome facoltativo del controllo integrità. Se null, viene usato un valore predefinito.
   • failureStatus: oggetto facoltativo HealthStatusche viene segnalato per uno stato di errore. Se null, viene usato HealthStatus.Unhealthy.
   • tags: raccolta facoltativa IEnumerable<string> di tag.

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

Server di pubblicazione dei controlli di integrità

Quando IHealthCheckPublisher viene aggiunto al contenitore del servizio, il sistema di controllo dell'integrità esegue periodicamente i controlli di integrità e chiama PublishAsync con il risultato. Questo processo è utile in uno scenario di sistema di monitoraggio dell'integrità basato su push che prevede che ogni processo chiami periodicamente il sistema di monitoraggio per determinare l'integrità.

HealthCheckPublisherOptions consente di impostare:

• Delay: ritardo iniziale applicato dopo l'avvio dell'app prima dell'esecuzione delle IHealthCheckPublisher istanze. Il ritardo viene applicato una sola volta all'avvio e non si applica alle iterazioni successive. Il valore predefinito è cinque secondi.
• Period: periodo di IHealthCheckPublisher esecuzione. Il valore predefinito è 30 secondi.
• Predicate: se Predicate è null (impostazione predefinita), il servizio di pubblicazione controllo integrità esegue tutti i controlli di integrità registrati. Per eseguire un subset dei controlli di integrità, specificare una funzione che filtra il set di controlli. Il predicato viene valutato per ogni periodo.
• Timeout: timeout per l'esecuzione dei controlli di integrità per tutte le IHealthCheckPublisher istanze. Usare InfiniteTimeSpan per l'esecuzione senza un timeout. Il valore predefinito è 30 secondi.

Nell'esempio seguente viene illustrato il layout di un editore di integrità:

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

        return Task.CompletedTask;
    }
}

La HealthCheckPublisherOptions classe fornisce proprietà per la configurazione del comportamento dell'autore del controllo integrità.

Nell'esempio seguente viene registrato un server di pubblicazione del controllo integrità come singleton e viene configurato 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:

• Include editori per diversi sistemi, tra cui Application Insights.
• Non è gestito o supportato da Microsoft.

Controlli di integrità individuali

Delay e Period possono essere impostati singolarmente HealthCheckRegistration . Ciò è utile quando si desidera eseguire alcuni controlli di integrità a una velocità diversa rispetto al periodo impostato in HealthCheckPublisherOptions.

Il codice seguente imposta e Delay Period per :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();

Inserimento delle dipendenze e controlli di integrità

È possibile usare l'inserimento delle dipendenze per utilizzare un'istanza di un oggetto specifico Type all'interno di una classe Controllo integrità. L'inserimento delle dipendenze può essere utile per inserire opzioni o una configurazione globale in un controllo integrità. L'uso dell'inserimento delle dipendenze non è uno scenario comune per configurare i controlli di integrità. In genere, ogni controllo integrità è piuttosto specifico del test effettivo ed è configurato usando IHealthChecksBuilder i metodi di estensione.

L'esempio seguente mostra un esempio di controllo integrità che recupera un oggetto di configurazione tramite l'inserimento delle dipendenze:

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

E SampleHealthCheckWithDiConfig il controllo integrità deve essere aggiunto al contenitore del servizio :

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 e MapHealthChecks

Esistono due modi per rendere i controlli di integrità accessibili ai chiamanti:

• UseHealthChecks registra il middleware per la gestione delle richieste di controlli di integrità nella pipeline middleware.
• MapHealthChecks registra un endpoint dei controlli di integrità. L'endpoint viene confrontato ed eseguito insieme ad altri endpoint nell'app.

Il vantaggio dell'uso MapHealthChecks di oltre UseHealthChecks è la possibilità di usare il middleware con riconoscimento degli endpoint, ad esempio l'autorizzazione, e di avere un maggiore controllo granulare sui criteri di corrispondenza. Il vantaggio principale dell'uso UseHealthChecks di over MapHealthChecks è controllare esattamente dove vengono eseguiti i controlli di integrità nella pipeline middleware.

UseHealthChecks:

• Termina la pipeline quando una richiesta corrisponde all'endpoint del controllo integrità. Il corto circuito è spesso auspicabile perché evita operazioni non necessarie, ad esempio la registrazione e altri middleware.
• Viene usato principalmente per configurare il middleware di controllo integrità nella pipeline.
• Può corrispondere a qualsiasi percorso di una porta con un null oggetto o vuoto PathString. Consente di eseguire un controllo di integrità su qualsiasi richiesta effettuata sulla porta specificata.
• Codice sorgente

MapHealthChecks Permette:

• Terminando la pipeline quando una richiesta corrisponde all'endpoint del controllo integrità, chiamando ShortCircuit. Ad esempio: app.MapHealthChecks("/healthz").ShortCircuit();. Per altre informazioni, vedere Middleware a corto circuito dopo il routing.
• Mapping di route o endpoint specifici per i controlli di integrità.
• Personalizzazione dell'URL o del percorso in cui l'endpoint del controllo integrità è accessibile.
• Mapping di più endpoint di controllo integrità con route o configurazioni diverse. Supporto di più endpoint:
  • Abilita endpoint separati per diversi tipi di controlli di integrità o componenti.
  • Viene usato per distinguere i diversi aspetti dell'integrità dell'app o applicare configurazioni specifiche ai subset di controlli di integrità.
• Codice sorgente

Risorse aggiuntive

• Visualizzare o scaricare il codice di esempio (procedura per il download)

Nota

Questo articolo è stato in parte creato con l'aiuto dell'intelligenza artificiale. Prima della pubblicazione, un autore ha rivisto e revisionato il contenuto secondo necessità. Vedere I nostri principi per l'uso di contenuto generato da intelligenza artificiale in Microsoft Learn.