Verificações de integridade no ASP.NET Core

Por Glenn Condron e Juergen Gutsch

O ASP.NET Core oferece o Middleware de Verificações de Integridade e bibliotecas para relatar a integridade de componentes de infraestrutura do aplicativo.

As verificações de integridade são expostas por um aplicativo como pontos de extremidade HTTP. Os pontos de extremidade de verificação de integridade podem ser configurados para vários cenários de monitoramento em tempo real:

• As investigações de integridade podem ser usadas por orquestradores de contêineres e balanceadores de carga para verificar o status de um aplicativo. Por exemplo, um orquestrador de contêineres pode responder a uma verificação de integridade com falha interrompendo uma implantação sem interrupção ou reiniciando um contêiner. Um balanceador de carga pode reagir a um aplicativo não íntegro encaminhando o tráfego para fora da instância com falha para uma instância íntegra.
• O uso de memória, disco e outros recursos de servidor físico pode ser monitorado quanto ao status de integridade.
• As verificações de integridade podem testar as dependências do aplicativo, como bancos de dados e pontos de extremidade de serviço externo, para confirmar a disponibilidade e o funcionamento normal.

As verificações de integridade são normalmente usadas com um orquestrador de contêineres ou um serviço de monitoramento externo para verificar o status de um aplicativo. Antes de adicionar verificações de integridade a um aplicativo, decida qual sistema de monitoramento será usado. O sistema de monitoramento determina quais tipos de verificações de integridade serão criados e como configurar seus pontos de extremidade.

Investigação de integridade básica

Para muitos aplicativos, uma configuração básica de investigação de integridade que relata a disponibilidade do aplicativo para processar solicitações (atividade) é suficiente para descobrir o status do aplicativo.

A configuração básica registra os serviços de verificação de integridade e chama o Middleware de Verificações de Integridade para responder a um ponto de extremidade de URL com uma resposta de integridade. Por padrão, nenhuma verificação de integridade específica é registrada para testar qualquer dependência ou subsistema específico. O aplicativo é considerado íntegro se consegue responder na URL do ponto de extremidade de integridade. O gravador de resposta padrão grava HealthStatus como uma resposta de texto sem formatação para o cliente. O HealthStatus é HealthStatus.Healthy, HealthStatus.Degradedou HealthStatus.Unhealthy.

Registre os serviços de verificação de integridade com AddHealthChecks em Program.cs. Crie um ponto de extremidade de verificação de integridade chamando MapHealthChecks.

O exemplo a seguir cria um ponto de extremidade de verificação de integridade em /healthz:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Docker HEALTHCHECK

O Docker oferece uma diretiva HEALTHCHECK interna que pode ser usada para verificar o status de um aplicativo que usa a configuração básica de verificação de integridade:

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

O exemplo anterior usa curl para fazer uma solicitação HTTP para o ponto de extremidade de verificação de integridade em /healthz. curl não está incluído nas imagens de contêiner do .NET Linux, mas pode ser adicionado instalando o pacote necessário no Dockerfile. Os contêineres que usam imagens com base no Alpine Linux podem usar o wget incluído ao invés de curl.

Criar verificações de integridade

As verificações de integridade são criadas pela implementação da interface IHealthCheck. O método CheckHealthAsync retorna um HealthCheckResult que indica a integridade como Healthy, Degraded ou Unhealthy. O resultado é gravado como uma resposta de texto sem formatação com um código de status configurável. A configuração é descrita na seção Opções de verificação de integridade. HealthCheckResult também pode retornar pares chave-valor opcionais.

O exemplo a seguir demonstra o layout de uma verificação de integridade:

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

A lógica da verificação de integridade é colocada no método CheckHealthAsync. O exemplo anterior define uma variável fictícia, isHealthy, como true. Se o valor de isHealthy for definido como false, o status de HealthCheckRegistration.FailureStatus será retornado.

Se CheckHealthAsync gerar uma exceção durante a verificação, um novo HealthReportEntry será retornado com seu HealthReportEntry.Status definido como FailureStatus. Esse status é definido por AddCheck (consulte a seção Registrar serviços de verificação de integridade) e inclui a exceção interna que causou a falha de verificação. O Description é definido como a mensagem da exceção.

Registrar os serviços de verificação de integridade

Para registrar um serviço de verificação de integridade, chame AddCheck em Program.cs:

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

