.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 Hosting-Integration modelliert einen RabbitMQ-Server als RabbitMQServerResource-Typ. Um auf diesen Typ und seine APIs zuzugreifen, fügen Sie das NuGet-Paket 📦Aspire.Hosting.RabbitMQ im -App-Host--Projekt hinzu.

dotnet add package Aspire.Hosting.RabbitMQ

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

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

Hinzufügen der Serverressource RabbitMQ

Rufen Sie in Ihrem App-Hostprojekt AddRabbitMQ in der builder Instanz auf, um eine RabbitMQ Serverressource 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 RabbitMQ Serverinstanz auf dem lokalen Computer erstellt. Ein Verweis auf Ihren RabbitMQ Server (die rabbitmq Variable) wird zur ExampleProject hinzugefügt. Die Serverressource RabbitMQ enthält Standard-Anmeldeinformationen mit einem username von "guest" und zufällig generiertem password mithilfe der CreateDefaultPasswordParameter-Methode.

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

Hinzufügen der RabbitMQ-Serverressource mit Verwaltungs-Plugin

Um das RabbitMQ Verwaltungs-Plugin zur RabbitMQ-Serverressource 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-Verwaltungs-Plug-In stellt eine HTTP-basierte API für die Verwaltung und Überwachung Ihres RabbitMQ Servers bereit. .NET .NET Aspire fügt dem App-Host, der das Management-Plugin ausführt, ein weiteres Containerimage docker.io/library/rabbitmq-management hinzu.

Hinzufügen RabbitMQ Serverressource mit Datenvolume

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

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 RabbitMQ Serverdaten außerhalb des Lebenszyklus des Containers zu speichern. Das Datenvolume wird am /var/lib/rabbitmq Pfad im RabbitMQ Servercontainer 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-Mounts bevorzugt werden, finden Sie in der Docker-Dokumentation: Volumes.

Hinzufügen der Serverressource RabbitMQ mit Datenbindemontage

Rufen Sie die RabbitMQ-Methode auf, um der WithDataBindMount Server-Ressource ein Datenbindungs-Mount 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...

Datenbind-Mounts basieren auf dem Dateisystem des Hostcomputers, um die RabbitMQ-Serverdaten bei Containerneustarts beizubehalten. Der Datenbindungs-Mount wird auf dem C:\RabbitMQ\Data unter Windows (oder /RabbitMQ/Data auf Unix) Pfad auf dem Hostcomputer im RabbitMQ-Servercontainer eingehängt. Weitere Informationen zu Bind-Mounts von Daten finden Sie in den Docker-Dokumentationen: Bind-Mounts.

Fügen Sie RabbitMQ Server-Ressource mit Parametern hinzu

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 Hosting-Integration fügt automatisch eine Gesundheitsprüfung für die RabbitMQ Server-Ressource hinzu. Der Gesundheitscheck überprüft, ob der RabbitMQ-Server läuft und ob eine Verbindung zu ihm hergestellt werden kann.

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

ClientIntegration

Um mit der .NET AspireRabbitMQ-Clientintegration zu beginnen, installieren Sie das 📦Aspire.RabbitMQ.Client-NuGet-Paket im Client-Projekt, d. h. dem Projekt für die Anwendung, die den RabbitMQ-Client verwendet. Die RabbitMQ Clientintegration registriert eine IConnection Instanz, die Sie für die Interaktion mit RabbitMQverwenden können.

dotnet add package Aspire.RabbitMQ.Client

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

Füge RabbitMQ-Client hinzu

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

builder.AddRabbitMQClient(connectionName: "messaging");

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.

Hinzufügen des Clients mit Schlüssel RabbitMQ

Es kann Situationen geben, in denen Sie mehrere IConnection-Instanzen mit unterschiedlichen Verbindungsnamen registrieren möchten. Rufen Sie die Methode AddKeyedRabbitMQClient auf, um angegebene 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 die Verbindung von einem Beispieldienst abzurufen, gehen Sie wie folgt vor:

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. Mithilfe des Schlüssels Aspire:RabbitMQ:Client lädt es die RabbitMQClientSettings aus der Konfiguration. 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
      }
    }
  }
}

Das vollständige RabbitMQ Clientintegration JSON Schema 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 durch 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 vom Client bereitgestellten Namen für Verbindungen 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 AspireRabbitMQ-Integration:

• Fügt die Integritätsprüfung hinzu, wenn RabbitMQClientSettings.DisableHealthChecksfalse ist. Es wird versucht, eine Verbindung mit dem RabbitMQ-Server herzustellen und einen Kanal zu 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

Nachverfolgung

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