Partilhar via

.NET Aspire Azure Event Hubs integração

  • Artigo

Azure Event Hubs é um serviço nativo de streaming de dados na nuvem que pode transmitir milhões de eventos por segundo, com baixa latência, de qualquer fonte para qualquer destino. A integração .NET AspireAzure Event Hubs permite conectar-se a instâncias Azure Event Hubs a partir das suas aplicações .NET.

Integração de hospedagem

A integração de hospedagem .NET.NET AspireAzure Event Hubs modela os vários recursos do Hub de Eventos como os seguintes tipos:

Para aceder a estes tipos e APIs e expressá-los no seu projeto de aplicação anfitriã , instale o pacote NuGet 📦Aspire.Hosting.Azure.EventHubs.

dotnet add package Aspire.Hosting.Azure.EventHubs

Para obter mais informações, consulte dotnet add package ou Manage package dependencies in .NET applications.

Adicionar um recurso Azure Event Hubs

Para adicionar um AzureEventHubsResource ao seu projeto de host de aplicativo, chame o método AddAzureEventHubs fornecendo um nome e, em seguida, chame AddHub:

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs");
eventHubs.AddHub("messages");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

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

Quando você adiciona um recurso Azure Event Hubs ao host do aplicativo, ele expõe outras APIs úteis para adicionar recursos do Hub de Eventos, grupos de consumidores, expressar configuração de provisionamento explícito e permitir o uso do emulador de Azure Event Hubs. O código anterior adiciona um recurso Azure Event Hubs chamado event-hubs e um Hub de Eventos chamado messages ao projeto de host do aplicativo. O método WithReference passa as informações de conexão para o projeto ExampleService.

Importante

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

Geração de provisionamento Bicep

Se és novo no Bicep, é uma linguagem de domínio específico para a definição de recursos Azure. Com .NET.NET Aspire, você não precisa escrever Bicep manualmente, em vez disso, as APIs de provisionamento geram Bicep para você. Ao publicares a tua aplicação, o Bicep gerado é exibido juntamente com o ficheiro de manifesto. Quando você adiciona um recurso Azure Event Hubs, o seguinte Bicep é 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 event_hubs 'Microsoft.EventHub/namespaces@2024-01-01' = {
  name: take('event_hubs-${uniqueString(resourceGroup().id)}', 256)
  location: location
  sku: {
    name: sku
  }
  tags: {
    'aspire-resource-name': 'event-hubs'
  }
}

resource event_hubs_AzureEventHubsDataOwner 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(event_hubs.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'f526a384-b230-433a-b45c-95f59c4a2dec'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'f526a384-b230-433a-b45c-95f59c4a2dec')
    principalType: principalType
  }
  scope: event_hubs
}

resource messages 'Microsoft.EventHub/namespaces/eventhubs@2024-01-01' = {
  name: 'messages'
  parent: event_hubs
}

output eventHubsEndpoint string = event_hubs.properties.serviceBusEndpoint

O Bicep anterior é um módulo que provisiona um recurso Azure Event Hubs com os seguintes padrões:

  • location: A localização do grupo de recursos.
  • sku: A SKU do recurso Hubs de Eventos, como padrão é Standard.
  • principalId: O ID principal do recurso Hubs de Eventos.
  • principalType: O tipo principal do recurso Event Hubs.
  • event_hubs: O recurso do namespace Hubs de Eventos.
  • event_hubs_AzureEventHubsDataOwner: O proprietário do recurso Hubs de Eventos, com base na função Azure Event Hubs Data Owner incorporada. Para obter mais informações, consulte Azure Event Hubs Proprietário de Dados.
  • messages: O recurso Hub de Eventos.
  • eventHubsEndpoint: O ponto final do recurso Event Hubs.

O Bíceps gerado é um ponto de partida e pode ser personalizado para atender às suas necessidades específicas.

Personalizar a infraestrutura de provisionamento