A sobrecarga AddCheck mostrada no exemplo a seguir define o status de falha (HealthStatus) como relatório quando a verificação de integridade relata uma falha. Se o status de falha é definido como null (padrão), HealthStatus.Unhealthy é relatado. Essa sobrecarga é um cenário útil para autores de biblioteca, em que o status de falha indicado pela biblioteca é imposto pelo aplicativo quando uma falha de verificação de integridade ocorre se a implementação da verificação de integridade respeita a configuração.

Marcações podem ser usadas para filtrar verificações de integridade. As marcações são descritas na seção Filtrar verificações de integridade.

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

AddCheck também pode executar uma função lambda. No exemplo a seguir, a verificação de integridade sempre retorna um resultado íntegro:

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

Chame AddTypeActivatedCheck para aprovar argumentos para uma implementação de verificação de integridade. No exemplo a seguir, uma verificação de integridade ativada por tipo aceita um inteiro e uma cadeia de caracteres em seu construtor:

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

Para registrar a verificação de integridade anterior, chame AddTypeActivatedCheck com o inteiro e a cadeia de caracteres aprovados como argumentos:

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

Usar roteamento de verificações de integridade

No Program.cs, chame MapHealthChecks no construtor de ponto de extremidade com a URL de ponto de extremidade ou o caminho relativo:

app.MapHealthChecks("/healthz");

Exigir host

Chame RequireHost para especificar um ou mais hosts permitidos para o ponto de extremidade de verificação de integridade. Os hosts devem ser Unicode em vez de punycode e podem incluir uma porta. Se uma coleção não for fornecida, qualquer host será aceito:

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

Para restringir o ponto de extremidade de verificação de integridade para responder somente em uma determinada porta, especifique uma porta na chamada para RequireHost. Essa abordagem normalmente é usada em um ambiente de contêiner para expor uma porta para os serviços de monitoramento:

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

Aviso

Uma API que dependa do cabeçalho de host, como HttpRequest.Host e RequireHost, está sujeita a possíveis falsificações por clientes.

Para evitar falsificação de host e porta, use uma das seguintes abordagens:

• Use HttpContext.Connection (ConnectionInfo.LocalPort) onde as portas são verificadas.
• Empregar filtragem de host.

Para impedir que clientes não autorizados falsifiquem a porta, chame RequireAuthorization:

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

Para obter mais informações, consulte Correspondência de host em rotas com RequireHost.

Exigir autorização

Chame RequireAuthorization para executar o Middleware de autorização no ponto de extremidade da solicitação de verificação de integridade. Uma sobrecarga RequireAuthorization aceita uma ou mais políticas de autorização. Se uma política não for fornecida, a política de autorização padrão será usada:

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

Habilitar o CORS (Solicitações Entre Origens)

Embora a execução manual das verificações de integridade de um navegador não seja um cenário comum, o Middleware CORS pode ser habilitado chamando RequireCors nos pontos de extremidade das verificações de integridade. A sobrecarga RequireCors aceita um representante do construtor de políticas CORS (CorsPolicyBuilder) ou um nome de política. Para obter mais informações, consulte Habilitar solicitações entre origens (CORS, na sigla em inglês) no ASP.NET Core.

Opções de verificação de integridade

HealthCheckOptions oferece uma oportunidade de personalizar o comportamento de verificação de integridade:

• Filtrar verificações de integridade
• Personalizar o código de status HTTP
• Suprimir os cabeçalhos de cache
• Personalizar a saída

Filtrar verificações de integridade

Por padrão, o Middleware de verificações de integridade executa todas as verificações de integridade registradas. Para executar um subconjunto das verificações de integridade, forneça uma função que retorne um booliano para a opção Predicate.

O exemplo a seguir filtra as verificações de integridade para que somente aquelas marcadas com sample sejam executadas:

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

Personalizar o código de status HTTP

Use ResultStatusCodes para personalizar o mapeamento de status da integridade para códigos de status HTTP. As atribuições StatusCodes a seguir são os valores padrão usados pelo middleware. Altere os valores do código de status de acordo com suas necessidades:

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

Suprimir os cabeçalhos de cache

