Partager via

intégration de .NET AspireNATS

  • Article

inclut :intégration d’hébergement et Client intégration

NATS est un système de messagerie distribué hautement performant et sécurisé. L’intégration .NET AspireNATS vous permet de vous connecter à des instances de NATS existantes ou de créer de nouvelles instances à partir de .NET avec l’image conteneur docker.io/library/nats.

Intégration de l’hébergement

NATS l'intégration d’hébergement pour les modèles .NET Aspire modélise un serveur NATS en tant que type NatsServerResource. Pour accéder à ce type, installez le package NuGet 📦Aspire.Hosting.Nats dans le projet de l'hôte de l'application , puis ajoutez-le avec le générateur.

dotnet add package Aspire.Hosting.Nats

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances de package dans les applications .NET.

Ajouter une ressource de serveur NATS

Dans votre projet hôte d’application, appelez AddNats sur l’instance de builder pour ajouter une ressource de serveur NATS :

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

// After adding all resources, run the app...

Lorsque .NET.NET Aspire ajoute une image conteneur à l’hôte de l’application, comme illustré dans l’exemple précédent avec l’image docker.io/library/nats, il crée une instance de serveur NATS sur votre ordinateur local. Une référence à votre serveur NATS (la variable nats) est ajoutée au ExampleProject.

La méthode WithReference configure une connexion dans le ExampleProject nommé "nats". Pour plus d'informations, consultez cycle de vie des ressources du conteneur.

Pourboire

Si vous préférez vous connecter à un serveur NATS existant, appelez AddConnectionString à la place. Pour plus d’informations, consultez Référencer les ressources existantes.

Ajouter NATS ressource de serveur avec JetStream

Pour ajouter le NATS JetStream à la ressource du serveur NATS, appelez la méthode WithJetStream :

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithJetStream();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

// After adding all resources, run the app...

La fonctionnalité NATS JetStream fournit un moteur de persistance intégré appelé JetStream, qui permet de stocker et de relire les messages ultérieurement. Vous pouvez éventuellement fournir un paramètre srcMountPath pour spécifier le chemin d’accès au répertoire de données JetStream sur l’ordinateur hôte (le chemin de montage fourni mappe à l’argument -sd du conteneur).

Ajouter NATS ressource de serveur avec un volume de données

