Bilans de santé dans ASP.NET Core

Découvrez comment configurer et développer des contrôles de l'intégrité dans ASP.NET Core pour confirmer l'intégrité de votre application.

Les vérifications de l'intégrité sont un nouveau middleware disponible dans ASP.NET Core 2.2. Il fournit un moyen d'exposer la santé de votre application via un point de terminaison HTTP.

La santé de votre application peut vouloir dire beaucoup de choses. C'est à vous de configurer ce qui est considéré comme sain ou malsain.

Votre application dépend peut-être de la possibilité de se connecter à une base de données. Si votre application ne parvient pas à se connecter à la base de données, le noeud final de vérification de l'état répondrait comme étant malsain.

D'autres scénarios pourraient inclure la confirmation que l'environnement hébergeant l'application est en bon état. Par exemple, utilisation de la mémoire, espace disque, etc.
Si vous avez utilisé un équilibreur de charge, vous avez probablement déjà utilisé au moins une vérification de base de l'état de santé. De même, si vous avez utilisé docker, vous connaissez peut-être son code HEALTHCHECK.

Dans un scénario d'équilibrage de charge, cela signifie que l'équilibreur de charge envoie périodiquement une demande HTTP à votre point de terminaison de vérification d'intégrité. S'il reçoit un statut HTTP 200 OK il ajoute l'application au pool d'équilibreur de charge et le trafic HTTP en direct est acheminé vers cette instance.

S'il répond avec un statut défaillant (généralement tout autre élément que HTTP 200 OK ), il ne l'ajoute ni ne le supprime du pool d'équilibreur de charge.

Principes de base

Pour créer des vérifications de l'intégrité dans votre application, vous devez modifier le fichier Startup.cs fichier en ajoutant les contrôles de santé aux méthodes ConfigureServices et Configure de façon appropriée.

 à l'aide de Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

espace de noms AspNetCore.HealthCheck.Demo
{
  classe publique Startup
  {
    démarrage public (configuration IConfiguration)
    {
      Configuration = configuration;
    }

    public IConfiguration Configuration {get; }

    public Void ConfigureServices (services IServiceCollection)
    {
      services.AddHealthChecks ();
      services.AddDbContext  ();
      services.AddMvc (). SetCompatibilityVersion (CompatibilityVersion.Version_2_2);
    }


    public void Configure (application IApplicationBuilder, env. IHostingEnvironment)
    {
      app.UseHealthChecks ("/ santé");
      app.UseStaticFiles ();
      app.UseMvc ();
    }
  }
} 

Lorsque vous accédez à la route / health vous recevez un HTTP 200 OK avec le corps du contenu de Healthy .

. Check

Un bilan de santé courant pourrait consister à vérifier que nous pouvons nous connecter à notre base de données. Dans cet exemple, j'ai un Entity Framework Core DbContext appelé MyDbContext enregistré sous ConfigureServices () .

. Pour pouvoir tester notre connexion à la base de données , nous pouvons créer un bilan de santé personnalisé. Pour ce faire, nous devons mettre en œuvre IHealthCheck . Le CheckhealthAsync nous oblige à renvoyer un HealthCheckStatus . Si nous pouvons nous connecter à la base de données, nous retournerons En bonne santé ; sinon, nous retournerons Unhealthy .

Vous remarquerez également que nous utilisons l’injection de dépendance par le constructeur. Tout ce qui est enregistré dans ConfigureServices () peut être injecté dans le constructeur de notre état de santé.

 à l'aide de System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Diagnostics.HealthChecks;

espace de noms AspNetCore.HealthCheck.Demo
{
  Classe publique DbContextHealthCheck: IHealthCheck
  {
    lecture seule privée MyDbContext _dbContext;


    public DbContextHealthCheck (MyDbContext dbContext)
    {
      _dbContext = dbContext;
    }

    public async Task  CheckHealthAsync (contexte HealthCheckContext,
      CancellationToken annulationToken = nouveau CancellationToken ())
    {
      return wait _dbContext.Database.CanConnectAsync (cancelToken)
              ? HealthCheckResult.Healthy ()
              : HealthCheckResult.Unhealthy ();
    }
  }
} 

Maintenant, pour utiliser ajouter un nouveau bilan de santé, nous pouvons utiliser Addcheck () à AddHealthChecks () dans ConfigureServices () : [19659010] using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

