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

NATS-Hosting-Integration für .NET Aspire-Modelle eines NATSserver 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.

Hinzufügen von NATSserver Ressourcen

Rufen Sie in Ihrem App-Host-Projekt AddNats in der builder-Instanz auf, um eine NATSserver Ressource 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 NATSserver Instanz auf dem lokalen Computer erstellt. Ein Verweis auf Ihre NATSserver (die nats Variable) wird dem ExampleProjecthinzugefü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 NATSserverherstellen möchten, rufen Sie stattdessen AddConnectionString auf. Weitere Informationen finden Sie unter Referenzieren vorhandener Ressourcen.

Die Ressource NATSserver mit JetStream hinzufügen

Rufen Sie die NATS-Methode auf, um den NATS zur Ressource serverWithJetStream 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. 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).

Füge NATSserver Ressource mit Datenvolumen hinzu

Rufen Sie die NATS-Methode für die serverWithDataVolume-Ressource auf, um der NATSserver Ressource ein Datenvolume hinzuzufügen:

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 Datenvolumen wird verwendet, um die NATSserver Daten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolume ist am Pfad /var/lib/nats im Container NATSserver eingebunden. 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 NATSserver Ressource mit Datenbindungs-Bereitstellung

Um eine Datenbindung zur Ressource NATSserver hinzuzufügen, rufen Sie die WithDataBindMount-Methode auf.

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.

Datenbindungs-Bereitstellungen basieren auf dem Dateisystem des Hostcomputers, um die NATSserver Daten über Containerneustarts hinweg beizubehalten. Die Datenbindemount wird auf dem Pfad C:\NATS\Data unter Windows (oder /NATS/Data auf Unix) auf dem Hostcomputer im Container NATSserver bereitgestellt. Weitere Informationen zu Datenbindemounts finden Sie in der Docker Dokumentation: Bindemounts.

Durchführung von Integrationsgesundheitsprüfungen

Die NATS-Hostingintegration fügt für die NATS-server-Ressource automatisch eine Integritätsprüfung hinzu. Die Integritätsprüfung überprüft, ob die NATSserver ausgeführt wird und ob eine Verbindung hergestellt werden kann.

Die Hostingintegration basiert auf den 📦 AspNetCore.HealthChecks- undNats NuGet-Paketen.

Client Integration

Um mit der .NET AspireNATSclient-Integration zu beginnen, installieren Sie das 📦Aspire.NATS.Net NuGet-Paket im verbrauchenden Projekt client, das heißt, dem Projekt für die Anwendung, die die NATSclientverwendet. Die NATSclient-Integration registriert eine INatsConnection-Instanz, die Sie zur Interaktion mit NATSverwenden können.

dotnet add package Aspire.NATS.Net

Hinzufügen von NATSclient

Rufen Sie in der Program.cs-Datei Ihres client-verbrauchenden Projekts die AddNatsClient-Erweiterungsmethode auf jedem 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 NATSserver Ressource im App-Hostprojekt verwendet wird. Weitere Informationen finden Sie unter Hinzufügen NATSserver Ressource.

Anschließend können Sie die INatsConnection Instanz mithilfe der Abhängigkeitsinjektion abrufen. Um zum Beispiel die 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 von keyed NATSclient

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 NATSclient Integration 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, eine sichere Produktion NATSserver 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