.NET Aspire RabbitMQ-Integration

umfasst:Hostingintegration und Client Integration

RabbitMQ ist ein zuverlässiger Messaging- und Streamingbroker, der einfach in Cloudumgebungen, lokal und auf Ihrem lokalen Computer bereitgestellt werden kann. Mit der .NET AspireRabbitMQ-Integration können Sie eine Verbindung mit vorhandenen RabbitMQ-Instanzen herstellen oder neue Instanzen aus .NET mit dem docker.io/library/rabbitmq Container-Imageerstellen.

Hosting-Integration

Die RabbitMQ-Hostintegration modelliert ein RabbitMQserver als Typ RabbitMQServerResource. Um auf diesen Typ und seine APIs zuzugreifen, fügen Sie das NuGet-Paket 📦Aspire.Hosting.RabbitMQ im -App-Host--Projekt hinzu.

.NET CLI

dotnet add package Aspire.Hosting.RabbitMQ

PackageReference

<PackageReference Include="Aspire.Hosting.RabbitMQ"
                  Version="*" />

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

Ressource RabbitMQserver hinzufügen

Rufen Sie AddRabbitMQ auf der builder Instanz in Ihrem App-Host-Projekt auf, um eine RabbitMQserver Ressource hinzuzufügen:

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging");

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

// 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/rabbitmq-Image gezeigt, wird eine neue RabbitMQserver Instanz auf dem lokalen Computer erstellt. Ein Verweis auf Ihre RabbitMQserver (die rabbitmq Variable) wird dem ExampleProjecthinzugefügt. Die RabbitMQserver-Ressource enthält Standardanmeldeinformationen mit einem username von "guest" und zufällig generierten password mithilfe der CreateDefaultPasswordParameter-Methode.

Die WithReference-Methode konfiguriert eine Verbindung im ExampleProject namens "messaging". Weitere Informationen finden Sie im Abschnitt Containerressourcenlebenszyklus.

Trinkgeld

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

Hinzufügen der RabbitMQserver Ressourcen mit dem Verwaltungs-Plugin

Um das RabbitMQ Verwaltungs-Plugin zur RabbitMQserver-Ressource hinzuzufügen, rufen Sie die WithManagementPlugin Methode auf.

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging")
                      .WithManagementPlugin();

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

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

Das RabbitMQ-Verwaltungsplugin stellt eine HTTP-basierte API für die Verwaltung und Überwachung Ihrer RabbitMQserverbereit. .NET .NET Aspire fügt dem App-Host, der das Management-Plugin ausführt, ein weiteres Containerimage docker.io/library/rabbitmq-management hinzu.

Fügen Sie RabbitMQserver eine Ressource mit Datenvolumen hinzu

Rufen Sie die WithDataVolume-Methode für die RabbitMQserver-Ressource auf, um der RabbitMQserver Ressource ein Datenvolume hinzuzufügen:

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging")
                      .WithDataVolume(isReadOnly: false);

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

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

Das Datenvolume wird verwendet, um die RabbitMQserver Daten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolume wird im /var/lib/rabbitmq-Pfad im Container RabbitMQserver bereitgestellt und wenn kein name-Parameter angegeben wird, wird der Name zufällig generiert. Weitere Informationen zu Datenvolumes und Details dazu, warum sie gegenüber Bind-Mountsbevorzugt werden, finden Sie unter Docker-Dokumentation: Volumes.

Hinzufügen RabbitMQserver Ressource mit Datenbindungs-Bereitstellung

Rufen Sie die WithDataBindMount-Methode auf, um der RabbitMQserver-Ressource eine Datenbindungs-Bereitstellung hinzuzufügen:

var builder = DistributedApplication.CreateBuilder(args);

var rabbitmq = builder.AddRabbitMQ("messaging")
                      .WithDataBindMount(
                          source: @"C:\RabbitMQ\Data",
                          isReadOnly: false);

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

// 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 Änderung von Dateien auf dem Hostsystem, ideal für die Entwicklung und Tests, bei denen Echtzeitänderungen notwendig sind.

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

Hinzufügen der Ressourcen RabbitMQundserver mit Parametern

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

var builder = DistributedApplication.CreateBuilder(args);

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

var rabbitmq = builder.AddRabbitMQ("messaging", username, password);

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

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

Weitere Informationen zum Bereitstellen von Parametern finden Sie unter externe Parameter.

Hosten von Integritätsprüfungen für Integration

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

Die Hosting-Integration basiert auf dem 📦 AspNetCore.HealthChecks.Rabbitmq NuGet-Paket.

Client-Integration

Um mit der .NET AspireRabbitMQclient-Integration zu beginnen, installieren Sie das 📦Aspire.RabbitMQ.Client NuGet-Paket im Projekt, das clientverwendet, d.h. das Projekt für die Anwendung, die das RabbitMQclientverwendet. Die RabbitMQclient-Integration registriert eine IConnection-Instanz, die Sie für die Interaktion mit RabbitMQverwenden können.

.NET CLI

dotnet add package Aspire.RabbitMQ.Client

