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 intègre l'hébergement pour .NET Aspire en modélisant un NATSserver comme type de NatsServerResource. Pour accéder à ce type, installez le . Hébergement. package NuGet dans le projet 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 NATSserver

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

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 NATSserver sur votre ordinateur local. Une référence à votre NATSserver (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 à une NATSserverexistante, appelez AddConnectionString à la place. Pour plus d’informations, consultez Référencer les ressources existantes.

Ajouter NATSserver ressource avec JetStream

Pour ajouter le NATS JetStream à la ressource NATSserver, utilisez 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 la ressource NATSserver avec un volume de données

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

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 NATSserver en dehors du cycle de vie de son conteneur. Le volume de données est monté sur le chemin /var/lib/nats dans le conteneur NATSserver. 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.

Ajouter NATSserver ressource avec montage de liaison de données

Pour ajouter un montage de liaison de données à la ressource NATSserver, 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 la machine hôte pour conserver les données NATSserver entre les redémarrages des conteneurs. Le montage de liaison de données est monté sur le chemin C:\NATS\Data sur Windows (ou /NATS/Data sur Unix) de l'ordinateur hôte dans le conteneur NATSserver. 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 NATSserver. Le contrôle de santé vérifie que le NATSserver est en cours d’exécution et qu'une connexion peut y être établie.

L’intégration de l’hébergement s’appuie sur les 📦 AspNetCore.HealthChecks et le package NuGetNats.

intégration de Client

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

dotnet add package Aspire.NATS.Net

Ajouter NATSclient

Dans le fichier Program.cs de votre projet consommant client, appelez la méthode d’extension AddNatsClient sur n’importe quel IHostApplicationBuilder pour enregistrer un INatsConnection à utiliser via le conteneur d’injection de dépendance. 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 NATSserver dans le projet hôte de l’application. Pour plus d’informations, consultez Ajouter NATSserverressource .

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 des codes clés NATSclient

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 obtenir le schéma complet NATSclient d’intégration JSON, 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 une NATSserver de production sécurisée 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