.NET Aspire-Azure Service Bus-Integration

Artikel
12/12/2024

Cloud-native Apps erfordern häufig kommunikation mit Messagingdiensten wie Azure Service Bus. Messagingdienste helfen dabei, Anwendungen zu entkoppeln und Szenarien zu ermöglichen, die auf Features wie Warteschlangen, Themen und Abonnements, atomare Transaktionen, Lastenausgleich und mehr basieren. Die .NET Aspire Service Bus-Integration behandelt die folgenden Aspekte, um Ihre App mit Azure Service Buszu verbinden.

Ein ServiceBusClient wird im DI-Container registriert, um eine Verbindung zu Azure Service Busherzustellen.
Wendet die ServiceBusClient-Konfigurationen entweder direkt im Code oder über Einstellungen in der Konfigurationsdatei an.

Voraussetzungen

Azure-Abonnement – Erstellen Sie eines kostenlos
Azure Service Bus-Namespace erfahren Sie mehr darüber, wie Sie einen Service Bus-Namespace hinzufügenkönnen. Alternativ können Sie eine Verbindungszeichenfolge verwenden, die in Produktionsumgebungen nicht empfohlen wird.

Loslegen

Um mit der .NET AspireAzure Service Bus-Integration zu beginnen, installieren Sie das 📦Aspire.Azure. Messaging.ServiceBus NuGet-Paket im Projekt client-Verbrauch, d. h. dem Projekt der Anwendung, die den Azure Service Busclientverwendet.

.NET CLI
PackageReference-

dotnet add package Aspire.Azure.Messaging.ServiceBus

<PackageReference Include="Aspire.Azure.Messaging.ServiceBus"
                  Version="*" />

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

Beispielverwendung

Rufen Sie in der datei Program.cs Ihres client-verbrauchenden Projekts die AddAzureServiceBusClient-Erweiterung auf, um eine ServiceBusClient für die Verwendung über den Container zum Einfügen von Abhängigkeiten zu registrieren.

builder.AddAzureServiceBusClient("messaging");

Um die konfigurierte ServiceBusClient Instanz mithilfe der Abhängigkeitseinfügung abzurufen, benötigen Sie sie als Konstruktorparameter. Um beispielsweise das client aus einem Beispielservice abzurufen:

public class ExampleService(ServiceBusClient client)
{
    // ...
}

App-Hostverwendung

Um Azure Service Bus Hosting-Unterstützung zu Ihrem IDistributedApplicationBuilderhinzuzufügen, installieren Sie das 📦Aspire.Hosting.Azure.ServiceBus NuGet-Paket im App-Host Projekt.

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.ServiceBus

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

Registrieren Sie in Ihrem App-Hostprojekt die Service Bus-Integration, und nutzen Sie den Dienst mit den folgenden Methoden:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureServiceBus("messaging")
    : builder.AddConnectionString("messaging");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(serviceBus)

Konfiguration

Die .NET.NET Aspire Service Bus-Integration bietet mehrere Optionen zum Konfigurieren der ServiceBusClient basierend auf den Anforderungen und Konventionen Ihres Projekts.

Verwendung von Konfigurationsanbietern

Die ServiceBus-Integration unterstützt Microsoft.Extensions.Configuration. Es lädt die AzureMessagingServiceBusSettings aus appsettings.json oder anderen Konfigurationsdateien mithilfe des Aspire:Azure:Messaging:ServiceBus-Schlüssels.

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "ServiceBus": {
          "DisableHealthChecks": true,
          "DisableTracing": false,
          "ClientOptions": {
            "Identifier": "CLIENT_ID"
          }
        }
      }
    }
  }
}

Wenn Sie Ihre Konfigurationen im Abschnitt Aspire:Azure:Messaging:ServiceBus Ihrer appsettings.json Datei eingerichtet haben, können Sie die Methode einfach AddAzureServiceBusClient aufrufen, ohne Parameter zu übergeben.

Verwendung von Inlinedelegaten

Sie können auch den Action<AzureMessagingServiceBusSettings> Delegat übergeben, um einige oder alle Optionen inline einzurichten, z. B. um die FullyQualifiedNamespacefestzulegen:

builder.AddAzureServiceBusClient(
    "messaging",
    static settings => settings.FullyQualifiedNamespace = "YOUR_SERVICE_BUS_NAMESPACE");