Todos os recursos .NET AspireAzure são subclasses do tipo AzureProvisioningResource. Esse tipo permite personalizar o Bicep gerado ao fornecer uma API fluente para configurar os recursos Azure, utilizando a API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por exemplo, você pode configurar o kind, consistencyPolicy, locationse muito mais. O exemplo a seguir demonstra como personalizar o recurso AzureAzure Cosmos DB:

builder.AddAzureEventHubs("event-hubs")
    .ConfigureInfrastructure(infra =>
    {
        var eventHubs = infra.GetProvisionableResources()
                             .OfType<EventHubsNamespace>()
                             .Single();

        eventHubs.Sku = new EventHubsSku()
        {
            Name = EventHubsSkuName.Premium,
            Tier = EventHubsSkuTier.Premium,
            Capacity = 7,
        };
        eventHubs.PublicNetworkAccess = EventHubsPublicNetworkAccess.SecuredByPerimeter;
        eventHubs.Tags.Add("ExampleKey", "Example value");
    });

O código anterior:

Há muito mais opções de configuração disponíveis para personalizar o recurso de recursos dos Hubs de Eventos. Para obter mais informações, consulte Azure.Provisioning.PostgreSql. Para obter mais informações, consulte Azure.Provisioning personalização.

Conectar-se a um namespace de Azure Event Hubs existente

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

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddConnectionString("event-hubs");

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

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

Observação

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. Na nomenclatura .NET.NET Aspire, 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 da aplicação, normalmente sob a seção Segredos do Utilizador, na secçã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": {
    "event-hubs": "{your_namespace}.servicebus.windows.net"
  }
}

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

Adicionar grupo de consumidores do Hub de Eventos

Para adicionar um grupo de consumidores, encadeie uma chamada num IResourceBuilder<AzureEventHubsResource> à API AddConsumerGroup.

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs");
var messages = eventHubs.AddHub("messages");
messages.AddConsumerGroup("messagesConsumer");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

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

Quando você chama AddConsumerGroup, ele configura seu recurso messages Hub de Eventos para ter um grupo de consumidores chamado messagesConsumer. O grupo de consumidores é criado no namespace Azure Event Hubs representado pelo AzureEventHubsResource que você adicionou anteriormente. Para obter mais informações, consulte Azure Event Hubs: Grupos de consumidores.

Adicionar recurso Azure Event Hubs do emulador

A integração de hospedagem .NET AspireAzure Event Hubs suporta a execução do recurso Hubs de Eventos como um emulador localmente, com base na imagem de contêiner mcr.microsoft.com/azure-messaging/eventhubs-emulator/latest. Isso é benéfico para situações em que você deseja executar o recurso Hubs de Eventos localmente para fins de desenvolvimento e teste, evitando a necessidade de provisionar um recurso Azure ou conectar-se a um servidor Azure Event Hubs existente.

Para executar o recurso Hubs de Eventos como um emulador, chame o método RunAsEmulator:

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator();

eventHubs.AddHub("messages");

var exampleProject = builder.AddProject<Projects.ExampleProject>()
                            .WithReference(eventHubs);

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

O código anterior configura um recurso Azure Event Hubs para ser executado localmente em um contêiner. Para obter mais informações, consulte Azure Event Hubs Emulator.

Configurar contêiner do emulador de Hubs de Eventos

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

Configurar a porta do host do contêiner do emulador de Hubs de Eventos

Por padrão, quando configurado com o .NET.NET Aspire, o contêiner do emulador de Hubs de Eventos expõe os seguintes endpoints:

Ponto final Imagem Porto de contentores Porta do host
emulator mcr.microsoft.com/azure-messaging/eventhubs-emulator/latest 5672 dinâmico

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

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithHostPort(7777);
                       });

eventHubs.AddHub("messages");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

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

O código anterior configura o ponto de extremidade existente emulator do contentor do emulador de eventos Azure para ouvir na porta 7777. A porta do contêiner do emulador de Evento Azure é mapeada para a porta do host, conforme mostrado na tabela a seguir:

Nome do ponto final Cartografia de portos (container:host)
emulator 5672:7777
Adicionar emulador do Event Hubs com volume de dados

Para adicionar um volume de dados ao recurso do emulador de Hubs de Eventos, chame o método WithDataVolume no recurso do emulador de Hubs de Eventos:

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithDataVolume();
                       });

eventHubs.AddHub("messages");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

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

O volume de dados é usado para manter os dados do emulador de Hubs de Eventos fora do ciclo de vida de seu contêiner. O volume de dados é montado no caminho /data no contêiner. Um nome é gerado aleatoriamente, a menos que você forneça um conjunto do parâmetro name. Para obter mais informações sobre volumes de dados e detalhes sobre porque eles são preferidos em relação aos "bind mounts" , consulte os documentos Docker: Volumes.

Adicionar emulador de Hubs de Eventos com montagem de associação de dados

Para adicionar um ponto de montagem ao contentor do emulador Event Hubs, deve encadear uma chamada à API WithDataBindMount, conforme mostrado no exemplo a seguir:

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithDataBindMount("/path/to/data");
                       });

eventHubs.AddHub("messages");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

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

Importante

As montagens de ligação de dados têm funcionalidade limitada em comparação com os volumes, que oferecem melhor desempenho, portabilidade e segurança, tornando-os mais adequados para ambientes de produção. No entanto, as montagens bind permitem o acesso direto e a modificação de arquivos no sistema host, ideal para desenvolvimento e testes onde alterações em tempo real são necessárias.

As montagens de 'data bind' dependem do sistema de arquivos da máquina host para persistir os dados de recursos do emulador Azure Event Hubs nas reinicializações do contêiner. A montagem de vinculação de dados é montada no caminho /path/to/data da máquina host dentro do contentor. Para obter mais informações sobre montagens de ligação de dados, consulte a documentação Docker: Bind mounts.

Configurar o contêiner do emulador de Hubs de Eventos JSON configuração

O contêiner do emulador de Hubs de Eventos é executado com um arquivo config.json padrão. Você pode modificar este arquivo por completo ou atualizar a configuração JSON com uma representação JsonNode da configuração.

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

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithConfigurationFile("./messaging/custom-config.json");
                       });

eventHubs.AddHub("messages");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

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

O código anterior configura o contêiner do emulador de Hubs de Eventos para usar um arquivo de configuração de JSON personalizado localizado em ./messaging/custom-config.json. Isso será montado no caminho /Eventhubs_Emulator/ConfigFiles/Config.json no contêiner, como um arquivo somente leitura. Para substituir propriedades específicas na configuração padrão, chame o método WithConfiguration(IResourceBuilder<AzureEventHubsEmulatorResource>, Action<JsonNode>):

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                       .RunAsEmulator(emulator =>
                       {
                           emulator.WithConfiguration(
                               (JsonNode configuration) =>
                               {
                                   var userConfig = configuration["UserConfig"];
                                   var ns = userConfig["NamespaceConfig"][0];
                                   var firstEntity = ns["Entities"][0];
                                   
                                   firstEntity["PartitionCount"] = 5;
                               });
                       });

eventHubs.AddHub("messages");

builder.AddProject<Projects.ExampleService>()
       .WithReference(eventHubs);

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

O código anterior recupera o nó UserConfig da configuração padrão. Em seguida, atualiza o PartitionCount da primeira entidade para um 5.

Verificações de estado da integração de hospedagem

A integração de hospedagem Azure Event Hubs adiciona automaticamente uma verificação de integridade para o recurso Hubs de Eventos. A verificação de integridade verifica se o Hub de Eventos 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.Azure.Messaging.EventHubs.

Client Integração

Para começar com a integração do cliente .NET AspireAzure Event Hubs, instale o pacote NuGet 📦Aspire.Azure.Messaging.EventHubs no projeto que consome o cliente, ou seja, o projeto correspondente à aplicação que utiliza o cliente do Event Hubs.

