Freigeben über

.NET Aspire NATS-Integration

Enthält:Hosting-Integration inbegriffen Hosting-Integration —&— Client Integration inbegriffenClient Integration

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

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-Hostprojekt 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 Verwalten von Paketabhängigkeiten in .NET-Anwendungen.

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 in dem Containerressourcenlebenszyklus.

Trinkgeld

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

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

Rufen Sie die Methode aufNATS, um die NATS der WithJetStream Serverressource hinzuzufügen:

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 Datenvolumen und Details dazu, warum sie gegenüber Bind-Mounts bevorzugt werden, finden Sie unter 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

Bind-Mounts für Daten bieten eine im Vergleich zu Volumes eingeschränkte Funktionalität, da diese eine bessere Leistung, Portabilität und Sicherheit bieten, wodurch sie 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-Bindemounts finden Sie unter Docker Docs: Daten-Bindemounts.

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 im Projekt, das den Client konsumiert, das heißt, das Projekt für die Anwendung, die den NATS Client verwendet. Die NATS Clientintegration registriert eine INatsConnection-Instanz , mit NATSder Sie interagieren 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 einer 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ängigkeitseinfügung: Schlüsseldienste.

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

Das vollständige NATS Clientintegrationsschema JSON 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

.NET .NET Aspire Standardmäßig aktivieren Integrationen Integritätsprüfungen für alle Dienste. Weitere Informationen finden Sie in .NET.NET Aspire der Übersicht über Integrationen.

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-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als Säulen der Observability bezeichnet werden. Weitere Informationen zur Integrations-Observability und Telemetrie finden Sie in der Übersicht über Integrationen. 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. Telemetriefeatures können auch mithilfe der im Abschnitt "Konfiguration " dargestellten Techniken deaktiviert 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