integração .NET AspireAzure Service Bus

Artigo
03/09/2025

Inclui: integração de hospedagem e Client integração

Azure Service Bus é um agente de mensagens empresarial totalmente gerenciado com filas de mensagens e tópicos de publicação/assinatura. A integração .NET AspireAzure Service Bus permite que você se conecte a instâncias do Azure Service Bus a partir de aplicativos .NET.

Integração de hospedagem

A integração de hospedagem do .NET.NET AspireAzure Service Bus modela os vários recursos do Barramento de Serviço nos seguintes tipos:

AzureServiceBusResource: representa um recurso de Azure Service Bus.
AzureServiceBusEmulatorResource: representa um recurso do emulador Azure Service Bus.

Para acessar esses tipos e APIs para expressá-los, adicione o 📦Aspire. Hospedagem.Azure. 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="*" />

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

Adicionar Azure Service Bus recurso

No projeto de host do aplicativo, chame AddAzureServiceBus para adicionar e retornar um construtor de recursos Azure Service Bus.

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");

// After adding all resources, run the app...

Quando você adiciona um AzureServiceBusResource ao host do aplicativo, ele expõe outras APIs úteis que permitem adicionar filas e tópicos. Em outras palavras, você deve adicionar um AzureServiceBusResource antes de adicionar qualquer um dos outros recursos do Service Bus.

Importante

Quando você chama AddAzureServiceBus, ele chama implicitamente AddAzureProvisioning— o que adiciona suporte para gerar recursos Azure dinamicamente durante a inicialização do aplicativo. O aplicativo deve configurar a assinatura e o local apropriados. Para obter mais informações, confira Configuração.

Provisionamento gerado por Bicep

Caso você seja novo no Bicep, é uma linguagem específica do domínio para definir recursos de Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente; as APIs de provisionamento geram Bicep para você. Quando você publica seu aplicativo, o Bicep gerado é exibido juntamente ao arquivo de manifesto. Quando você adiciona um recurso Azure Service Bus, o Bicep a seguir é gerado:

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param sku string = 'Standard'

param principalType string

param principalId string

resource service_bus 'Microsoft.ServiceBus/namespaces@2024-01-01' = {
  name: take('servicebus-${uniqueString(resourceGroup().id)}', 50)
  location: location
  properties: {
    disableLocalAuth: true
  }
  sku: {
    name: sku
  }
  tags: {
    'aspire-resource-name': 'service-bus'
  }
}

resource service_bus_AzureServiceBusDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(service_bus.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '090c5cfd-751d-490a-894a-3ce6f1109419')
    principalType: principalType
  }
  scope: service_bus
}

output serviceBusEndpoint string = service_bus.properties.serviceBusEndpoint

O Bicep anterior é um módulo que provisiona um namespace Azure Service Bus com os seguintes padrões:

sku: a SKU do namespace do Barramento de Serviço. O padrão é Standard.
location: o local do namespace do Barramento de Serviço. O padrão é o local do grupo de recursos.

Além do namespace do Barramento de Serviço, ele também provisiona uma função interna Azure de controle de acesso baseado em função (Azure RBAC) de Azure Service Bus Proprietário de Dados. A função é atribuída ao grupo de recursos do namespace do Barramento de Serviço. Para obter mais informações, consulte Azure Service Bus Proprietário de Dados.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Esse tipo permite a personalização do Bicep gerado ao oferecer uma API fluente para configurar os recursos do Azure utilizando a API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por exemplo, você pode configurar o sku, o local e muito mais. O exemplo a seguir demonstra como personalizar o recurso de Azure Service Bus:

builder.AddAzureServiceBus("service-bus")
    .ConfigureInfrastructure(infra =>
    {
        var serviceBusNamespace = infra.GetProvisionableResources()
                                       .OfType<ServiceBusNamespace>()
                                       .Single();

        serviceBusNamespace.Sku = new ServiceBusSku
        {
            Tier = ServiceBusSkuTier.Premium
        };
        serviceBusNamespace.Tags.Add("ExampleKey", "Example value");
    });

O código anterior:

