.NET Aspire Azure Service Bus integração

Artigo
12/15/2024

Os aplicativos nativos da nuvem geralmente exigem comunicação com serviços de mensagens, como Azure Service Bus. Os serviços de mensagens ajudam a dissociar aplicativos e permitem 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 .NET Aspire Service Bus aborda as seguintes preocupações para conectar o seu aplicativo a Azure Service Bus:

Um ServiceBusClient é registrado no contêiner DI para conexão com Azure Service Bus.
Aplica ServiceBusClient configurações inline através do código ou através das definições do ficheiro de configuração.

Pré-requisitos

Azure subscrição - crie uma gratuitamente
Azure Service Bus namespace, saiba mais sobre como adicionar um namespace do Service Bus. Como alternativa, você pode usar uma cadeia de conexão, o que não é recomendado em ambientes de produção.

Começar

Para começar com a integração .NET AspireAzure Service Bus, instale o pacote NuGet 📦Aspire.Azure.Messaging.ServiceBus no projeto que consome client, ou seja, o projeto para a aplicação que utiliza o Azure Service Busclient.

.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 Gerir dependências de pacotes em aplicações .NET.

Exemplo de utilização

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

builder.AddAzureServiceBusClient("messaging");

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

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

Utilização do host da aplicação

Para adicionar Azure Service Bus suporte de hospedagem ao seu IDistributedApplicationBuilder, instale o pacote NuGet 📦Aspire.Hosting.Azure.ServiceBus no projeto de host do aplicativo .

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.ServiceBus

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

Em seu projeto de host de aplicativo, registre a integração do Service Bus 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 .NET.NET Aspire Service Bus 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 Service Bus suporta Microsoft.Extensions.Configuration. Ele carrega o AzureMessagingServiceBusSettings de appsettings.json ou de outros ficheiros de configuração com a chave Aspire:Azure:Messaging:ServiceBus.

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

Se você configurou suas configurações na seção Aspire:Azure:Messaging:ServiceBus do seu arquivo appsettings.json, você pode simplesmente chamar o método AddAzureServiceBusClient sem passar nenhum parâmetro.

Usar delegados integrados

Você também pode passar o delegado Action<AzureMessagingServiceBusSettings> para configurar algumas ou todas as opções em linha, 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 Action<IAzureClientBuilder<ServiceBusClient, ServiceBusClientOptions>> delegação, o segundo parâmetro do método AddAzureServiceBus. Por exemplo, para definir o ID de 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 através da classe AzureMessagingServiceBusSettings:

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

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

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente as configurações de Logging, Trace e Metrics, que às vezes são conhecidas como os pilares da observabilidade. Para obter mais informações sobre observabilidade e telemetria de integração, consulte Visão geral de integrações .NET.NET Aspire. Dependendo do serviço de suporte, algumas integrações podem suportar apenas alguns desses recursos. Por exemplo, algumas integrações suportam registro em log e rastreamento, mas não métricas. Os recursos de telemetria também podem ser desativados usando as técnicas apresentadas na seção de configuração .

Registo

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

Azure.Core
Azure.Identity
Azure-Messaging-ServiceBus

Rastreio

Observação

O suporte ao Service Bus ActivitySource no SDK do Azure para .NET é experimental e a forma das atividades pode mudar no futuro sem aviso prévio.

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

Definir a configuração de tempo de execução Azure.Experimental.EnableActivitySource para true. O que pode ser feito com uma das seguintes opções:
- Ligue para o AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);.
- Adicione a configuração RuntimeHostConfigurationOption ao seu 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 encadeando uma chamada para WithEnvironment("AZURE_EXPERIMENTAL_ENABLE_ACTIVITY_SOURCE", "true")

Quando habilitada, a integração de .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 mais informações, consulte:

Métricas

A integração .NET AspireAzure Service Bus atualmente não oferece 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.

Partilhar via