integrazione di .NET AspireAzure Service Bus

Articolo
12/15/2024

Le app native del cloud spesso richiedono la comunicazione con i servizi di messaggistica, ad esempio Azure Service Bus. I servizi di messaggistica consentono di separare le applicazioni e abilitare scenari basati su funzionalità quali code, argomenti e sottoscrizioni, transazioni atomiche, bilanciamento del carico e altro ancora. L'integrazione del Service Bus .NET Aspire gestisce i seguenti aspetti per la connessione dell'app a Azure Service Bus:

Un ServiceBusClient viene registrato nel contenitore DI per la connessione a Azure Service Bus.
Applica le configurazioni ServiceBusClient in linea tramite codice o tramite impostazioni del file di configurazione.

Prerequisiti

abbonamento Azure - creane uno gratuitamente
Azure Service Bus namespace, scopri come aggiungere un Service Bus namespace. In alternativa, è possibile usare una stringa di connessione, che non è consigliata negli ambienti di produzione.

Inizia

Per iniziare a usare l'integrazione di .NET AspireAzure Service Bus, installare il pacchetto NuGet 📦Aspire.Azure.Messaging.ServiceBus nel progetto cliente, cioè il progetto per l'applicazione che utilizza il client Azure Service Bus.

.NET dell'interfaccia della riga di comando
PackageReference

dotnet add package Aspire.Azure.Messaging.ServiceBus

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

Per altre informazioni, vedere dotnet add package o Manage package dependencies in .NET applications.

Esempio di utilizzo

Nel file Program.cs del progetto che utilizza il client, chiamare l'estensione AddAzureServiceBusClient per registrare un ServiceBusClient da usare tramite il contenitore di iniezione delle dipendenze.

builder.AddAzureServiceBusClient("messaging");

Per recuperare l'istanza di ServiceBusClient configurata usando l'inserimento delle dipendenze, richiederla come parametro del costruttore. Ad esempio, per recuperare il client da un servizio di esempio:

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

Utilizzo dell'host dell'app

Per aggiungere supporto per l'hosting al , installare il . Ospitare.. ServiceBus pacchetto NuGet nel progetto host dell'app .

.NET dell'interfaccia della riga di comando
PackageReference

dotnet add package Aspire.Hosting.Azure.ServiceBus

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

Nel progetto host dell'app, registrare l'integrazione del Service Bus e utilizzare il servizio tramite i seguenti metodi:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Configurazione

L'integrazione del .NET.NET Aspire Service Bus offre più opzioni per configurare il ServiceBusClient in base ai requisiti e alle convenzioni del progetto.

Utilizzare i provider di configurazione

L'integrazione del bus di servizio supporta Microsoft.Extensions.Configuration. Carica il AzureMessagingServiceBusSettings da appsettings.json o da altri file di configurazione usando la chiave Aspire:Azure:Messaging:ServiceBus.

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

Se sono state configurate le configurazioni nella sezione Aspire:Azure:Messaging:ServiceBus del file di appsettings.json, è sufficiente chiamare il metodo AddAzureServiceBusClient senza passare alcun parametro.

Usare delegati inline

È anche possibile passare il delegato Action<AzureMessagingServiceBusSettings> per configurare direttamente alcune o tutte le opzioni, ad esempio per impostare il FullyQualifiedNamespace:

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

È anche possibile configurare ServiceBusClientOptions usando delegato, il secondo parametro del metodo . Ad esempio, per impostare l'ID ServiceBusClient per identificare il client:

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

Opzioni di configurazione

Le opzioni configurabili seguenti vengono esposte tramite la classe AzureMessagingServiceBusSettings:

Nome	Descrizione
`ConnectionString`	Stringa di connessione utilizzata per connettersi allo spazio dei nomi del bus di servizio.
`Credential`	La credenziale utilizzata per l'autenticazione nello spazio dei nomi del bus di servizio.
`FullyQualifiedNamespace`	Spazio dei nomi completamente qualificato del bus di servizio.
`DisableTracing`	Disabilita il tracciamento per il client del Service Bus.
^†`HealthCheckQueueName`	Nome della coda utilizzata per i controlli di integrità.
^†`HealthCheckTopicName`	Nome dell'argomento utilizzato per le verifiche dello stato di salute.

^† Almeno una delle opzioni relative al nome è obbligatoria quando si abilitano i controlli di integrità.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni impostano automaticamente le configurazioni di registrazione, tracciamento e metriche, talvolta noti come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione .NET AspireAzure Service Bus usa le categorie di log seguenti:

Azure.Core
Azure.Identity
Azure-Messaging-ServiceBus

Tracciamento

Nota

Il supporto per il Service Bus ActivitySource nell'SDK Azure per .NET è sperimentale e la struttura delle attività può cambiare in futuro senza preavviso.

È possibile abilitare la traccia in diversi modi:

Impostazione della configurazione di runtime Azure.Experimental.EnableActivitySourcesutrue. L'operazione può essere eseguita con uno dei seguenti:
- Chiamare AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);.
- Aggiungere l'impostazione RuntimeHostConfigurationOption al file di progetto:
```
<ItemGroup>
    <RuntimeHostConfigurationOption
         Include="Azure.Experimental.EnableActivitySource"
         Value="true" />
</ItemGroup>
```
Impostare la variabile di ambiente AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE su "true".
- Può essere ottenuto concatenando una chiamata a WithEnvironment("AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE", "true")

Se abilitata, l'integrazione .NET AspireAzure Service Bus genererà le attività di traccia seguenti usando OpenTelemetry:

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

Per altre informazioni, vedere:

Metriche

L'integrazione .NET AspireAzure Service Bus attualmente non supporta le metriche di default a causa di limitazioni con l'SDK Azure per .NET. Se tali modifiche verranno apportate in futuro, questa sezione verrà aggiornata in modo da riflettere tali modifiche.

Condividi tramite