PackageReference

<PackageReference Include="Aspire.RabbitMQ.Client"
                  Version="*" />

Hinzufügen von RabbitMQclient

Rufen Sie in der Program.cs-Datei Ihres client-verbrauchenden Projekts die AddRabbitMQClient-Erweiterungsmethode für ein beliebiges IHostApplicationBuilder auf, um eine IConnection zur Verwendung über den Dependency Injection Container zu registrieren. Die Methode verwendet einen Verbindungsnamenparameter.

builder.AddRabbitMQClient(connectionName: "messaging");

Tipp

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

Anschließend können Sie die IConnection Instanz mithilfe der Abhängigkeitseinfügung abrufen. Um die Verbindung von einem Beispieldienst abzurufen, gehen Sie wie folgt vor:

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

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

Schlüsselwort RabbitMQclient hinzufügen

Es kann Situationen geben, in denen Sie mehrere IConnection-Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Rufen Sie die AddKeyedRabbitMQClient-Methode auf, um Schlüssel RabbitMQ-Clients zu registrieren.

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

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

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

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

Konfiguration

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

Verwenden Sie eine Verbindungszeichenfolge

Wenn Sie eine Verbindungszeichenfolge aus dem Konfigurationsabschnitt ConnectionStrings verwenden, können Sie beim Aufrufen der AddRabbitMQClient-Methode den Namen der Verbindungszeichenfolge angeben:

builder.AddRabbitMQClient(connectionName: "messaging");

Aus dem Konfigurationsabschnitt ConnectionStrings wird anschließend die Verbindungszeichenfolge abgerufen.

{
  "ConnectionStrings": {
    "messaging": "amqp://username:password@localhost:5672"
  }
}

Weitere Informationen zum Formatieren dieser Verbindungszeichenfolge finden Sie in den RabbitMQ URI-Spezifikationsdokumenten.

Verwendung von Konfigurationsanbietern

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

{
  "Aspire": {
    "RabbitMQ": {
      "Client": {
        "ConnectionString": "amqp://username:password@localhost:5672",
        "DisableHealthChecks": true,
        "DisableTracing": true,
        "MaxConnectRetryCount": 2
      }
    }
  }
}

Die vollständige RabbitMQclient Integration JSON Schemas finden Sie unter Aspire.RabbitMQ.Client/ConfigurationSchema.json.

Verwenden von Inlinedelegatn

Sie können auch den Action<RabbitMQClientSettings> configureSettings-Delegaten verwenden, um einige oder alle Optionen inline einzurichten, z. B. um Gesundheitsprüfungen im Code zu deaktivieren.

builder.AddRabbitMQClient(
    "messaging",
    static settings => settings.DisableHealthChecks = true);

Sie können auch die IConnectionFactory- mithilfe des Action<IConnectionFactory> configureConnectionFactory Delegatparameters der AddRabbitMQClient-Methode einrichten. So legen Sie z. B. den für Verbindungen angegebenen Namen client fest:

builder.AddRabbitMQClient(
    "messaging",
    configureConnectionFactory:
        static factory => factory.ClientProvidedName = "MyApp");

Client Integrationsgesundheitsprüfungen

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

Die .NET Aspire- undRabbitMQ-Integration:

• Fügt die Integritätsprüfung hinzu, wenn RabbitMQClientSettings.DisableHealthChecksfalseist, die versucht, eine Verbindung herzustellen und einen Kanal auf der RabbitMQserverzu erstellen.
• Integriert sich in den /health HTTP-Endpunkt, der spezifiziert, dass alle registrierten Gesundheitsprüfungen erfolgreich sein müssen, damit die App bereit ist, Datenverkehr anzunehmen.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Ablaufverfolgungs- und Metrikkonfigurationen ein, die manchmal als die Säulen der Beobachtbarkeitbezeichnet werden. Weitere Informationen zur Integrationsbeobachtbarkeit und Telemetrie finden Sie unter .NET.NET Aspire Integrationsübersicht. Abhängig vom unterstützenden Dienst unterstützen manche Integrationen möglicherweise nur einige dieser Funktionen. Beispielsweise unterstützen einige Integrationen Protokollierung und Ablaufverfolgung, aber keine Metriken. Telemetrie-Features können auch mithilfe der Techniken deaktiviert werden, die im Abschnitt Konfiguration dargestellt werden.

Protokollierung

Die .NET AspireRabbitMQ-Integration verwendet die folgenden Protokollkategorien:

• RabbitMQ.Client

Verfolgung

Die Integration .NET AspireRabbitMQ gibt mithilfe von OpenTelemetrydie folgenden Ablaufverfolgungsaktivitäten aus:

• Aspire.RabbitMQ.Client

Kennzahlen

Die .NET AspireRabbitMQ-Integration unterstützt derzeit standardmäßig keine Metriken.

Siehe auch

• Nachrichten senden mit RabbitMQ in .NET Aspire
• RabbitMQ .NET Client Dokumente
• .NET .NET Aspire Integrationen
• .NET Aspire GitHub Repository-