Encadeia uma chamada para a API ConfigureInfrastructure:
- O parâmetro infra é uma instância do tipo AzureResourceInfrastructure.
- Os recursos provisionáveis são recuperados chamando o método GetProvisionableResources().
- O elemento único ServiceBusNamespace é recuperado.
- O ServiceBusNamespace.Sku criado com um ServiceBusSkuTier.Premium
- Uma etiqueta é adicionada ao namespace do Barramento de Serviço com uma chave de ExampleKey e um valor de Example value.

Há muitas outras opções de configuração disponíveis para personalizar o recurso de Azure Service Bus. Para obter mais informações, consulte Azure.Provisioning.ServiceBus. Para obter mais informações, consulte Azure. Personalização do provisionamento.

Conectar-se a um namespace Azure Service Bus existente

Você pode ter um namespace Azure Service Bus existente ao qual deseja se conectar. Em vez de representar um novo recurso de Azure Service Bus, você pode adicionar uma cadeia de conexão ao host do aplicativo. Para adicionar uma conexão a um namespace Azure Service Bus existente, chame o método AddConnectionString:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddConnectionString("messaging");

builder.AddProject<Projects.WebApplication>("web")
       .WithReference(serviceBus);

// After adding all resources, run the app...

Nota

As cadeias de conexão são usadas para representar uma ampla gama de informações de conexão, incluindo conexões de banco de dados, agentes de mensagens, URIs de ponto de extremidade e outros serviços. Em .NET.NET Aspire nomenclatura, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

A cadeia de conexão é configurada na configuração do host do aplicativo, normalmente em Segredos do Usuário, na seção ConnectionStrings. O host do aplicativo injeta essa cadeia de conexão como uma variável de ambiente em todos os recursos dependentes, por exemplo:

{
    "ConnectionStrings": {
        "messaging": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={key_name};SharedAccessKey={key_value};"
    }
}

O recurso dependente pode acessar a cadeia de conexão injetada chamando o método GetConnectionString e passando o nome da conexão como o parâmetro, nesse caso "messaging". A API GetConnectionString é uma abreviação de IConfiguration.GetSection("ConnectionStrings")[name].

Adicionar fila Azure Service Bus

Para adicionar uma fila Azure Service Bus, chame o método AddServiceBusQueue no IResourceBuilder<AzureServiceBusResource>:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");
serviceBus.AddServiceBusQueue("queue");

// After adding all resources, run the app...

Quando você chama AddServiceBusQueue(IResourceBuilder<AzureServiceBusResource>, String, String), configura os recursos do Barramento de Serviço para criar uma fila chamada queue. A fila é criada no namespace do Barramento de Serviço que é representado pelo AzureServiceBusResource que você adicionou anteriormente. Para obter mais informações, consulte Filas, tópicos e assinaturas no Azure Service Bus.

Adicionar tópico Azure Service Bus e assinatura

Para adicionar um tópico Azure Service Bus, chame o método AddServiceBusTopic no IResourceBuilder<AzureServiceBusResource>:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");
serviceBus.AddServiceBusTopic("topic");

// After adding all resources, run the app...

Quando você chama AddServiceBusTopic(IResourceBuilder<AzureServiceBusResource>, String, String), ele configura os recursos do Barramento de Serviço para criar um tópico chamado topic. O tópico é criado no namespace do Barramento de Serviço que é representado pelo AzureServiceBusResource que você adicionou anteriormente.

Para adicionar uma assinatura para o tópico, chame o método AddServiceBusSubscription no IResourceBuilder<AzureServiceBusTopicResource> e configure-o usando o método WithProperties:

using Aspire.Hosting.Azure;

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging");
var topic = serviceBus.AddServiceBusTopic("topic");
topic.AddServiceBusSubscription("sub1")
     .WithProperties(subscription =>
     {
         subscription.MaxDeliveryCount = 10;
         subscription.Rules.Add(
             new AzureServiceBusRule("app-prop-filter-1")
             {
                 CorrelationFilter = new()
                 {
                     ContentType = "application/text",
                     CorrelationId = "id1",
                     Subject = "subject1",
                     MessageId = "msgid1",
                     ReplyTo = "someQueue",
                     ReplyToSessionId = "sessionId",
                     SessionId = "session1",
                     SendTo = "xyz"
                 }
             });
     });

