Freigeben über

.NET Aspire NATS-Integration

  • Artikel

umfasst: Hostingintegration und Client Integration

NATS ist ein leistungsstarkes, sicheres, verteiltes Messaging-System. Mit der .NET AspireNATS-Integration können Sie eine Verbindung mit vorhandenen NATS-Instanzen aufbauen oder neue Instanzen aus .NET mit dem docker.io/library/nats Container-Imageerstellen.

Hosting-Integration

Die NATS-Hostingintegration modelliert für .NET Aspire Modelle einen NATS-Server als NatsServerResource-Typ. Um auf diesen Typ zuzugreifen, installieren Sie das 📦Aspire.Hosting.Nats NuGet-Paket im App-Host Projekt und fügen Sie es dann mit dem Builder hinzu.

dotnet add package Aspire.Hosting.Nats

Weitere Informationen finden Sie unter dotnet add package oder unter Paketabhängigkeiten in .NET-Anwendungen verwalten.

NATS-Serverressource hinzufügen

Rufen Sie in Ihrem App-Hostprojekt AddNats in der builder Instanz auf, um eine NATS Serverressource hinzuzufügen:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Wenn .NET.NET Aspire dem App-Host ein Containerimage hinzufügt, wie im vorherigen Beispiel mit dem docker.io/library/nats-Image gezeigt, wird eine neue NATS Serverinstanz auf dem lokalen Computer erstellt. Ein Verweis auf Ihren NATS-Server (die nats-Variable) wird zu ExampleProject hinzugefügt.

Die WithReference-Methode konfiguriert eine Verbindung im ExampleProject namens "nats". Weitere Informationen finden Sie unter Container-Ressourcenlebenszyklus.

Trinkgeld

Wenn Sie lieber eine Verbindung mit einem vorhandenen NATS Server herstellen möchten, rufen Sie stattdessen AddConnectionString auf. Weitere Informationen finden Sie unter Referenzieren vorhandener Ressourcen.

Fügen Sie die Serverressource "NATS" mit JetStream hinzu.

Um die NATS JetStream- zur NATS Serverressource hinzuzufügen, rufen Sie die WithJetStream-Methode auf:

var builder = DistributedApplication.CreateBuilder(args);

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

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

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

Die NATS JetStream-Funktionalität bietet ein integriertes Persistenzmodul namens JetStream, mit dem Nachrichten zu einem späteren Zeitpunkt gespeichert und wiedergegeben werden können.

Hinzufügen NATS Serverressource mit Authentifizierungsparametern

Wenn Sie den Benutzernamen und das Kennwort explizit angeben möchten, können Sie diese als Parameter angeben. Betrachten Sie das folgende alternative Beispiel:

var builder = DistributedApplication.CreateBuilder(args);

var username = builder.AddParameter("username");
var password = builder.AddParameter("password", secret: true);

var nats = builder.AddNats(
    name: "nats",
    userName: username,
    password: password);

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


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

Weitere Informationen finden Sie unter Externe Parameter.

Hinzufügen NATS Serverressource mit Datenvolume

Um der NATS Serverressource ein Datenvolume hinzuzufügen, rufen Sie die WithDataVolume Methode für die NATS Serverressource auf:

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...

Das Datenvolume wird verwendet, um die NATS Serverdaten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolumen wird am /var/lib/nats Pfad im NATS-Servercontainer gemountet. Ein Name wird zufällig generiert, es sei denn, Sie geben einen Wert für den name-Parameter an. Weitere Informationen zu Datenvolumes und Details dazu, warum sie gegenüber Bind-Mountsbevorzugt werden, finden Sie in der Docker-Dokumentation: Volumes.

Hinzufügen der Server-Ressource NATS mit Daten-Bindemontage

Rufen Sie die NATS-Methode auf, um der WithDataBindMount Server-Ressource ein Datenbindungs-Mount hinzuzufügen.

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...

Wichtig

Daten-Bindemounts haben eine eingeschränkte Funktionalität im Vergleich zu den Volumes, die eine bessere Leistung, Portabilität und Sicherheit bieten und damit besser für Produktionsumgebungen geeignet sind. Bind-Mounts ermöglichen jedoch den direkten Zugriff und die Bearbeitung von Dateien auf dem Hostsystem, ideal für die Entwicklung und Tests, bei denen Echtzeitänderungen erforderlich sind.

Datenbind-Mounts basieren auf dem Dateisystem des Host-Rechners, um die NATS-Serverdaten über Neustarts von Containern hinweg zu persistieren. Der Datenbindungs-Mount wird auf dem C:\NATS\Data unter Windows (oder /NATS/Data auf Unix) Pfad auf dem Hostcomputer im NATS-Servercontainer eingehängt. Weitere Informationen zu Daten-Bind-Mounts finden Sie in der Docker Dokumentation: Bind-Mounts.

Durchführung von Integrationsgesundheitsprüfungen

Die NATS Hostingintegration fügt automatisch eine Integritätsprüfung für die NATS Serverressource hinzu. Die Gesundheitsprüfung überprüft, ob der NATS Server läuft und ob eine Verbindung zu ihm hergestellt werden kann.

