Comprobaciones de estado en ASP.NET Core

Por Glenn Condron y Juergen Gutsch

ASP.NET Core ofrece el middleware de comprobaciones de estado y bibliotecas para informar sobre el estado de los componentes de la infraestructura de la aplicación.

Una aplicación se encarga de exponer las comprobaciones de estado como puntos de conexión HTTP. Los puntos de conexión de las comprobaciones de estado pueden configurarse para diversos escenarios de supervisión en tiempo real:

• Los orquestadores de contenedores y los equilibradores de carga pueden utilizar los sondeos de estado para comprobar el estado de una aplicación. Por ejemplo, para responder a una comprobación de estado con errores, es posible que un orquestador de contenedores detenga una implementación en curso o reinicie un contenedor. Como respuesta a una aplicación con estado incorrecto, es posible que un equilibrador de carga enrute el tráfico al margen de la instancia con errores hacia una instancia con estado correcto.
• El uso de la memoria, el disco y otros recursos del servidor físico puede supervisarse para determinar si el estado es correcto.
• Las comprobaciones de estado pueden probar las dependencias de una aplicación, como las bases de datos y los puntos de conexión de servicio externo, para confirmar la disponibilidad y el funcionamiento normal.

Normalmente, las comprobaciones de estado se usan con un servicio de supervisión externa o un orquestador de contenedores para comprobar el estado de una aplicación. Antes de agregar comprobaciones de estado a una aplicación, debe decidir en qué sistema de supervisión se va a usar. El sistema de supervisión determina qué tipos de comprobaciones de estado se deben crear y cómo configurar sus puntos de conexión.

Sondeo de estado básico

Para muchas aplicaciones, una configuración de sondeo de estado básico que notifique la disponibilidad de la aplicación para procesar las solicitudes (ejecución) es suficiente para detectar el estado de la aplicación.

La configuración básica registra los servicios de comprobación de estado y llama al middleware de comprobaciones de estado para responder a un punto de conexión de dirección URL con una respuesta de estado. De forma predeterminada, no se registran comprobaciones de estado específicas para probar cualquier dependencia o subsistema concretos. La aplicación se considera en buen estado si puede responder en la dirección URL del punto de conexión de mantenimiento. El escritor de respuestas predeterminado escribe HealthStatus como una respuesta de texto no cifrado en el cliente. HealthStatus es HealthStatus.Healthy, HealthStatus.Degraded o HealthStatus.Unhealthy.

Registre los servicios de comprobación de estado con AddHealthChecks de Program.cs. Cree un punto de conexión de comprobación de estado llamando a MapHealthChecks.

En el ejemplo siguiente se crea un punto de conexión de comprobación de estado en /healthz:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHealthChecks();

var app = builder.Build();

app.MapHealthChecks("/healthz");

app.Run();

Docker HEALTHCHECK

Docker ofrece una directiva de HEALTHCHECK integrada que puede utilizarse para comprobar el estado de una aplicación que use la configuración de comprobación de estado básica:

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

El ejemplo anterior utiliza curl para hacer una solicitud HTTP al punto de conexión de comprobación de estado en /healthz. curl no se incluye en las imágenes de contenedor de Linux de .NET, pero se puede agregar instalando el paquete necesario en Dockerfile. Los contenedores que usan imágenes basadas en Alpine Linux pueden usar el wget incluido en lugar de curl.

Creación de comprobaciones de estado

Las comprobaciones de estado se crean mediante la implementación de la interfaz de IHealthCheck. El método CheckHealthAsync devuelve un elemento HealthCheckResult que indica el estado como Healthy, Degraded o Unhealthy. El resultado se escribe como una respuesta de texto no cifrado con un código de estado configurable. La configuración se describe en la sección Opciones de comprobación de estado. HealthCheckResult también puede devolver pares clave-valor opcionales.

En el ejemplo siguiente se muestra el diseño de una comprobación de estado:

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 lógica de comprobaciones de estado se coloca en el método CheckHealthAsync. En el ejemplo siguiente se establece una variable ficticia, isHealthy, en true. Si el valor de isHealthy se establece en false, se devuelve el estado HealthCheckRegistration.FailureStatus.

Si CheckHealthAsync produce una excepción durante la comprobación, se devuelve un nuevo HealthReportEntry con su HealthReportEntry.Status establecido en FailureStatus. Este estado se define mediante AddCheck (consulte la sección Registro de los servicios de comprobación de estado) e incluye la excepción interna que produjo el error de comprobación. Description se establece en el mensaje de la excepción.

