Condividi tramite

integrazione di .NET AspireNATS

  • Articolo

include:integrazione dell'hosting e Client integrazione

NATS è un sistema di messaggistica distribuito, sicuro e a prestazioni elevate. L'integrazione .NET AspireNATS consente di connettersi a istanze esistenti di NATS o di creare nuove istanze da .NET utilizzando l'immagine del container docker.io/library/nats.

Integrazione dell'hosting

NATS l'integrazione dell'hosting per .NET Aspire modella un NATSserver come tipo di NatsServerResource. Per accedere a questo tipo, installare il . Ospitare. pacchetto NuGet nel progetto host dell'app , quindi aggiungerlo con il generatore.

dotnet add package Aspire.Hosting.Nats

Per ulteriori informazioni, vedere dotnet add package o Gestire le dipendenze di pacchetti nelle applicazioni .NET.

Aggiungere la risorsa NATSserver

Nel progetto host dell'app, effettuare una chiamata a AddNats sull'istanza di builder per aggiungere una risorsa NATSserver.

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Quando .NET.NET Aspire aggiunge un'immagine contenitore all'host dell'app, come illustrato nell'esempio precedente con l'immagine docker.io/library/nats, crea una nuova istanza NATSserver nel computer locale. Al NATSviene aggiunto un riferimento alla servernats (la variabile ExampleProject).

Il metodo WithReference configura una connessione nel ExampleProject denominato "nats". Per ulteriori informazioni, vedere ciclo di vita delle risorse di contenitori.

Suggerimento

Se preferisci connetterti a un NATSserveresistente, chiama AddConnectionString. Per altre informazioni, vedere Fare riferimento alle risorse esistenti.

Aggiungere NATSserver risorsa con JetStream

Per aggiungere il JetStream alla risorsa di , chiamare il metodo :

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 funzionalità NATS JetStream fornisce un motore di persistenza predefinito denominato JetStream che consente l'archiviazione e la riproduzione dei messaggi in un secondo momento. Facoltativamente, è possibile fornire un parametro srcMountPath per indicare il percorso della directory dei dati JetStream sulla macchina host (il percorso di montaggio fornito è associato all'argomento -sd del contenitore).

Aggiungere NATSserver risorsa con volume di dati

Per aggiungere un volume di dati alla risorsa NATSserver, chiamare il metodo WithDataVolume nella risorsa 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...

Il volume di dati viene usato per rendere persistenti i dati NATSserver al di fuori del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso di /var/lib/nats nel contenitore NATSserver. Un nome viene generato in modo casuale, a meno che non si fornisca il parametro name. Per altre informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto a associare i montaggi, vedere la documentazione Docker: Volumi.

Aggiungere la risorsa NATSserver con bind mount dei dati

Per aggiungere un data bind mount alla risorsa NATSserver, chiamare il metodo 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...

Importante

I di binding dei dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendole più adatte per gli ambienti di produzione. Tuttavia, i montaggi di associazione consentono l'accesso diretto e la modifica diretta dei file nel sistema host, ideale per lo sviluppo e il test in cui sono necessarie modifiche in tempo reale.

I montaggi di associazione dati si basano sul file system del computer host per mantenere persistenti i dati NATSserver tra i riavvii del contenitore. Il montaggio dell'associazione dati è montato al percorso C:\NATS\Data su Windows (o /NATS/Data su Unix) sulla macchina host nel contenitore NATSserver. Per ulteriori informazioni sui montaggi bind dei dati, consultare la documentazione Docker: Bind mounts.

Verifiche di integrità dell'integrazione di hosting

L'integrazione dell'hosting NATS aggiunge automaticamente un controllo dello stato di salute per la risorsa NATSserver. La verifica dello stato di salute verifica che il NATSserver sia in esecuzione e che sia possibile stabilire una connessione.

L'integrazione dell'hosting si basa sul pacchetto 📦 AspNetCore.HealthChecks.Nats Pacchetto NuGet.

integrazione Client

Per iniziare a usare l'integrazione di .NET AspireNATSclient, installare il 📦Aspire.NATSpacchetto NuGet .Net nel progetto client-consume, ovvero il progetto per l'applicazione che usa il NATSclient. L'integrazione NATSclient registra un'istanza di INatsConnection che è possibile usare per interagire con NATS.

dotnet add package Aspire.NATS.Net

Aggiungere NATSclient

Nel file Program.cs del tuo progetto clientdi consumo, chiama il metodo di estensione AddNatsClient su qualsiasi IHostApplicationBuilder per registrare un INatsConnection da usare tramite il contenitore di iniezione delle dipendenze. Il metodo accetta un parametro del nome di connessione.

builder.AddNatsClient(connectionName: "nats");

Suggerimento

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa NATSserver nel progetto host dell'app. Per altre informazioni, vedere Aggiungere NATSserver risorsa.

È quindi possibile recuperare l'istanza di INatsConnection usando l'injectione delle dipendenze. Ad esempio, per recuperare il client da un servizio:

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

Per altre informazioni sull'iniezione delle dipendenze, vedere .NET iniezione delle dipendenze.

Aggiungi i codici NATSclient associati a una chiave

In alcuni casi potrebbe essere necessario registrare più istanze di INatsConnection con nomi di connessione diversi. Per registrare i client NATS con chiave, chiamare il metodo AddKeyedNatsClient:

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

È quindi possibile ottenere le istanze di IConnection usando la dependency injection. Ad esempio, per recuperare la connessione da un servizio di esempio:

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

Per altre informazioni sui servizi con chiave, vedere .NET inserimento delle dipendenze: Servizi con chiave.

Configurazione

L'integrazione .NET AspireNATS offre più opzioni per configurare la connessione NATS in base ai requisiti e alle convenzioni del progetto.

Usare una stringa di connessione

Specificare il nome della stringa di connessione quando si chiama builder.AddNatsClient:

builder.AddNatsClient(connectionName: "nats");

La stringa di connessione viene recuperata dalla sezione di configurazione ConnectionStrings:

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

Per altre informazioni su come formattare questa stringa di connessione, vedere la documentazione ConnectionString.

Utilizzare i fornitori di configurazione

L'integrazione .NET AspireNATS supporta Microsoft.Extensions.Configuration. Carica il NatsClientSettings dalla configurazione usando la chiave di Aspire:Nats:Client. Il frammento di codice seguente è un esempio di un file appsettings.json che configura alcune delle opzioni:

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

Per il completo schema di integrazione NATSclientJSON, consultare Aspire.NATS.Net/ConfigurationSchema.json.

Usare delegati inline

Passare il delegato Action<NatsClientSettings> configureSettings per configurare alcune o tutte le opzioni in linea, ad esempio per disabilitare i controlli di integrità direttamente nel codice.

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

NATS nel manifesto .NET Aspire

NATS non fa parte del manifesto di distribuzione .NET Aspire. È consigliabile configurare un NATSserver di produzione sicuro al di fuori di .NET Aspire.

Client controlli di integrità dell'integrazione

Per impostazione predefinita, le integrazioni di .NET.NET Aspire abilitano controlli di salute per tutti i servizi. Per altre informazioni, vedere panoramica delle integrazioni .NET.NET Aspire.

L'integrazione .NET AspireNATS gestisce le operazioni seguenti:

  • Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere passati affinché l'app sia considerata pronta per accettare il traffico.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni impostano automaticamente la registrazione, il tracciamento e le configurazioni delle metriche, talvolta note come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione .NET AspireNATS usa le categorie di log seguenti:

  • NATS

Tracciamento

L'integrazione .NET AspireNATS emette le seguenti attività di tracciamento:

  • NATS.Net

Vedere anche