integração .NET AspireAzure Event Hubs

Artigo
12/15/2024

Neste artigo, você aprenderá a usar a integração .NET AspireAzure Event Hubs. A biblioteca Aspire.Azure.Messaging.EventHubs oferece opções para registrar os seguintes tipos:

Esses tipos são registrados no contêiner de DI para se conectar ao Azure Event Hubs.

Pré-requisitos

Azure assinatura: criar uma gratuitamente.
Azure Event Hubs namespace: para mais informações, veja e adicione um namespace do Event Hubs. 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 .NET AspireAzure Event Hubs, instale o pacote NuGet 📦Aspire.Azure.Messaging.EventHubs no projeto de consumo client, ou seja, o projeto do aplicativo que usa o Azure Event Hubsclient.

.NET CLI
PackageReference

dotnet add package Aspire.Azure.Messaging.EventHubs

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

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

Clientes apoiados com classes de opções

Os seguintes clientes são compatíveis com a biblioteca, juntamente com suas opções e classes de configuração correspondentes:

tipo de AzureClient	Classe Azure Opções	Classe .NET.NET Aspire Configurações
`EventHubProducerClient`	`EventHubProducerClientOptions`	`AzureMessagingEventHubsProducerSettings`
`EventHubBufferedProducerClient`	`EventHubBufferedProducerClientOptions`	`AzureMessagingEventHubsBufferedProducerSettings`
`EventHubConsumerClient`	`EventHubConsumerClientOptions`	`AzureMessagingEventHubsConsumerSettings`
`EventProcessorClient`	`EventProcessorClientOptions`	`AzureMessagingEventHubsProcessorSettings`
`PartitionReceiver`	`PartitionReceiverOptions`	`AzureMessagingEventHubsPartitionReceiverSettings`

O tipo client é do SDK do Azure para .NET, assim também são as classes de opções correspondentes. As classes de configurações são fornecidas pela biblioteca de integração .NET AspireAzure Event Hubs.

Exemplo de uso

O exemplo a seguir pressupõe que você tem um namespace Azure Event Hubs e um Hub de Eventos criado e deseja configurar um EventHubProducerClient para enviar eventos para o Hub de Eventos. Os EventHubBufferedProducerClient, EventHubConsumerClient, EventProcessorCliente PartitionReceiversão configurados de maneira semelhante.

No arquivo Program.cs do seu projeto que consome client, chame a extensão AddAzureEventHubProducerClient para registrar um EventHubProducerClient para uso no contêiner de injeção de dependência.

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

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

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

Para obter mais informações, consulte o Azure. A documentação do Messaging.EventHubs por exemplos sobre como usar o EventHubProducerClient.

Uso do host do aplicativo

Para adicionar Azure suporte de hospedagem do Event Hub ao seu IDistributedApplicationBuilder, instale o 📦Aspire.Hosting.Azure.EventHubs pacote NuGet no projeto de host do aplicativo .

.NET CLI
PackageReference

dotnet add package Aspire.Hosting.Azure.EventHubs

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

No projeto de host do aplicativo, adicione uma conexão dos Hubs de Eventos e um recurso do Hub de Eventos e consuma a conexão usando os seguintes métodos:

var builder = DistributedApplication.CreateBuilder(args);

var eventHubs = builder.AddAzureEventHubs("eventHubsConnectionName")
                       .AddEventHub("MyHub");

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

O método AddAzureEventHubs lerá informações de conexão da configuração do AppHost (por exemplo, de "segredos de usuário") na chave de configuração ConnectionStrings:eventHubsConnectionName. O método WithReference passa essas informações de conexão para uma cadeia de conexão chamada eventHubsConnectionName no projeto ExampleService.

A partir do .NET Aspire 8.1, a extensão Azure EventHubs para .NET Aspire dá suporte ao lançamento de um emulador local para EventHubs. Você pode usar o emulador aplicando o método de extensão RunAsEmulator() da seguinte maneira:

var eventHubs = builder.AddAzureEventHubs("eventHubsConnectionName")
                       .RunAsEmulator()
                       .AddEventHub("MyHub");

O emulador para Azure Event Hubs resulta no lançamento de dois recursos de contêiner dentro de .NET Aspire, derivados do nome do recurso Event Hubs.

Importante

Embora estejamos criando um Hub de Eventos usando o AddEventHub ao mesmo tempo que o namespace, a partir da versão .NET.NET Aspirepreview-5, a cadeia de conexão não incluirá a propriedade EntityPath, portanto, a propriedade EventHubName deve ser configurada no callback de configurações para o clientpreferido. As versões futuras do Aspire incluirão a propriedade EntityPath na cadeia de conexão e não exigirão que a propriedade EventHubName seja definida neste cenário.

No arquivo Program.cs de ExampleService, a conexão pode ser consumida ao usar os métodos de extensão suportados para os Hubs de Eventos client.

builder.AddAzureEventProcessorClient(
    "eventHubsConnectionName",
    static settings =>
    {
        settings.EventHubName = "MyHub";
    });

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 FullyQualifiedNamespace ou um ConnectionString.

Usar uma string de conexão

Ao usar uma cadeia de conexão da seção de configuração ConnectionStrings, forneça o nome da cadeia de conexão ao chamar builder.AddAzureEventHubProducerClient() e outros clientes dos Hubs de Eventos com suporte. 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(
    "eventHubsConnectionName",
    static settings =>
    {
        settings.EventHubName = "MyHub";
    });

E, em seguida, as informações de conexão serão recuperadas da seção de configuração ConnectionStrings. Há suporte para dois formatos de conexão:

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": {
    "eventHubsConnectionName": "{your_namespace}.servicebus.windows.net"
  }
}

Cadeia de conexão

Como alternativa, use uma cadeia de conexão:

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

Usar provedores de configuração

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

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

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

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

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 de Eventos

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

Azure.Core
Azure.Identity

Rastreamento

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

"Azure.Messaging.EventHubs.*"

Métricas

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