Pour ajouter un volume de données à la ressource du serveur NATS, appelez la méthode WithDataVolume sur la ressource de serveur NATS :

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithDataVolume(isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

// After adding all resources, run the app...

Le volume de données est utilisé pour conserver les données du serveur NATS en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin d’accès /var/lib/nats dans le conteneur du serveur NATS. Un nom est généré au hasard, sauf si vous fournissez une valeur pour le paramètre name. Pour plus d’informations sur les volumes de données et sur la raison pour laquelle ils sont préférés par rapport aux points de montage de liaison , consultez la documentation Docker : Volumes.

Ajoutez la ressource serveur NATS avec un montage de liaison de fichiers.

Pour ajouter un montage de liaison de données à la ressource de serveur NATS, appelez la méthode WithDataBindMount :

var builder = DistributedApplication.CreateBuilder(args);

var nats = builder.AddNats("nats");
                  .WithDataBindMount(
                      source: @"C:\NATS\Data",
                      isReadOnly: false);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(nats);

// After adding all resources, run the app...

Important

Les montages de liaison de données ont des fonctionnalités limitées par rapport aux volumes , qui offrent de meilleures performances, une portabilité et une sécurité accrues, les rendant plus adaptés aux environnements de production. Toutefois, les montages de liaison autorisent l’accès direct et la modification des fichiers sur le système hôte, ce qui est idéal pour le développement et les tests lorsque des modifications en temps réel sont nécessaires.

Les montages de liaison de données s’appuient sur le système de fichiers de l’ordinateur hôte pour conserver les données du serveur NATS entre les redémarrages de conteneur. Le point de montage de liaison de données est monté au chemin d'accès C:\NATS\Data sur Windows (ou /NATS/Data sur Unix) sur la machine hôte, dans le conteneur du serveur NATS. Pour plus d’informations sur les montages de liaison de données, consultez Docker docs : Liaison de montages.

Vérifications d’intégrité de l’intégration d’hébergement

L’intégration d’hébergement NATS ajoute automatiquement un contrôle d’intégrité pour la ressource de serveur NATS. La vérification d’intégrité vérifie que le serveur NATS est en cours d’exécution et qu’une connexion peut être établie à celle-ci.

L’intégration de l’hébergement s’appuie sur le package NuGet 📦 AspNetCore.HealthChecks.Nats.

intégration de Client

Pour commencer à utiliser l’intégration du client .NET AspireNATS, installez le 📦Aspire.NATS.Net package NuGet dans le projet consommant le client, c’est-à-dire le projet pour l’application qui utilise le client NATS. L’intégration du client NATS inscrit une instance INatsConnection que vous pouvez utiliser pour interagir avec NATS.

dotnet add package Aspire.NATS.Net

Ajouter NATS client

Dans le fichier Program.cs de votre projet client-consommateur, appelez la méthode d’extension AddNatsClient sur un(e) IHostApplicationBuilder pour enregistrer un(e) INatsConnection à utiliser via le conteneur d’injection de dépendances. La méthode prend un paramètre de nom de connexion.

builder.AddNatsClient(connectionName: "nats");

Pourboire

Le paramètre connectionName doit correspondre au nom utilisé lors de l’ajout de la ressource de serveur NATS dans le projet hôte de l’application. Pour plus d’informations, consultez Ajouter NATS ressource serveur.

Vous pouvez ensuite récupérer l’instance INatsConnection à l’aide de l’injection de dépendances. Par exemple, pour récupérer le client à partir d’un service :

public class ExampleService(INatsConnection connection)
{
    // Use connection...
}

Pour plus d'informations sur l'injection de dépendances, consultez l'injection de dépendances .NET.

Ajouter un client NATS avec clé

Il peut arriver que vous souhaitiez inscrire plusieurs instances de INatsConnection avec différents noms de connexion. Pour inscrire les clients identifiés par NATS, appelez la méthode AddKeyedNatsClient.

builder.AddKeyedNatsClient(name: "chat");
builder.AddKeyedNatsClient(name: "queue");

Vous pouvez ensuite récupérer les instances IConnection à l’aide de l’injection de dépendances. Par exemple, pour récupérer la connexion à partir d’un exemple de service :

public class ExampleService(
    [FromKeyedServices("chat")] INatsConnection chatConnection,
    [FromKeyedServices("queue")] INatsConnection queueConnection)
{
    // Use connections...
}

Pour plus d’informations sur les services à clé, consultez l'injection de dépendances .NET : services à clé.

Configuration

L’intégration .NET AspireNATS fournit plusieurs options pour configurer la connexion NATS en fonction des exigences et des conventions de votre projet.

Utiliser une chaîne de connexion

Indiquez le nom de la chaîne de connexion lorsque vous appelez builder.AddNatsClient:

builder.AddNatsClient(connectionName: "nats");

La chaîne de connexion est récupérée à partir de la section de configuration ConnectionStrings :

{
  "ConnectionStrings": {
    "nats": "nats://nats:4222"
  }
}

Consultez la documentation ConnectionString pour plus d’informations sur la mise en forme de cette chaîne de connexion.

Utiliser des fournisseurs de configuration

L’intégration .NET AspireNATS prend en charge Microsoft.Extensions.Configuration. Il charge le NatsClientSettings à partir de la configuration par l'intermédiaire de la clé Aspire:Nats:Client. L’extrait de code suivant est un exemple de fichier appsettings.json qui configure certaines des options :

{
  "Aspire": {
    "Nats": {
      "Client": {
        "ConnectionString": "nats://nats:4222",
        "DisableHealthChecks": true,
        "DisableTracing": true
      }
    }
  }
}

Pour le schéma complet d'intégration du client NATSJSON, consultez Aspire.NATS.Net/ConfigurationSchema.json.

Utiliser des délégués inline

Transmettez le délégué Action<NatsClientSettings> configureSettings pour configurer certaines ou toutes les options inline, par exemple pour désactiver les vérifications d’intégrité à partir du code :

builder.AddNatsClient(
    "nats",
    static settings => settings.DisableHealthChecks  = true);

NATS dans le manifeste de .NET Aspire

NATS ne fait pas partie du manifeste de déploiement .NET Aspire. Il est recommandé de configurer un serveur de production sécurisé NATS en dehors de .NET Aspire.

Client contrôles de santé de l’intégration

Les intégrations .NET.NET Aspire permettent par défaut des contrôles de santé pour tous les services. Pour plus d’informations, consultez .NET.NET Aspire vue d’ensemble des intégrations.

L’intégration .NET AspireNATS gère les éléments suivants :

  • S’intègre au point de terminaison HTTP /health, qui spécifie que tous les contrôles de santé enregistrés doivent réussir pour que l’application soit considérée prête à accepter le trafic.

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent automatiquement les configurations de journalisation, de suivi et de métriques, parfois appelées les piliers de l’observabilité. Pour plus d’informations sur l’observabilité de l’intégration et la télémétrie, consultez .NET.NET Aspire vue d’ensemble des intégrations. Selon le service de stockage, certaines intégrations peuvent uniquement prendre en charge certaines de ces fonctionnalités. Par exemple, certaines intégrations prennent en charge la journalisation et le suivi, mais pas les métriques. Les fonctionnalités de télémétrie peuvent également être désactivées à l’aide des techniques présentées dans la section Configuration.

Exploitation forestière

L'intégration .NET AspireNATS utilise les catégories de journaux de logs suivantes :

  • NATS

Traçage

L’intégration .NET AspireNATS émet les activités de traçage suivantes :

  • NATS.Net

Voir aussi