espace de noms AspNetCore.HealthCheck.Demo
{
  classe publique Startup
  {
    démarrage public (configuration IConfiguration)
    {
      Configuration = configuration;
    }

    public IConfiguration Configuration {get; }

    public Void ConfigureServices (services IServiceCollection)
    {
      services.AddDbContext ();

      services.AddHealthChecks ()
              .AddCheck ("DbContextHealthCheck");

      services.AddMvc (). SetCompatibilityVersion (CompatibilityVersion.Version_2_2);
    }

    public void Configure (application IApplicationBuilder, env. IHostingEnvironment)
    {
      app.UseHealthChecks ("/ santé");
      app.UseStaticFiles ();
      app.UseMvc ();
    }
  }
}

Vérification du Core EF intégré

Heureusement, nous n'avons pas besoin de créer une vérification du Core DbContext EF, car Microsoft l'a déjà fait dans le Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore . ] Forfait NuGet. Nous pouvons simplement utiliser ce paquet, puis modifier notre chèque comme suit:

 services.AddHealthChecks ()
        .AddDbContextCheck  ("DbContextHealthCheck"); 

Packages de communauté

Il existe de nombreux packages de contrôle de la santé sur NuGet pour SQL Server, MySQL, MongoDB, Redis, RabbitMQ, Elasticsearch, Azastics Storage, Amazon S3 et beaucoup plus.

Vous trouverez tous ces éléments dans le référentiel AspNetCore.Diagnostics.HealthChecks sur GitHub qui fait référence à chaque paquet NuGet.

Voici quelques exemples de la facilité avec laquelle ils peuvent être ajoutés à votre Startup ConfigureServices () :

AspNetCore.HealthChecks.SqlServer

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

AspNetCore.HealthChecks.Redis

 public void ConfigureServices (services IServiceCollection)
{
  services.AddHealthChecks ()
          .AddRedis (Configuration ["Data:ConnectionStrings:Redis"])
} 

Options

Il existe différentes options pour configurer le comportement du middleware de contrôle de l'intégrité.

Codes de statut

Dans notre propre DbContextHealthCheck nous avons renvoyé un . statut si notre application peut se connecter à notre base de données. Sinon, nous avons renvoyé un statut Unhealthy