Registro de los servicios de comprobación de estado

Para registrar un servicio de comprobación de estado, llame a AddCheck en Program.cs:

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

La sobrecarga AddCheck que se muestra en el ejemplo siguiente establece el estado de error (HealthStatus) para notificar cuándo la comprobación de estado informa de un error. Si el estado de error se establece en null (valor predeterminado), HealthStatus.Unhealthy se notifica. Esta sobrecarga es un escenario útil para los creadores de bibliotecas en los que la aplicación ejecuta el estado de error indicado por la biblioteca cuando se produce un error de comprobación de estado si la implementación de la comprobación de estado respeta la configuración.

Las etiquetas se pueden usar para filtrar las comprobaciones de estado. Las etiquetas se describen en la sección Filtrado de comprobaciones de estado.

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

AddCheck también puede ejecutar una función lambda. En el ejemplo siguiente, la comprobación de estado siempre devuelve un resultado correcto:

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

Llame a AddTypeActivatedCheck para pasar argumentos a una implementación de comprobación de estado. En el ejemplo siguiente, una comprobación de estado activada por tipo acepta un entero y una cadena en su constructor:

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 la comprobación de estado anterior, llame a AddTypeActivatedCheck con el entero y la cadena pasados como argumentos:

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

Uso del enrutamiento de comprobaciones de estado

En Program.cs, llame a MapHealthChecks en el generador de puntos de conexiones con la dirección URL del punto de conexión o la ruta de acceso relativa:

app.MapHealthChecks("/healthz");

Requerimiento de host

Llame RequireHost a para especificar uno o más hosts permitidos para el punto de conexión de comprobación de estado. Los hosts deben ser Unicode en lugar de Punycode y pueden incluir un puerto. Si no se proporciona una colección, se acepta cualquier host:

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

Para restringir el punto de conexión de comprobación de estado para que responda solo en un puerto específico, especifique un puerto en la llamada a RequireHost. Este enfoque se usa normalmente en un entorno de contenedor para exponer un puerto para los servicios de supervisión:

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

Advertencia

Las API que se basan en el encabezado host, como HttpRequest.Host y RequireHost, están sujetas a una posible suplantación de identidad por parte de los clientes.

Para evitar la suplantación de identidad de host y puerto, use uno de los métodos siguientes:

• Use HttpContext.Connection (ConnectionInfo.LocalPort) donde se comprueban los puertos.
• Emplee el filtrado de hosts.

Para evitar que los clientes no autorizados suplanten el puerto, llame a RequireAuthorization:

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

Para obtener más información, consulte Comparación de host en rutas con RequireHost.

Requerimiento de autorización

Llame a RequireAuthorization para ejecutar el middleware de autorización en el punto de conexión de solicitudes de comprobación de estado. Una sobrecarga RequireAuthorization acepta una o varias directivas de autorización. Si no se proporciona una directiva, se usa la directiva de autorización predeterminada:

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

Habilitar solicitudes entre orígenes (CORS)

Aunque no se suelen ejecutar comprobaciones de estado manualmente desde un explorador, el middleware de CORS se puede habilitar mediante una llamada a RequireCors en los puntos de conexión de las comprobaciones de estado. La sobrecarga de RequireCors acepta un delegado del generador de directivas CORS (CorsPolicyBuilder) o un nombre de directiva. Para obtener más información, vea Habilitar solicitudes entre orígenes (CORS) en ASP.NET Core.

Opciones de comprobación de estado

El elemento HealthCheckOptions ofrece una oportunidad para personalizar el comportamiento de las comprobaciones de estado:

• Filtrado de las comprobaciones de estado
• Personalización del código de estado HTTP
• Supresión de los encabezados de caché
• Personalización del resultado

Filtrado de las comprobaciones de estado

De forma predeterminada, el middleware de comprobaciones de estado ejecuta todas las comprobaciones de estado registradas. Para ejecutar un subconjunto de comprobaciones de estado, proporcione una función que devuelva un valor booleano para la opción Predicate.

En el ejemplo siguiente se filtran las comprobaciones de estado para que solo se ejecuten aquellas etiquetadas con sample:

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

Personalización del código de estado HTTP

Use ResultStatusCodes para personalizar la asignación del estado de mantenimiento de los códigos de estado HTTP. Las siguientes asignaciones de StatusCodes son los valores predeterminados que el middleware utiliza. Cambie los valores de código de estado para satisfacer sus necesidades:

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

Supresión de los encabezados de caché