AllowCachingResponses controla se o Middleware de verificações de integridade adiciona cabeçalhos HTTP a uma resposta de investigação para prevenir o cache de resposta. Se o valor é false (padrão), o middleware define ou substitui os cabeçalhos Cache-Control, Expires e Pragma para prevenir o cache de resposta. Se o valor for true, o middleware não modifica os cabeçalhos de cache da resposta:

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

Personalizar a saída

Para personalizar a saída de um relatório de verificações de integridade, defina a propriedade HealthCheckOptions.ResponseWriter como um representante que grava a resposta:

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

O representante padrão grava uma resposta mínima de texto sem formatação com o valor de cadeia de caracteres HealthReport.Status. O representante personalizado a seguir gera uma JSresposta ON personalizada 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()));
}

A API de verificações de integridade não fornece suporte interno para formatos de retorno JSON complexos porque o formato é específico para sua escolha de sistema de monitoramento. Personalize a resposta nos exemplos anteriores, conforme necessário. Para obter mais informações sobre a serialização JSON com System.Text.Json, consulte Como serializar e desserializar JSON no .NET.

Investigação de banco de dados

Uma verificação de integridade pode especificar uma consulta de banco de dados a ser executada como um teste booliano para indicar se o banco de dados está respondendo normalmente.

AspNetCore.Diagnostics.HealthChecks, uma biblioteca de verificação de integridade para aplicativos do ASP.NET Core, inclui uma verificação de integridade executada em um banco de dados do SQL Server. O AspNetCore.Diagnostics.HealthChecks executa uma consulta SELECT 1 no banco de dados para confirmar se a conexão ao banco de dados está íntegra.

Aviso

Ao verificar uma conexão de banco de dados com uma consulta, escolha uma consulta que retorne rapidamente. A abordagem de consulta corre o risco de sobrecarregar o banco de dados e prejudicar o desempenho. Na maioria dos casos, a execução de uma consulta de teste não é necessária. É suficiente apenas estabelecer uma conexão bem-sucedida ao banco de dados. Se você achar necessário executar uma consulta, escolha uma consulta SELECT simples, como SELECT 1.

Para usar essa verificação de integridade do SQL Server, inclua uma referência de pacote ao pacote AspNetCore.HealthChecks.SqlServer NuGet. O exemplo a seguir registra a verificação de integridade do 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);

Observação

O AspNetCore.Diagnostics.HealthChecks não é mantido nem tem suporte da Microsoft.

Investigação de DbContext do Entity Framework Core

A verificação DbContext confirma se o aplicativo pode se comunicar com o banco de dados configurado para um EF CoreDbContext. A verificação DbContext é compatível em aplicativos que:

• Usam o EF (Entity Framework) Core.
• Inclui uma referência de pacote ao pacote Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore NuGet.

AddDbContextCheck registra uma verificação de integridade para um DbContext. O DbContext é fornecido ao método como o TContext. Uma sobrecarga está disponível para configurar o status de falha, marcas e uma consulta de teste personalizada.

Por padrão:

• O DbContextHealthCheck chama o método CanConnectAsync do EF Core. Você pode personalizar qual operação é executada durante a verificação de integridade usando sobrecargas do método AddDbContextCheck.
• O nome da verificação de integridade é o nome do tipo TContext.

O exemplo a seguir registra um DbContext e um DbContextHealthCheck associado:

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

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

Investigações de preparação e atividade separadas

Em alguns cenários de hospedagem, é usado um par de verificações de integridade que distingue dois estados de aplicativo:

• Preparação indica se o aplicativo está em execução normalmente, mas não está pronto para receber solicitações.
• Atividade indica se um aplicativo falhou e deve ser reiniciado.

Considere o exemplo a seguir: um aplicativo deve baixar um arquivo de configuração grande antes de estar pronto para processar solicitações. Não queremos que o aplicativo seja reiniciado se o download inicial falhar porque o aplicativo pode tentar baixar o arquivo novamente várias vezes. Usamos uma investigação de atividade para descrever a atividade do processo; nenhuma outra verificação é executada. Também queremos impedir que as solicitações sejam enviadas ao aplicativo antes que o download do arquivo de configuração seja bem-sucedido. Usamos uma investigação de preparação para indicar um estado "não pronto" até que o download seja bem-sucedido e o aplicativo esteja pronto para receber solicitações.

A tarefa em segundo plano a seguir simula um processo de inicialização que leva cerca de 15 segundos. Depois de concluída, a tarefa define a propriedade StartupHealthCheck.StartupCompleted como 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;
    }
}