Sie können die ServiceBusClientOptions- auch mit dem Action<IAzureClientBuilder<ServiceBusClient, ServiceBusClientOptions>>-Delegaten einrichten, dem zweiten Parameter der AddAzureServiceBus-Methode. Um beispielsweise die ServiceBusClient-ID festzulegen, um die clientzu identifizieren:

builder.AddAzureServiceBusClient(
    "messaging",
    static clientBuilder =>
        clientBuilder.ConfigureOptions(
            static options => options.Identifier = "CLIENT_ID"));

Konfigurationsoptionen

Die folgenden konfigurierbaren Optionen werden über die AzureMessagingServiceBusSettings Klasse verfügbar gemacht:

Name	Beschreibung
`ConnectionString`	Die Verbindungszeichenfolge, die zur Verbindung mit dem Service Bus-Namespace verwendet wird.
`Credential`	Die Anmeldeinformationen, die für die Authentifizierung beim Service Bus-Namespace verwendet werden.
`FullyQualifiedNamespace`	Der vollqualifizierte Service Bus-Namespace.
`DisableTracing`	Deaktiviert die Ablaufverfolgung für den Service Bus client.
^†`HealthCheckQueueName`	Der Name der Warteschlange, die für Gesundheitsprüfungen verwendet wird.
^†`HealthCheckTopicName`	Der Name des Themas, das für Gesundheitsprüfungen verwendet wird.

^† Mindestens eine der Namensoptionen ist erforderlich, wenn Integritätsprüfungen aktiviert werden.

Observability und Telemetrie

.NET .NET Aspire Integrationen richten automatisch Protokollierungs-, Tracing- und Metrikkonfigurationen ein, die manchmal als den Säulen der Observierbarkeitbezeichnet werden. Weitere Informationen zur Integrations-Observability und Telemetrie finden Sie unter .NET.NET Aspire Integrationen-Übersicht. Abhängig vom Backend-Dienst unterstützen einige Integrationen möglicherweise nur bestimmte 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 AspireAzure Service Bus-Integration verwendet die folgenden Protokollkategorien:

Azure.Core
Azure.Identity
Azure-Messaging-ServiceBus

Nachverfolgung

Anmerkung

Die Unterstützung von Service Bus ActivitySource im Azure SDK für .NET ist experimentell, und die Form der Aktivitäten kann sich in Zukunft ohne vorherige Ankündigung ändern.

Sie können die Ablaufverfolgung auf verschiedene Arten aktivieren:

Festlegen der Azure.Experimental.EnableActivitySource-Laufzeitkonfigurationseinstellung auf true. Dies kann mit einer der folgenden Aktionen erfolgen:
- Rufen Sie AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);auf.
- Fügen Sie der Projektdatei die Einstellung RuntimeHostConfigurationOption hinzu:
```
<ItemGroup>
    <RuntimeHostConfigurationOption
         Include="Azure.Experimental.EnableActivitySource"
         Value="true" />
</ItemGroup>
```
Legen Sie die AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE Umgebungsvariable auf "true" fest.
- Kann durch das Verketten eines Aufrufs an WithEnvironment("AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE", "true") erreicht werden

Bei Aktivierung gibt die .NET AspireAzure Service Bus-Integration die folgenden Tracing-Aktivitäten mithilfe von OpenTelemetryaus.

Message
ServiceBusSender.Send
ServiceBusSender.Schedule
ServiceBusSender.Cancel
ServiceBusReceiver.Receive
ServiceBusReceiver.ReceiveDeferred
ServiceBusReceiver.Peek
ServiceBusReceiver.Abandon
ServiceBusReceiver.Complete
ServiceBusReceiver.DeadLetter
ServiceBusReceiver.Defer
ServiceBusReceiver.RenewMessageLock
ServiceBusSessionReceiver.RenewSessionLock
ServiceBusSessionReceiver.GetSessionState
ServiceBusSessionReceiver.SetSessionState
ServiceBusProcessor.ProcessMessage
ServiceBusSessionProcessor.ProcessSessionMessage
ServiceBusRuleManager.CreateRule
ServiceBusRuleManager.DeleteRule
ServiceBusRuleManager.GetRules

Weitere Informationen finden Sie unter:

Kennzahlen

Die .NET AspireAzure Service Bus-Integration unterstützt derzeit standardmäßig keine Metriken aufgrund von Einschränkungen mit dem Azure SDK für .NET. Wenn sich dies in Zukunft ändert, wird dieser Abschnitt aktualisiert, um diese Änderungen widerzuspiegeln.

Freigeben über