.NET Aspire Azure Event Hubs integração

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 DI para conexão com Azure Event Hubs.

Pré-requisitos

Azure assinatura: crie uma gratuitamente.
Azure Event Hubs namespace: para obter mais informações, consulte adicionar um namespace de Hubs de Eventos. Como alternativa, você pode usar uma cadeia de conexão, que não é recomendada em ambientes de produção.

Começar

Para começar com a integração .NET AspireAzure Event Hubs, instale o pacote NuGet 📦Aspire.Azure. Messaging.EventHubs no projeto que consome client, ou seja, o projeto para a aplicação que utiliza 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 Manage package dependencies in .NET applications.

Clientes suportados com classes de opções

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

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

O tipo client é do Azure SDK para .NET, tal como 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 utilização

O exemplo a seguir pressupõe que você tenha um namespace Azure Event Hubs e um Hub de Eventos criados e deseje 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 ser utilizado através do contêiner de injeção de dependência.

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

Em seguida, você pode recuperar a instância 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 a documentação do Azure.Messaging.EventHubs para exemplos de como utilizar o EventHubProducerClient.

Utilização do anfitrião da aplicação

Para adicionar Azure suporte de hosting do Hub de Eventos ao seu IDistributedApplicationBuilder, instale o pacote NuGet 📦Aspire.Hosting.Azure.EventHubs no projeto do host da aplicação .

.NET CLI
ReferênciaDePacote

dotnet add package Aspire.Hosting.Azure.EventHubs

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

Em seu projeto de host de aplicativo, adicione uma conexão de Hubs de Eventos e um recurso de 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á as informações de conexão da configuração do AppHost (por exemplo, de "segredos do usuário") sob a 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 oferece suporte à inicialização 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 EventHubs resulta no lançamento de dois recursos de contentor dentro de .NET Aspire, derivados do nome do recurso Event Hubs.

Importante

Embora estejamos a criar 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 definida no retorno de chamada das configurações para o clientpreferencial. 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 nesse cenário.

No arquivo Program.cs do ExampleService, a conexão pode ser consumida chamando os métodos de extensão suportados dos 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 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(
    "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. 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": {
    "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 .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 client 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 de client do processador 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 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.

Partilhar via