O StartupHealthCheck relata a conclusão da tarefa de inicialização de execução prolongada e expõe a propriedade StartupCompleted que é definida pelo serviço em segundo plano:

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

A verificação de integridade é registrada em AddCheck no Program.cs juntamente com o serviço hospedado. Como o serviço hospedado precisa definir a propriedade na verificação de integridade, a verificação de integridade também é registrada no contêiner de serviço como um banco de dados individual:

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

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

Para criar dois pontos de extremidade de verificação de integridade diferentes, chame MapHealthChecks duas vezes:

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

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

O exemplo anterior cria os seguintes pontos de extremidade de verificação de integridade:

• /healthz/ready para a verificação de preparação. A verificação de preparação filtra as verificações de integridade para aquelas marcadas com ready.
• /healthz/live para a verificação de atividade. A verificação de atividade filtra todas as verificações de integridade retornando false no representante HealthCheckOptions.Predicate. Para obter mais informações sobre como filtrar verificações de integridade, consulte Filtrar verificações de integridade neste artigo.

Antes da conclusão da tarefa de inicialização, o ponto de extremidade /healthz/ready relata um status Unhealthy. Depois que a tarefa de inicialização for concluída, esse ponto de extremidade relatará um status Healthy. O ponto de extremidade /healthz/live exclui todas as verificações e relata um status Healthy para todas as chamadas.

Exemplo do Kubernetes

O uso de verificações de preparação e atividade separadas é útil em um ambiente como o Kubernetes. No Kubernetes, um aplicativo pode precisar executar um trabalho de inicialização demorado antes de aceitar solicitações, como um teste da disponibilidade do banco de dados subjacente. O uso de verificações separadas permite que o orquestrador distinga se o aplicativo está funcionando, mas ainda não está pronto, ou se o aplicativo falhou ao ser iniciado. Para obter mais informações sobre as investigações de preparação e atividade no Kubernetes, confira Configurar investigações de preparação e atividade na documentação do Kubernetes.

O seguinte exemplo demonstra uma configuração de investigação de preparação do 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

Distribuir uma biblioteca de verificação de integridade

Para distribuir uma verificação de integridade como uma biblioteca:

1. Escreva uma verificação de integridade que implementa a interface IHealthCheck como uma classe autônoma. A classe pode depender da DI (injeção de dependência), da ativação de tipo e das opções nomeadas para acessar os dados de configuração.

2. Escreva um método de extensão com parâmetros que o aplicativo de consumo chama em seu método Program.cs. Considere o exemplo a seguir de verificação de integridade, que aceita arg1 e arg2 como parâmetros de construtor:

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

   A assinatura anterior indica que a verificação de integridade exige dados personalizados para processar a lógica de investigação da verificação de integridade. Os dados são fornecidos para o representante usado para criar a instância de verificação de integridade quando a verificação de integridade é registrada em um método de extensão. No exemplo a seguir, o chamador especifica:

   • arg1: um ponto de dados de inteiro para a verificação de integridade.
   • arg2: um argumento de cadeia de caracteres para a verificação de integridade.
   • name: um nome de verificação de integridade opcional. Se null, o valor padrão é usado.
   • failureStatus: um HealthStatus opcional, que é relatado para um status de falha. Se null, HealthStatus.Unhealthy é usado.
   • tags: uma coleção IEnumerable<string> opcional de marcações.

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

Publicador de Verificação de Integridade

Quando um IHealthCheckPublisher é adicionado ao contêiner de serviços, o sistema de verificação de integridade periodicamente executa sua verificação de integridade e chama PublishAsync com o resultado. Esse processo é útil em um cenário de sistema de monitoramento de integridade baseado em push que espera que cada processo chame o sistema de monitoramento periodicamente para determinar a integridade.

HealthCheckPublisherOptions permite que você defina:

• Delay: o atraso inicial aplicado após o aplicativo começar antes de executar instâncias IHealthCheckPublisher. O atraso é aplicado uma vez na inicialização e não ocorre em iterações posteriores. O valor padrão é cinco segundos.
• Period: o período da execução de IHealthCheckPublisher. O valor padrão é 30 segundos.
• Predicate: se Predicate for null (padrão), o serviço do publicador de verificação de integridade executará todas as verificações de integridade registradas. Para executar um subconjunto das verificações de integridade, forneça uma função que filtre o conjunto de verificações. O predicado é avaliado a cada período.
• Timeout: o tempo limite para a execução de verificações de integridade em todas as instâncias IHealthCheckPublisher. Use InfiniteTimeSpan para executar sem um tempo limite. O valor padrão é 30 segundos.

