integração .NET AspireAzure Service Bus

Artigo
12/13/2024

Aplicativos nativos de nuvem geralmente exigem comunicação com serviços de mensagens, como Azure Service Bus. Os serviços de mensagens ajudam a desacoplar aplicativos e habilitar cenários que dependem de recursos como filas, tópicos e assinaturas, transações atômicas, balanceamento de carga e muito mais. A integração do Barramento de Serviço .NET Aspire aborda as seguintes questões para conectar seu aplicativo ao Azure Service Bus:

Um ServiceBusClient é registrado no contêiner de DI para se conectar ao Azure Service Bus.
Aplica as configurações ServiceBusClient diretamente no código ou por meio de arquivo de configuração.

Pré-requisitos

assinatura Azure – criar uma gratuitamente
Azure Service Bus namespace, saiba mais sobre como adicionar um namespace do Barramento de Serviço. Como alternativa, você pode usar uma cadeia de conexão, que não é recomendada em ambientes de produção.

Começar

Para começar a usar a integração , instale o pacote NuGet ..Messaging.ServiceBus no projeto consumidor , ou seja, o projeto do aplicativo que usa o .

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Messaging.ServiceBus

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

Para obter mais informações, consulte dotnet add package ou Gerenciar dependências de pacotes em .NET aplicativos.

Exemplo de uso

No arquivo Program.cs do seu projeto que consome client, chame a extensão AddAzureServiceBusClient para registrar um ServiceBusClient para uso através do container de injeção de dependência.

builder.AddAzureServiceBusClient("messaging");

Para recuperar a instância de ServiceBusClient configurada usando a injeção de dependência, solicite-a como parâmetro do construtor. Por exemplo, para recuperar o client de um serviço de exemplo:

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

Uso do host do aplicativo

Para adicionar suporte de hospedagem ao seu , instale o . Hospedagem.. O ServiceBus pacote NuGet no projeto do host do aplicativo .

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.ServiceBus

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

No projeto de host do aplicativo, registre a integração do Barramento de Serviço e consuma o serviço usando os seguintes métodos:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Configuração

A integração do Barramento de Serviço .NET.NET Aspire fornece várias opções para configurar o ServiceBusClient com base nos requisitos e convenções do seu projeto.

Usar provedores de configuração

A integração do Barramento de Serviço dá suporte a Microsoft.Extensions.Configuration. Ele carrega o AzureMessagingServiceBusSettings de appsettings.json ou de outros arquivos de configuração usando a chave Aspire:Azure:Messaging:ServiceBus.

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

Se você tiver configurado suas configurações na seção Aspire:Azure:Messaging:ServiceBus do arquivo appsettings.json, basta chamar o método AddAzureServiceBusClient sem passar parâmetros.

Usar delegados em linha

Você também pode passar o delegado Action<AzureMessagingServiceBusSettings> para configurar algumas ou todas as opções diretamente, por exemplo, para definir o FullyQualifiedNamespace:

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

Você também pode configurar o ServiceBusClientOptions usando o delegato Action<IAzureClientBuilder<ServiceBusClient, ServiceBusClientOptions>>, que é o segundo parâmetro do método AddAzureServiceBus. Por exemplo, para definir a ID do ServiceBusClient para identificar o client:

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

Opções de configuração

As seguintes opções configuráveis são expostas por meio da classe AzureMessagingServiceBusSettings:

Nome	Descrição
`ConnectionString`	A cadeia de conexão usada para se conectar ao namespace do Barramento de Serviço.
`Credential`	A credencial usada para autenticar no namespace do Barramento de Serviço.
`FullyQualifiedNamespace`	O namespace totalmente qualificado do Service Bus.
`DisableTracing`	Desabilita o rastreamento do clientdo Barramento de Serviço.
^†`HealthCheckQueueName`	O nome da fila usada para verificações de saúde.
^†`HealthCheckTopicName`	O nome do tópico usado para checagens de saúde.

^† Pelo menos uma das opções de nome é obrigatória ao habilitar verificações de integridade.

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente configurações de Log, Rastreamento e Métricas, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre a observabilidade e a telemetria de integração, consulte .NET.NET Aspire visão geral das integrações. Dependendo do serviço de backup, algumas integrações só podem dar suporte a alguns desses recursos. Por exemplo, algumas integrações dão suporte a registro em log e rastreamento, mas não a métricas. Os recursos de telemetria também podem ser desabilitados usando as técnicas apresentadas na seção Configuration.

Registro

A integração .NET AspireAzure Service Bus usa as seguintes categorias de log:

Azure.Core
Azure.Identity
Azure-Messaging-ServiceBus

Rastreamento

Nota

O suporte ao ActivitySource no Barramento de Serviço no SDK do Azure para .NET é experimental, e a estrutura das atividades pode mudar no futuro sem aviso prévio.

Você pode habilitar o rastreamento de várias maneiras:

Definir a configuração do Azure.Experimental.EnableActivitySourceruntime como true. O que pode ser feito com qualquer uma das opções:
- Chamar AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);.
- Adicione a configuração de RuntimeHostConfigurationOption ao arquivo de projeto:
```
<ItemGroup>
    <RuntimeHostConfigurationOption
         Include="Azure.Experimental.EnableActivitySource"
         Value="true" />
</ItemGroup>
```
Defina a variável de ambiente AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE como "true".
- Pode ser alcançado pelo encadeamento de uma chamada para WithEnvironment("AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE", "true")

Quando habilitada, a integração .NET AspireAzure Service Bus emitirá as seguintes atividades de rastreamento 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

Para obter mais informações, consulte:

Métricas

A integração .NET AspireAzure Service Bus atualmente não dá suporte a métricas por padrão devido a limitações com o SDK Azure para .NET. Se isso mudar no futuro, esta seção será atualizada para refletir essas alterações.

Compartilhar via