Freigeben über

.NET Aspire NATS-Integration

  • Artikel

umfasst:Hosting-Integration 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. Zu ExampleProjectwird ein Verweis auf den NATS Server (die nats Variable) 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. Optionalerweise können Sie einen srcMountPath-Parameter angeben, um den Pfad zum JetStream-Datenverzeichnis auf dem Hostcomputer anzugeben (der bereitgestellte Bereitstellungspfad ist dem -sd-Argument des Containers zugeordnet).

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 WithDataBindMount-Methode auf, um der NATS 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 Binden von Bereitstellungen mit eingeschränkter Funktionalität im Vergleich zu Volumes, die eine bessere Leistung, Portabilität und Sicherheit bieten, wodurch sie für Produktionsumgebungen besser 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 Hostcomputers, um die NATS-Serverdaten über Containerneustarts hinweg zu erhalten. 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 Datenbindemounts finden Sie in der Docker Dokumentation: 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 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 clientnutzenden Projekts die AddNatsClient Erweiterungsmethode an einem beliebigen IHostApplicationBuilder auf, um eine INatsConnection für die Verwendung über den Abhängigkeitsinjektions-Container 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 mithilfe des Aspire:Nats:Client Schlüssels aus der Konfiguration. 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 Inlinedelegatn

Übergeben Sie den Action<NatsClientSettings> configureSettings Delegat, um einige oder alle Optionen inline einzurichten, z. B. zum Deaktivieren von Integritätsprüfungen aus Code:

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

NATS im Manifest .NET Aspire

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

Client Gesundheitsprüfungen der Integration

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

Die .NET AspireNATS Integration behandelt Folgendes:

  • Integriert in den /health HTTP-Endpunkt, der angibt, dass alle registrierten Integritätsprüfungen bestehen müssen, damit die App als bereit für die Annahme des Datenverkehrs gilt.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als den Säulen der Observabilitybezeichnet 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 Protokollierungsaktivitäten aus:

  • NATS.Net

Siehe auch