// After adding all resources, run the app...

O código anterior não só adiciona um tópico e cria e configura uma assinatura chamada sub1 para o tópico. A assinatura tem uma contagem máxima de entrega de 10 e possui uma regra chamada app-prop-filter-1. A regra é um filtro de correlação que filtra mensagens com base nas propriedades ContentType, CorrelationId, Subject, MessageId, ReplyTo, ReplyToSessionId, SessionIde SendTo.

Para obter mais informações, consulte Filas, tópicos e assinaturas no Azure Service Bus.

Adicionar recurso do emulador Azure Service Bus

Para adicionar um recurso do emulador Azure Service Bus, você deve encadear uma chamada de um <IResourceBuilder<AzureServiceBusResource>> à API RunAsEmulator.

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging")
                        .RunAsEmulator();

// After adding all resources, run the app...

Quando você chama RunAsEmulator, ele configura os recursos do Barramento de Serviço para serem executados localmente usando um emulador. O emulador nesse caso é o Azure Service Bus emulador. O Azure Service Bus Emulador fornece um ambiente local gratuito para testar seus aplicativos Azure Service Bus e é um complemento perfeito para a integração de hospedagem .NET AspireAzure. O emulador não está instalado, em vez disso, é acessível para .NET.NET Aspire como um contêiner. Quando você adiciona um contêiner ao host do aplicativo, conforme mostrado no exemplo anterior com a imagem mcr.microsoft.com/azure-messaging/servicebus-emulator (e a imagem mcr.microsoft.com/azure-sql-edge complementar), ele cria e inicia o contêiner quando o host do aplicativo é iniciado. Para obter mais informações, consulte ciclo de vida do recurso de contêiner.

Configurar o contêiner de Emulador de Barramento de Serviço

Há várias configurações disponíveis para recursos de contêiner, por exemplo, você pode configurar as portas do contêiner ou fornecer uma configuração holística JSON que substitui tudo.

Configurar a porta de host do contêiner do emulador do Barramento de Serviço

Por padrão, quando configurado pelo .NET.NET Aspire, o contêiner do emulador do Barramento de Serviço expõe os seguintes pontos de extremidade:

Ponto de extremidade	Imagem	Porta de contêiner	Porta do host
`emulator`	`mcr.microsoft.com/azure-messaging/servicebus-emulator`	5672	dinâmico
`tcp`	`mcr.microsoft.com/azure-sql-edge`	1433	dinâmico

A porta que está sendo utilizada para escuta é dinâmica por padrão. Quando o contêiner é iniciado, a porta é mapeada para uma porta aleatória no computador host. Para configurar a porta do ponto de extremidade, encadeia chamadas no construtor de recursos de contêiner fornecido pelo método RunAsEmulator e, em seguida, o WithHostPort(IResourceBuilder<AzureServiceBusEmulatorResource>, Nullable<Int32>) conforme mostrado no exemplo a seguir:

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging").RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithHostPort(7777);
                         });

// After adding all resources, run the app...

O código anterior configura o endpoint existente emulator do contêiner do emulador do Service Bus para escutar na porta 7777. A porta do contêiner do emulador do Barramento de Serviço é mapeada para a porta host, conforme mostrado na tabela a seguir:

Nome do ponto de extremidade	Mapeamento de porta (`container:host`)
`emulator`	`5672:7777`

Configurar a configuração do contêiner do emulador do Barramento de Serviço JSON

O contêiner do emulador do Barramento de Serviço executa-se com um arquivo padrão de config.json. Você pode substituir esse arquivo inteiramente ou atualizar a configuração de JSON com uma versão JsonNode da configuração.

Para fornecer um arquivo de configuração de JSON personalizado, chame o método WithConfigurationFile(IResourceBuilder<AzureServiceBusEmulatorResource>, String):

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging").RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithConfigurationFile(
                                 path: "./messaging/custom-config.json");
                         });

