integrazione di .NET AspireNATS
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 server NATS come tipo di NatsServerResource. Per accedere a questo tipo, installare il pacchetto NuGet 📦Aspire.Hosting.Nats nel progetto host dell'app , quindi aggiungerlo utilizzando il builder.
- .NET dell'interfaccia della riga di comando
- PackageReference
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 server NATS
Nel progetto host dell'applicazione, chiamare AddNats sull'istanza builder per aggiungere una risorsa server NATS.
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 del server NATS nel computer locale. Un riferimento al server di NATS (la variabile nats) viene aggiunto al 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 server NATS esistente, chiama AddConnectionString. Per altre informazioni, vedere Fare riferimento alle risorse esistenti.
Aggiungere NATS risorsa server con JetStream
Per aggiungere NATS JetStream alla risorsa server NATS, chiamare il metodo 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 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 NATS risorsa server con volume di dati
Per aggiungere un volume di dati alla risorsa server NATS, chiamare il metodo WithDataVolume nella risorsa server 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...
Il volume di dati viene usato per rendere persistenti i dati del server NATS al di fuori del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /var/lib/nats nel contenitore del server NATS. 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.
Aggiungi la risorsa server NATS con il bind mount dei dati
Per aggiungere un bind mount di dati alla risorsa server NATS, utilizzare 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 rendere persistenti i dati del server NATS tra i riavvii del contenitore. Il bind mount dei dati è montato sul percorso C:\NATS\Data su Windows (o /NATS/Data su Unix) sul computer host nel contenitore server NATS. 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 di integrità per la risorsa server NATS. Il controllo di integrità verifica che il server NATS sia in esecuzione e che sia possibile stabilire una connessione.
L'integrazione dell'hosting si basa sul pacchetto NuGet 📦 AspNetCore.HealthChecks.Nats.
integrazione Client
Per iniziare con l'integrazione client .NET AspireNATS, installare il pacchetto NuGet .Net 📦Aspire.NATS nel progetto cliente, ovvero il progetto per l'applicazione che utilizza il client NATS. L'integrazione client NATS registra un'istanza INatsConnection che è possibile usare per interagire con NATS.
- .NET dell'interfaccia della riga di comando
- PackageReference
dotnet add package Aspire.NATS.Net
Aggiungere NATS client
Nel file Program.cs del progetto che utilizza il client, chiama il metodo di estensione AddNatsClient su qualsiasi IHostApplicationBuilder per registrare un INatsConnection da usare tramite il contenitore per l'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 server NATS nel progetto host dell'app. Per altre informazioni, vedere Aggiungere NATS risorsa server.
È 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.
Aggiungere il client NATS con 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 lo schema completo di integrazione client NATSJSON, vedere 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 server di produzione sicuro NATS all'esterno 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