Die Hostingintegration basiert auf dem 📦 AspNetCore.HealthChecks.Nats NuGet-Paket.

Client Integration

Um mit der .NET AspireNATS Clientintegration zu beginnen, installieren Sie das 📦Aspire.NATS.Net NuGet-Paket in dem Projekt, das den NATS Client nutzt, also dem Projekt der Anwendung, die den Client verwendet. Die NATS Clientintegration registriert eine INatsConnection Instanz, die Sie für die Interaktion mit NATSverwenden können.

dotnet add package Aspire.NATS.Net

Hinzufügen des NATS-Clients

Rufen Sie in der Program.cs Datei Ihres Client verwendenden Projekts die AddNatsClient Erweiterungsmethode an einem beliebigen IHostApplicationBuilder auf, um eine INatsConnection für die Verwendung über den Abhängigkeitsinjektionscontainer zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.

builder.AddNatsClient(connectionName: "nats");

Trinkgeld

Der parameter connectionName muss mit dem Namen übereinstimmen, der beim Hinzufügen der NATS Serverressource im App-Hostprojekt verwendet wird. Weitere Informationen finden Sie unter Hinzufügen NATS Serverressource.

Anschließend können Sie die INatsConnection Instanz mithilfe der Abhängigkeitsinjektion abrufen. Um den Client von einem Dienst abzurufen:

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

Weitere Informationen zur Abhängigkeitsinjektion finden Sie unter .NET Abhängigkeitsinjektion.

Hinzufügen des Clients mit Schlüssel NATS

Es kann Situationen geben, in denen Sie mehrere INatsConnection Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Um Keyed-NATS-Clients zu registrieren, rufen Sie die AddKeyedNatsClient-Methode auf.

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

Anschließend können Sie die IConnection Instanzen mithilfe der Abhängigkeitseinfügung abrufen. Um beispielsweise die Verbindung von einem Beispieldienst abzurufen:

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

Weitere Informationen zu schlüsselbasierten Diensten finden Sie unter .NET Abhängigkeitsinjektion: schlüsselbasierte Dienste.

Konfiguration

Die .NET AspireNATS Integration bietet mehrere Optionen zum Konfigurieren der NATS Verbindung basierend auf den Anforderungen und Konventionen Ihres Projekts.

Verwenden Sie eine Verbindungszeichenfolge

Geben Sie den Namen der Verbindungszeichenfolge an, wenn Sie builder.AddNatsClientaufrufen:

builder.AddNatsClient(connectionName: "nats");

Die Verbindungszeichenfolge wird aus dem Konfigurationsabschnitt ConnectionStrings abgerufen.

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

Weitere Informationen zum Formatieren dieser Verbindungszeichenfolge finden Sie in der ConnectionString-Dokumentation.

Verwenden Sie Konfigurationsanbieter

Die .NET AspireNATS-Integration unterstützt Microsoft.Extensions.Configuration. Sie lädt die NatsClientSettings aus der Konfiguration mithilfe des Schlüssels Aspire:Nats:Client. Der folgende Codeausschnitt ist ein Beispiel für eine appsettings.json Datei, die einige der Optionen konfiguriert:

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

Die vollständige NATS Clientintegration JSON Schemas finden Sie unter Aspire.NATS.Net/ConfigurationSchema.json.

Verwenden von Inline-Delegaten

Übergeben Sie den Action<NatsClientSettings> configureSettings Delegaten, um einige oder alle Optionen inline einzurichten, z. B. zum Deaktivieren von Gesundheitsprüfungen im Code.

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

NATS im .NET Aspire Manifest

NATS ist nicht Teil des .NET AspireBereitstellungsmanifests. Es wird empfohlen, einen sicheren NATS-Produktionsserver außerhalb von .NET Aspireeinzurichten.

Client Integrationsgesundheitsprüfungen

Standardmäßig aktivieren .NET.NET Aspire Integrationen Gesundheitsprüfungen für alle Dienste. Weitere Informationen finden Sie unter .NET.NET Aspire Integrationsübersicht.

Die .NET AspireNATS Integration behandelt Folgendes:

  • Integriert sich in den /health HTTP-Endpunkt, wobei angegeben wird, dass alle registrierten Integritätsprüfungen bestehen müssen, damit die App als bereit gilt, um Datenverkehr anzunehmen.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Tracing- und Metrikkonfigurationen ein, die manchmal als den Säulen der Beobachtbarkeit bezeichnet werden. Weitere Informationen zur Integrationsüberwachung und Telemetrie finden Sie in der Übersicht zu Integrationen unter .NET.NET Aspire. Abhängig vom Sicherungsdienst unterstützen einige Integrationen möglicherweise nur einige dieser Features. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetrie-Funktionen können auch mithilfe der Techniken deaktiviert werden, die im Abschnitt Konfiguration dargestellt werden.

Protokollierung

Die .NET AspireNATS-Integration verwendet die folgenden Protokollkategorien:

  • NATS

Nachverfolgung

Die .NET AspireNATS Integration führt die folgenden Tracing-Aktivitäten aus:

  • NATS.Net

Siehe auch