O exemplo a seguir demonstra o layout de um publicador de integridade:

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

        return Task.CompletedTask;
    }
}

A classe HealthCheckPublisherOptions fornece propriedades para configurar o comportamento do publicador de verificação de integridade.

O exemplo a seguir registra um publicador de verificação de integridade como um banco de dados individual e configura 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:

• Inclui publicadores para vários sistemas, inclusive o Application Insights.
• Não é mantido ou com suporte da Microsoft.

Verificações de integridade individuais

Delay e Period pode ser definido em cada HealthCheckRegistration individualmente. Isso é útil quando você deseja executar algumas verificações de integridade a uma taxa diferente do período definido em HealthCheckPublisherOptions.

O código a seguir define o Delay e Period para o 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();

Injeção de dependência e verificações de integridade

É possível usar a injeção de dependência para consumir uma instância de um Type específico dentro de uma classe de Verificação de Integridade. A injeção de dependência pode ser útil para injetar opções ou uma configuração global em uma Verificação de Integridade. O uso da injeção de dependência não é um cenário comum para configurar verificações de integridade. Normalmente, cada Verificação de Integridade é bastante específica para o teste real e é configurada usando métodos de extensão IHealthChecksBuilder.

O exemplo a seguir exibe uma amostra de Verificação de Integridade que recupera um objeto de configuração por meio da injeção de dependência:

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

O SampleHealthCheckWithDiConfig e a verificação de integridade precisam ser adicionados ao contêiner de serviço :

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

Há duas maneiras de tornar as verificações de integridade acessíveis aos chamadores:

• UseHealthChecks registra o middleware para lidar com solicitações de verificação de integridade no pipeline de middleware.
• MapHealthChecks registra um ponto de extremidade de verificação de integridade. O ponto de extremidade é correspondido e executado junto com outros pontos de extremidade no aplicativo.

A vantagem de usar MapHealthChecks em vez de UseHealthChecks é a capacidade de usar middleware com reconhecimento de ponto de extremidade, como uma autorização, e ter maior controle refinado sobre a política de correspondência. A principal vantagem de usar UseHealthChecks em vez de MapHealthChecks é controlar exatamente onde as verificações de integridade são executadas no pipeline do middleware.

UseHealthChecks:

• Encerra o pipeline quando uma solicitação corresponde ao ponto de extremidade de verificação de integridade. O curto-circuito geralmente é desejável porque evita trabalhos desnecessários, como registro em log e outro middleware.
• É usado principalmente para configurar o middleware de verificação de integridade no pipeline.
• Pode corresponder qualquer caminho em uma porta com um null ou PathString vazio. Permite executar uma verificação de integridade em qualquer solicitação feita à porta especificada.
• Código-fonte

MapHealthChecks permite:

• Encerrar o pipeline quando uma solicitação corresponde ao ponto de extremidade de verificação de integridade, chamando ShortCircuit. Por exemplo, app.MapHealthChecks("/healthz").ShortCircuit();. Para obter mais informações, consulte middleware de curto-circuito após o roteamento.
• Mapear rotas ou pontos de extremidade específicos para verificações de integridade.
• Personalizar o URL ou caminho em que o ponto de extremidade de verificação de integridade está acessível.
• Mapear vários pontos de extremidade de verificação de integridade com diferentes rotas ou configurações. Suporte a vários pontos de extremidade:
  • Habilita pontos de extremidade separados para diferentes tipos de verificações de integridade ou componentes.
  • É usado para diferenciar entre aspectos distintos da integridade do aplicativo ou aplicar configurações específicas a subconjuntos de verificações de integridade.
• Código-fonte

Recursos adicionais

• Exibir ou baixar código de exemplo (como baixar)

Observação

Este artigo foi parcialmente criado com a ajuda de inteligência artificial. Antes de publicar, um autor revisou o conteúdo conforme necessário. Confira Nossos princípios para usar o conteúdo gerado por IA no Microsoft Learn.