O código anterior configura o contêiner do emulador do Service Bus para usar um arquivo de configuração personalizado de JSON localizado em ./messaging/custom-config.json. Para, em vez disso, substituir propriedades específicas na configuração padrão, chame o método WithConfiguration(IResourceBuilder<AzureServiceBusEmulatorResource>, Action<JsonNode>):

var builder = DistributedApplication.CreateBuilder(args);

var serviceBus = builder.AddAzureServiceBus("messaging").RunAsEmulator(
                         emulator =>
                         {
                             emulator.WithConfiguration(
                                 (JsonNode configuration) =>
                                 {
                                     var userConfig = configuration["UserConfig"];
                                     var ns = userConfig["Namespaces"][0];
                                     var firstQueue = ns["Queues"][0];
                                     var properties = firstQueue["Properties"];
                                     
                                     properties["MaxDeliveryCount"] = 5;
                                     properties["RequiresDuplicateDetection"] = true;
                                     properties["DefaultMessageTimeToLive"] = "PT2H";
                                 });
                         });

// After adding all resources, run the app...

O código anterior recupera o nó UserConfig da configuração padrão. Em seguida, ele atualiza as propriedades da primeira fila para definir o MaxDeliveryCount como 5, RequiresDuplicateDetection para truee DefaultMessageTimeToLive para 2 hours.

Verificações de integridade das integrações de hospedagem

A integração de hospedagem Azure Service Bus adiciona automaticamente uma verificação de integridade para o recurso do Barramento de Serviço. A verificação de integridade verifica se o Barramento de Serviço está em execução e se uma conexão pode ser estabelecida com ele.

A integração de hospedagem depende do pacote NuGet 📦 AspNetCore.HealthChecks.AzureServiceBus.

integração Client

Para começar a usar a integração do cliente .NET AspireAzure Service Bus, instale o pacote NuGet 📦Aspire.Azure.Messaging.ServiceBus no projeto que consome o cliente, ou seja, o projeto do aplicativo que utiliza o cliente do Barramento de Serviço. A integração do cliente do Barramento de Serviço registra uma instância de ServiceBusClient que você pode usar para interagir com o Barramento de Serviço.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Messaging.ServiceBus

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

Adicionar cliente do Barramento de Serviço

No arquivo Program.cs do projeto que utiliza o cliente, chame o método de extensão AddAzureServiceBusClient em qualquer IHostApplicationBuilder para registrar um ServiceBusClient para que possa ser usado por meio do contêiner de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddAzureServiceBusClient(connectionName: "messaging");

Dica

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso do Barramento de Serviço no projeto de host do aplicativo. Em outras palavras, quando você chama AddAzureServiceBus e fornece um nome de messaging esse mesmo nome deve ser usado ao chamar AddAzureServiceBusClient. Para obter mais informações, consulte Adicionar recursoAzure Service Bus.

Em seguida, você pode recuperar a instância ServiceBusClient usando injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

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

Para obter mais informações sobre injeção de dependência, consulte .NET injeção de dependência.

Adicionar cliente do Barramento de Serviço autenticado por chave

Pode haver situações em que você deseja registrar várias instâncias de ServiceBusClient com nomes de conexão diferentes. Para registrar clientes com chave do Service Bus, chame o método AddKeyedAzureServiceBusClient:

builder.AddKeyedAzureServiceBusClient(name: "mainBus");
builder.AddKeyedAzureServiceBusClient(name: "loggingBus");

Importante

Ao usar serviços baseados em chave, espera-se que o recurso do Barramento de Serviços configure dois barramentos nomeados, um para o mainBus e outro para o loggingBus.

Em seguida, você pode recuperar as instâncias de ServiceBusClient usando injeção de dependência. Por exemplo, para recuperar a conexão de um serviço de exemplo:

public class ExampleService(
    [FromKeyedServices("mainBus")] ServiceBusClient mainBusClient,
    [FromKeyedServices("loggingBus")] ServiceBusClient loggingBusClient)
{
    // Use clients...
}

Para obter mais informações sobre serviços chaveados, consulte .NET injeção de dependência: serviços chaveados.

Configuração

A integração .NET AspireAzure Service Bus fornece várias opções para configurar a conexão com base nos requisitos e convenções do seu projeto.