. Le point final / health renvoie différents codes de statut HTTP en fonction de notre HealthStatus . En bonne santé, saine retournera un statut HTTP de 200 OK . Unwealthy retournera un 503 service indisponible . Nous pouvons modifier ce comportement par défaut en utilisant HealthCheckOptions pour créer nos mappages entre HealthStatus et StatusCodes .

 app.UseHealthChecks ("/ health", nouveau HealthCheckOptions
{
  ResultStatusCodes =
  {
    [HealthStatus.Healthy] = StatusCodes.Status200OK,
    [HealthStatus.Degraded] = StatusCodes.Status200OK,
    [HealthStatus.Unhealthy] = StatusCodes.Status503ServiceUnavailable,
  }
Il existe un troisième code de statut:  Degraded . Par défaut, cela renvoie également un statut  200 OK . 

 Réponse 
 Par défaut, le type de contenu   sera  text / plain  et le corps de la réponse sera  Sain  ou  Malsain . 
 Une autre option que vous pouvez configurer est le corps de réponse réel du noeud final. Vous pouvez contrôler la sortie en configurant le  ResponseWriter  dans le  HealthCheckOptions . 
 Au lieu de renvoyer un texte brut, je sérialiserai le  HealthReport  en JSON: [19659010] app.UseHealthChecks ("/ health", nouvelles options HealthCheckOptions
{
  ResponseWriter = async (contexte, rapport) =>
  {
    context.Response.ContentType = "application / json; charset = utf-8";
    var bytes = Encoding.UTF8.GetBytes (JsonConvert.SerializeObject (report));
    wait context.Response.Body.WriteAsync (octets);
  }

Ceci a pour résultat le retour de notre point final / health :

 Type de contenu: application / json; jeu de caractères = utf-8
Serveur: Kestrel
Cache-Control: no-store, no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Expire: jeu., 01 janvier 1970 00:00:00 GMT
{
  "Entrées": {
    "DbContextHealthCheck": {
      "Les données": {},
      "Description": null,
      "Durée": "00: 00: 00.0265244",
      "Exception": null,
      "Statut": 2
    }
  },
  "Statut": 2,
  "TotalDuration": "00: 00: 00.0302606"
} 

Délais d'expiration

Les délais d'expiration sont un élément à prendre en compte lors de la création de contrôles de santé. Par exemple, vous avez peut-être créé un bilan de santé en train de tester une connexion à une base de données ou vous utilisez HttpClient pour vérifier que vous pouvez établir une connexion HTTP externe.

Souvent, ces clients ( DbConnection ou HttpClient ) ont des délais d'expiration par défaut qui peuvent être assez élevés. HttpClient a une valeur par défaut de 100 secondes .

Si vous utilisez le point de terminaison du contrôle d'intégrité d'un équilibreur de charge pour déterminer l'intégrité de votre application, vous souhaitez le renvoyer. état de santé le plus rapidement possible. Si vous avez un problème de connexion Internet, vous ne voudrez peut-être pas attendre 100 secondes pour renvoyer un service 503 indisponible . Cela va empêcher votre équilibreur de charge de retirer votre application du pool.

Interface utilisateur Web

Il existe un autre excellent package, AspNetCore.HealthChecks.UI qui ajoute une interface utilisateur Web à votre application. Cela vous permet de visualiser les contrôles de santé que vous avez configurés et leur statut.

Une fois le package installé, vous devez appeler AddHealthChecksUI () à ConfigureServices () ainsi que appelez UseHealthChecksUI () de Configure () dans votre Startup .

Vous devez également configurer le ResponseWrite pour pouvoir utiliser le UIResponseWriter.WriteHealthCheckUIResponse . Cela correspond essentiellement à ce que nous avons décrit ci-dessus en sérialisant le HealthReport en JSON. HealthCheck-UI a besoin de cela pour pouvoir obtenir des informations détaillées sur vos contrôles de santé configurés.

 public class Startup
{
  démarrage public (configuration IConfiguration)
  {
    Configuration = configuration;
  }

  public IConfiguration Configuration {get; }

  public Void ConfigureServices (services IServiceCollection)
  {
    services.AddDbContext  ();


    services.AddHealthChecks ()
            .AddCheck  ("DbContextHealthCheck");
    
    services.AddHealthChecksUI ();
    
    services.AddMvc (). SetCompatibilityVersion (CompatibilityVersion.Version_2_2);
  }

  public void Configure (application IApplicationBuilder, env. IHostingEnvironment)
  {
    app.UseHealthChecks ("/ health", nouvelles options HealthCheckOptions ()
    {
      Prédicat = _ => vrai,
      ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
    });
    
    app.UseHealthChecksUI ();
    
    app.UseStaticFiles ();
    app.UseMvc ();
  }
} 

Ceci ajoutera une nouvelle route à votre application à l'adresse / healthchecks-ui .

Vous devez également ajouter une configuration à appsettings.json (ou à toute configuration de votre choix).

Ceci indique à l'interface de HealthChecks où interroger pour obtenir des informations détaillées sur l'état de santé. De ce fait, vous pouvez ajouter autant d'URL différentes pour diverses autres applications ASP.NET Core qui renvoient des données de contrôle d'intégrité.

Pour notre exemple, nous allons simplement ajouter notre point de terminaison local exécuté sous / health :

 "HealthChecks-UI": {
  "HealthChecks": [
    {
      "Name": "Local",
      "Uri": "http://localhost:5000/health"
    }
  ],
  "EvaluationTimeOnSeconds": 10,
  "MinimumSecondsBetweenFailureNotifications": 60
} 

Lorsque vous accédez à / healtchecks-ui l'interface utilisateur s'affiche avec une liste de nos contrôles de santé:

Résumé

Le middleware de vérification de l'état de santé est une excellente addition à ASP.NET Core. Il est configurable et très facile d'ajouter vos propres vérifications de l'état de santé. La communauté publie déjà de nombreux packages pour différents services externes. et je ne peux que supposer que leur nombre augmentera à l'avenir.

Pour en savoir plus sur le développement avec ASP.NET Core

Pour en savoir plus sur la création d'excellentes interfaces utilisateur avec ASP.NET Core? Découvrez Interface utilisateur Telerik pour ASP.NET Core avec tout, des grilles et graphiques aux planificateurs et aux sélecteurs.