AllowCachingResponses controla si el middleware de comprobaciones de estado agrega encabezados HTTP a una respuesta de sondeo para evitar el almacenamiento en caché de respuesta. Si el valor es false (valor predeterminado), el middleware establece o invalida los encabezados Cache-Control, Expires y Pragma para evitar el almacenamiento en caché de respuesta. Si el valor es true, el middleware no modifica los encabezados de caché de la respuesta:

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

Personalización del resultado

Para personalizar la salida de un informe de comprobaciones de estado, establezca la propiedad HealthCheckOptions.ResponseWriter en un delegado que escriba la respuesta:

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

El delegado predeterminado escribe una respuesta de texto no cifrado mínima con el valor de cadena HealthReport.Status. El siguiente delegado personalizado genera una respuesta JSON personalizada mediante 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()));
}

La API de comprobaciones de estado no ofrece compatibilidad integrada con formatos de retorno JSON complejos porque el formato es específico del sistema de supervisión elegido. Personalice la respuesta en los ejemplos anteriores según sea necesario. Para más información sobre la serialización de JSON con System.Text.Json, consulte Procedimiento para serializar y deserializar JSON en .NET.

Sondeo de bases de datos

Una comprobación de estado puede especificar que una consulta de base de datos se ejecute como una prueba booleana para indicar si esta responde con normalidad.

AspNetCore.Diagnostics.HealthChecks, una biblioteca de comprobación de estado para aplicaciones ASP.NET Core, incluye una comprobación de estado que se ejecuta en una base de datos SQL Server. AspNetCore.Diagnostics.HealthChecks ejecuta una consulta SELECT 1 en la base de datos para confirmar que la conexión a la base de datos es correcta.

Advertencia

Al comprobar la conexión de una base de datos a una consulta, elija una consulta que se devuelva rápidamente. El enfoque de la consulta plantea el riesgo de sobrecargar la base de datos y degradar el rendimiento. En la mayoría de los casos, no es necesario ejecutar una consulta de prueba. Simplemente, realizar una conexión correcta a la base de datos es suficiente. Si resulta necesario ejecutar una consulta, elija una consulta SELECT sencilla, como SELECT 1.

Para utilizar esta comprobación de estado de SQL Server, incluya una referencia al paquete NuGet AspNetCore.HealthChecks.SqlServer. En el ejemplo siguiente se registra la comprobación de estado de 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

Microsoft no mantiene ni admite AspNetCore.Diagnostics.HealthChecks.

Sondeo de DbContext de Entity Framework Core

La comprobación DbContext confirma que la aplicación puede comunicarse con la base de datos configurada para un elemento DbContext de EF Core. La comprobación DbContext se admite en las aplicaciones que:

• Usan Entity Framework (EF) Core.
• Incluya una referencia al paquete NuGet Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore.

AddDbContextCheck registra una comprobación de estado para un elemento DbContext. El elemento DbContext se proporciona al método como TContext. Hay disponible una sobrecarga para configurar el estado de error, las etiquetas y una consulta de prueba personalizada.

De manera predeterminada:

• DbContextHealthCheck llama al método CanConnectAsync de EF Core. Se puede personalizar qué operación se ejecuta al comprobar el estado con sobrecargas del método AddDbContextCheck.
• El nombre de la comprobación de estado es el nombre del tipo TContext.

En el siguiente ejemplo se registra DbContext y un DbContextHealthCheck asociado:

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

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

Sondeos de preparación y ejecución independientes

En algunos escenarios de hospedaje, se usa un par de comprobaciones de estado que distinguen dos estados de la aplicación:

• Preparación indica si la aplicación se ejecuta con normalidad, pero no está lista para recibir solicitudes.
• Ejecución indica si una aplicación se ha bloqueado y debe reiniciarse.

Considere el ejemplo siguiente: Antes de estar lista para procesar solicitudes, una aplicación debe descargar un archivo de configuración de gran tamaño. No queremos que se reinicie la aplicación si se produce un error en la descarga inicial, dado que la aplicación puede volver a intentar descargar el archivo varias veces. Usamos un sondeo de ejecución para describir la ejecución del proceso, sin realizar ninguna otra comprobación. También queremos evitar que las solicitudes se envíen a la aplicación antes de que finalice la descarga del archivo de configuración. Hasta que no finaliza la descarga y la aplicación está lista para recibir solicitudes, usamos un sondeo de preparación para indicar un estado "no preparado".