Utilize uma string de conexão

Ao usar uma cadeia de conexão da seção de configuração ConnectionStrings, você pode fornecer o nome da cadeia de conexão ao chamar o método AddAzureServiceBusClient:

builder.AddAzureServiceBusClient("messaging");

Em seguida, a cadeia de conexão é recuperada da seção de configuração ConnectionStrings:

{
  "ConnectionStrings": {
    "messaging": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={keyName};SharedAccessKey={key};"
  }
}

Para obter mais informações sobre como formatar essa cadeia de conexão, consulte a documentação connectionString.

Usar provedores de configuração

A integração .NET AspireAzure Service Bus dá suporte a Microsoft.Extensions.Configuration. Ele carrega o AzureMessagingServiceBusSettings da configuração utilizando a chave Aspire:Azure:Messaging:ServiceBus. O snippet a seguir é um exemplo de um arquivo de appsettings.json que configura algumas das opções:

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "ServiceBus": {
          "ConnectionString": "Endpoint=sb://{namespace}.servicebus.windows.net/;SharedAccessKeyName={keyName};SharedAccessKey={key};",
          "DisableTracing": false
        }
      }
    }
  }
}

Para obter o esquema de integração completo do cliente do Barramento de Serviço JSON, consulte Aspire.Azure. Messaging.ServiceBus/ConfigurationSchema.json.

Usar delegados em linha

Além disso, você pode passar o delegado Action<AzureMessagingServiceBusSettings> configureSettings para configurar algumas ou todas as opções em linha, por exemplo, para desabilitar o rastreamento a partir do código:

builder.AddAzureServiceBusClient(
    "messaging",
    static settings => settings.DisableTracing = true);

Você também pode configurar o Azure.Messaging.ServiceBus.ServiceBusClientOptions usando o parâmetro Action<ServiceBusClientOptions> configureClientOptions opcional do método AddAzureServiceBusClient. Por exemplo, para definir o sufixo de cabeçalho do agente de usuário ServiceBusClientOptions.Identifier para todas as solicitações feitas por este cliente:

builder.AddAzureServiceBusClient(
    "messaging",
    configureClientOptions:
        clientOptions => clientOptions.Identifier = "myapp");

Client checagens de saúde de integração

Por padrão, as integrações de .NET.NET Aspire habilitam verificações de saúde para todos os serviços. Para obter mais informações, consulte .NET.NET Aspire visão geral de integrações.

A integração .NET AspireAzure Service Bus:

Adiciona a verificação de integridade quando AzureMessagingServiceBusSettings.DisableTracing é false, que tenta se conectar ao Barramento de Serviço.
Integra-se ao endpoint HTTP /health, que especifica que todas as verificações de integridade já registradas devem passar para que o aplicativo seja considerado pronto para aceitar tráfego.

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

Além de obter diagnósticos de solicitação Azure Service Bus para solicitações com falha, você pode configurar limites de latência para determinar quais diagnósticos de solicitações Azure Service Bus bem-sucedidas serão registrados. Os valores padrão são 100 ms para operações de ponto e 500 ms para operações não pontuais.

builder.AddAzureServiceBusClient(
    "messaging",
    configureClientOptions:
        clientOptions => {
            clientOptions.ServiceBusClientTelemetryOptions = new()
            {
                ServiceBusThresholdOptions = new()
                {
                    PointOperationLatencyThreshold = TimeSpan.FromMilliseconds(50),
                    NonPointOperationLatencyThreshold = TimeSpan.FromMilliseconds(300)
                }
            };
        });

Rastreamento

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

Azure Service Bus tracing está atualmente em versão prévia, portanto, você deve ativar a opção experimental para assegurar que os rastreamentos sejam realizados.

AppContext.SetSwitch("Azure.Experimental.EnableActivitySource", true);

Para mais informações, consulte Azure Service Bus: rastreamento distribuído e correlação através de mensagens do Barramento de Serviço.

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 do Azure.

Consulte também

Azure Service Bus
visão geral das integrações .NET.NET Aspire
visão geral das integrações .NET AspireAzure
.NET Aspire GitHub repositório

Compartilhar via