dotnet add package Aspire.Azure.Messaging.EventHubs

Tipos de cliente de Hubs de Eventos suportados

Os seguintes clientes do Hub de Eventos são suportados pela biblioteca, juntamente com suas opções e classes de configurações correspondentes:

Azure tipo de cliente Azure classe de opções .NET .NET Aspire classes de configurações
EventHubProducerClient EventHubProducerClientOptions AzureMessagingEventHubsProducerSettings
EventHubBufferedProducerClient EventHubBufferedProducerClientOptions AzureMessagingEventHubsBufferedProducerSettings
EventHubConsumerClient EventHubConsumerClientOptions AzureMessagingEventHubsConsumerSettings
EventProcessorClient EventProcessorClientOptions AzureMessagingEventHubsProcessorSettings
PartitionReceiver PartitionReceiverOptions AzureMessagingEventHubsPartitionReceiverSettings

Os tipos de cliente são do Azure SDK para .NET, assim como as classes de opções correspondentes. As classes de configurações são fornecidas pelo .NET.NET Aspire. As classes de configurações são usadas para configurar as instâncias do cliente.

Adicionar um cliente produtor de Hubs de Eventos

No ficheiro Program.cs do seu projeto cliente-consumidor, chame o método de extensão AddAzureEventHubProducerClient em qualquer IHostApplicationBuilder para registar um EventHubProducerClient para ser utilizado através do contentor de injeção de dependência. O método usa um parâmetro de nome de conexão.

builder.AddAzureEventHubProducerClient(connectionName: "event-hubs");

")

O parâmetro connectionName deve corresponder ao nome usado ao adicionar o recurso Hubs de Eventos no projeto de host do aplicativo. Para obter mais informações, consulte Adicionar um recurso Azure Event Hubs.

Depois de adicionares o EventHubProducerClient, podes recuperar a instância do cliente usando a injeção de dependência. Por exemplo, para recuperar seu objeto de fonte de dados de um serviço de exemplo, defina-o como um parâmetro de construtor e verifique se a classe ExampleService está registrada com o contêiner de injeção de dependência:

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

Para mais informações, consulte:

APIs adicionais a considerar

A integração do cliente fornece APIs adicionais para configurar instâncias do cliente. Quando precisar registrar um cliente de Hubs de Eventos, considere as seguintes APIs:

Azure tipo de cliente API de registo
EventHubProducerClient AddAzureEventHubProducerClient
EventHubBufferedProducerClient AddAzureEventHubBufferedProducerClient
EventHubConsumerClient AddAzureEventHubConsumerClient
EventProcessorClient AddAzureEventProcessorClient
PartitionReceiver AddAzurePartitionReceiverClient

Todas as APIs acima mencionadas incluem parâmetros opcionais para configurar as instâncias do cliente.

Adicionar cliente produtor de Hubs de Eventos com chave

Pode haver situações em que você queira registrar várias instâncias de EventHubProducerClient com nomes de conexão diferentes. Para registrar clientes de Hubs de Eventos com chave, chame o método AddKeyedAzureServiceBusClient:

builder.AddKeyedAzureEventHubProducerClient(name: "messages");
builder.AddKeyedAzureEventHubProducerClient(name: "commands");

Importante

Ao usar serviços com chave, espera-se que seu recurso de Hubs de Eventos tenha configurado dois hubs nomeados, um para o messages e outro para o commands.

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

public class ExampleService(
    [KeyedService("messages")] EventHubProducerClient messagesClient,
    [KeyedService("commands")] EventHubProducerClient commandsClient)
{
    // Use clients...
}

Para obter mais informações, consulte Serviços associados no .NET.

APIs com chave adicionais a serem consideradas

A integração do cliente fornece APIs adicionais para configurar instâncias de cliente com chave. Quando precisar registrar um cliente de Hubs de Eventos com chave, considere as seguintes APIs:

Azure tipo de cliente API de registo
EventHubProducerClient AddKeyedAzureEventHubProducerClient
EventHubBufferedProducerClient AddKeyedAzureEventHubBufferedProducerClient
EventHubConsumerClient AddKeyedAzureEventHubConsumerClient
EventProcessorClient AddKeyedAzureEventProcessorClient
PartitionReceiver AddKeyedAzurePartitionReceiverClient

Todas as APIs acima mencionadas incluem parâmetros opcionais para configurar as instâncias do cliente.

Configuração

A biblioteca de .NET AspireAzure Event Hubs fornece várias opções para configurar a conexão Azure Event Hubs com base nos requisitos e convenções do seu projeto. É necessário fornecer um dos seguintes: FullyQualifiedNamespace ou ConnectionString.

Usar uma string de conexão

Ao usar uma cadeia de conexão da seção de configuração de ConnectionStrings, forneça o nome da cadeia de conexão ao chamar builder.AddAzureEventHubProducerClient() e outros clientes de Hubs de Eventos suportados. Neste exemplo, a cadeia de conexão não inclui a propriedade EntityPath, portanto, a propriedade EventHubName deve ser definida no retorno de chamada de configurações:

builder.AddAzureEventHubProducerClient(
    "event-hubs",
    static settings =>
    {
        settings.EventHubName = "MyHub";
    });

E, em seguida, as informações de conexão serão recuperadas da seção de configuração ConnectionStrings. Dois formatos de conexão são suportados:

Namespace totalmente qualificado (FQN)

A abordagem recomendada é usar um namespace totalmente qualificado, que funciona com a propriedade AzureMessagingEventHubsSettings.Credential para estabelecer uma conexão. Se nenhuma credencial estiver configurada, o DefaultAzureCredential será usado.

{
  "ConnectionStrings": {
    "event-hubs": "{your_namespace}.servicebus.windows.net"
  }
}

Cadeia de conexão

Como alternativa, use uma cadeia de conexão:

{
  "ConnectionStrings": {
    "event-hubs": "Endpoint=sb://mynamespace.servicebus.windows.net/;SharedAccessKeyName=accesskeyname;SharedAccessKey=accesskey;EntityPath=MyHub"
  }
}

Usar provedores de configuração

A biblioteca .NET AspireAzure Event Hubs suporta Microsoft.Extensions.Configuration. Ele carrega o AzureMessagingEventHubsSettings e as opções associadas, por exemplo, EventProcessorClientOptions, da configuração usando o prefixo da chave Aspire:Azure:Messaging:EventHubs:, seguido pelo nome do cliente específico em uso. Por exemplo, considere o appsettings.json que configura algumas das opções para um EventProcessorClient:

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "EventHubs": {
          "EventProcessorClient": {
            "EventHubName": "MyHub",
            "ClientOptions": {
              "Identifier": "PROCESSOR_ID"
            }
          }
        }
      }
    }
  }
}

Você também pode configurar o tipo Options usando o parâmetro Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder opcional do método AddAzureEventProcessorClient. Por exemplo, para definir o ID do cliente do processador para este cliente:

builder.AddAzureEventProcessorClient(
    "event-hubs",
    configureClientBuilder: clientBuilder => clientBuilder.ConfigureOptions(
        options => options.Identifier = "PROCESSOR_ID"));

Observabilidade e telemetria

.NET .NET Aspire integrações configuram automaticamente as definições de Registo, Rastreio e Métricas, 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 do .

Registo

A integração .NET AspireAzure Event Hubs usa as seguintes categorias de log:

  • Azure.Core
  • Azure.Identity

Rastreio

A integração .NET AspireAzure Event Hubs emitirá as seguintes atividades de rastreio utilizando OpenTelemetry:

  • Azure.Messaging.EventHubs.*

Métricas

A integração .NET AspireAzure Event Hubs 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.

Ver também