La siguiente tarea en segundo plano simula un proceso de inicio que tarda aproximadamente 15 segundos. Una vez que se completa, la tarea establece la propiedad StartupHealthCheck.StartupCompleted en 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 notifica la finalización de la tarea de inicio de ejecución prolongada y expone la propiedad StartupCompleted establecida por el servicio en 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."));
    }
}

La comprobación de estado se registra con AddCheck en Program.cs junto con el servicio hospedado. Dado que el servicio hospedado debe establecer la propiedad en la comprobación de estado, esta también se registra en el contenedor de servicios como singleton:

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

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

Para crear dos puntos de conexión de comprobación de estado diferentes, llame a MapHealthChecks dos veces:

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

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

En el ejemplo anterior se crean los siguientes puntos de conexión de comprobación de estado:

• /healthz/ready para la comprobación de la idoneidad. La comprobación de preparación filtra las comprobaciones de estado a las etiquetadas con ready.
• /healthz/live para la comprobación de la ejecución. La comprobación de ejecución filtra todas las comprobaciones de estado devolviendo false en el delegado HealthCheckOptions.Predicate. Para obtener más información sobre el filtrado de comprobaciones de estado, vea Filtrado de las comprobaciones de estado en este artículo.

Antes de que se complete la tarea de inicio, el punto de conexión /healthz/ready notifica un estado Unhealthy. Después de que se complete la tarea de inicio, este punto de conexión notifica un estado Healthy. El punto de conexión /healthz/live excluye todas las comprobaciones e informa de un estado Healthy para todas las llamadas.

Ejemplo de Kubernetes

Utilizar comprobaciones de preparación y ejecución independientes es útil en un entorno como Kubernetes. En Kubernetes, es posible que se requiera una aplicación para ejecutar un trabajo de inicio lento antes de aceptar solicitudes, como una prueba de la disponibilidad de la base de datos subyacente. El hecho de utilizar comprobaciones independientes permite que el orquestador distinga si la aplicación está funcionando, pero aún no esté preparada, o si la aplicación no se ha podido iniciar. Para obtener más información sobre los sondeos de preparación y ejecución en Kubernetes, consulte Configuración de sondeos de preparación y ejecución en la documentación de Kubernetes.

En el ejemplo siguiente, se muestra una configuración de sondeo de preparación de 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

Distribución de una biblioteca de comprobación de estado

Para distribuir una comprobación de estado como una biblioteca, haga lo siguiente:

1. Escriba una comprobación de estado que implemente la interfaz de IHealthCheck como una clase independiente. La clase puede depender de la inserción de dependencias (DI), de la activación del tipo y de las opciones denominadas para acceder a los datos de configuración.

2. Escriba un método de extensión con los parámetros a los que la aplicación de uso llama en su método Program.cs. Considere la siguiente comprobación de estado de ejemplo, que acepta arg1 y arg2 como parámetros de constructor:

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

   La firma anterior indica que la comprobación de estado requiere datos personalizados para procesar la lógica de sondeo de la comprobación de estado. Los datos se proporcionan al delegado que se usa para crear la instancia de la comprobación de estado cuando la comprobación de estado se registra con un método de extensión. En el ejemplo siguiente, el autor de la llamada especifica:

   • arg1: punto de datos de entero para la comprobación de estado.
   • arg2: argumento de cadena para la comprobación de estado.
   • name: nombre de comprobación de estado opcional. Si null, se usa el valor predeterminado.
   • failureStatus: un HealthStatus opcional, que se notifica para un estado de error. En el caso de null, se utiliza HealthStatus.Unhealthy.
   • tags: una colección IEnumerable<string> opcional de etiquetas.

   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 la comprobación de estado

Cuando un elemento IHealthCheckPublisher se agrega al contenedor de servicios, el sistema de comprobación de estado ejecuta periódicamente las comprobaciones de estado y llama a PublishAsync con el resultado. Este proceso es útil en un escenario de sistema de supervisión de estado basado en inserción que espera que cada proceso llame periódicamente al sistema de supervisión para determinar el estado.

HealthCheckPublisherOptions le permiten establecer:

• Delay: el retraso inicial aplicado tras iniciarse la aplicación antes de ejecutar instancias de IHealthCheckPublisher. El retraso se aplica una vez en el inicio y no se aplica a iteraciones posteriores. El valor predeterminado es cinco segundos.
• Period: el período de ejecución de IHealthCheckPublisher. El valor predeterminado es 30 segundos.
• Predicate: si Predicate es null (valor predeterminado), el servicio de publicador de la comprobación de estado ejecuta todas las comprobaciones de estado registradas. Para ejecutar un subconjunto de comprobaciones de estado, proporcione una función que filtre el conjunto de comprobaciones. El predicado se evalúa cada período.
• Timeout: el tiempo de expiración para ejecutar las comprobaciones de estado para todas las instancias de IHealthCheckPublisher. Use InfiniteTimeSpan para ejecutar sin tiempo de expiración. El valor predeterminado es 30 segundos.

En el ejemplo siguiente se muestra el diseño de un publicador de estado:

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

        return Task.CompletedTask;
    }
}

La clase HealthCheckPublisherOptions proporciona propiedades para configurar el comportamiento del publicador de la comprobación de estado.

En el ejemplo siguiente se registra un publicador de comprobación de estado como singleton y se 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:

• incluye editores para varios sistemas, incluido Application Insights.
• Microsoft no realiza su mantenimiento ni su soporte técnico.

Comprobaciones de estado individuales

Delay y Period se pueden establecer en cada HealthCheckRegistration individualmente. Esto resulta útil cuando desea ejecutar algunas comprobaciones de estado a una velocidad diferente del período establecido en HealthCheckPublisherOptions.

El siguiente código establece Delay y Period para 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();

Inserción de dependencias y comprobaciones de estado

Se puede usar la inserción de dependencias para consumir una instancia de un elemento Type específico dentro de una clase de comprobación de estado (Health Check). La inserción de dependencias puede ser útil para insertar opciones o una configuración global en una comprobación de estado. El uso de la inserción de dependencias no es un escenario común para configurar comprobaciones de estado. Normalmente, cada comprobación de estado es bastante específica para la prueba real y se configura mediante métodos de extensión IHealthChecksBuilder.

En el ejemplo siguiente se muestra una comprobación de estado de ejemplo que recupera un objeto de configuración a través de la inserción de dependencias:

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

El elemento SampleHealthCheckWithDiConfig y la comprobación de estado deben agregarse al contenedor de servicios:

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 frente a MapHealthChecks

Hay dos maneras de que las comprobaciones de estado sean accesibles para los autores de llamadas:

• UseHealthChecks registra el middleware para controlar las solicitudes de comprobaciones de estado en la canalización de middleware.
• MapHealthChecks registra un punto de conexión de comprobaciones de estado. El punto de conexión coincide y se ejecuta junto con otros puntos de conexión de la aplicación.

La ventaja de usar MapHealthChecks sobre UseHealthChecks es la capacidad de usar middleware compatible con puntos de conexión, como la autorización, y tener un mayor control específico sobre la directiva de coincidencias. La principal ventaja de usar UseHealthChecks sobre MapHealthChecks es controlar exactamente dónde se ejecutan las comprobaciones de estado en la canalización de middleware.

UseHealthChecks:

• Finaliza la canalización cuando una solicitud coincide con el punto de conexión de comprobación de estado. Un cortocircuito suele ser deseable porque evita el trabajo innecesario, como el registro y otro middleware.
• Se usa principalmente para configurar el middleware de las comprobaciones de estado en la canalización.
• Puede coincidir con cualquier ruta de acceso de un puerto con un null o PathString vacío. Permite realizar una comprobación de estado en cualquier solicitud realizada al puerto especificado.
• Código fuente

MapHealthChecks permite:

• Finalizar la canalización cuando una solicitud coincide con el punto de conexión de comprobación de estado, llamando a ShortCircuit. Por ejemplo: app.MapHealthChecks("/healthz").ShortCircuit();. Para obtener más información, vea Middleware de cortocircuito después del enrutamiento.
• Asignar rutas o puntos de conexión específicos para las comprobaciones de estado.
• Personalización de la dirección URL o ruta de acceso a la que se puede acceder al punto de conexión de la comprobación de estado.
• Asignación de varios puntos de conexión de la comprobación de estado con diferentes rutas o configuraciones. Compatibilidad con varios puntos de conexión:
  • Habilita puntos de conexión independientes para distintos tipos de comprobaciones de estado o componentes.
  • Se usa para diferenciar entre distintos aspectos del estado de la aplicación o aplicar configuraciones específicas a subconjuntos de comprobaciones de estado.
• Código fuente

Recursos adicionales

• Vea o descargue el código de ejemplo (cómo descargarlo)

Nota:

Este artículo se ha creado parcialmente con ayuda de inteligencia artificial. Antes de la publicación, un autor ha revisado y corregido el contenido según ha estimado necesario. Consulta Los principios para usar contenido generado por IA en Microsoft Learn.