Compartir a través de

integración de .NET AspireAzure Event Hubs

  • Artículo

En este artículo, aprenderá a usar la integración de .NET AspireAzure Event Hubs. La biblioteca Aspire.Azure.Messaging.EventHubs ofrece opciones para registrar los siguientes tipos:

Este tipo se registra en el contenedor de inserción de dependencias para conectarse a Azure Event Hubs.

Prerrequisitos

Comenzar

Para comenzar con la integración de .NET AspireAzure Event Hubs, instale el paquete NuGet 📦Aspire.Azure.Messaging.EventHubs en el proyecto que consume client, es decir, el proyecto de la aplicación que utiliza el Azure Event Hubsclient.

dotnet add package Aspire.Azure.Messaging.EventHubs

Para obtener más información, consulte dotnet add package o Administrar dependencias de paquetes en aplicaciones .NET.

Clientes asistidos con clases de opciones

La biblioteca admite los siguientes clientes, junto con sus opciones y clases de configuración correspondientes:

Tipo AzureClient Azure Clase de opciones clase Settings de .NET.NET Aspire
EventHubProducerClient EventHubProducerClientOptions AzureMessagingEventHubsProducerSettings
EventHubBufferedProducerClient EventHubBufferedProducerClientOptions AzureMessagingEventHubsBufferedProducerSettings
EventHubConsumerClient EventHubConsumerClientOptions AzureMessagingEventHubsConsumerSettings
EventProcessorClient EventProcessorClientOptions AzureMessagingEventHubsProcessorSettings
PartitionReceiver PartitionReceiverOptions AzureMessagingEventHubsPartitionReceiverSettings

El tipo client es del SDK Azure para .NET, al igual que las clases de opciones correspondientes. Las clases de configuración son proporcionadas por la biblioteca de integración .NET AspireAzure Event Hubs.

Ejemplo de uso

En el ejemplo siguiente se supone que tiene un espacio de nombres Azure Event Hubs y un centro de eventos creado y desea configurar un EventHubProducerClient para enviar eventos al centro de eventos. Los EventHubBufferedProducerClient, EventHubConsumerClient, EventProcessorClienty PartitionReceiverse configuran de forma similar.

En el archivo Program.cs de tu proyecto que consume client, llama a la extensión AddAzureEventHubProducerClient para registrar un EventHubProducerClient para su uso a través del contenedor de inyección de dependencias.

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

A continuación, puede recuperar la instancia de EventHubProducerClient mediante la inyección de dependencias. Por ejemplo, para recuperar el client de un servicio:

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

Para obtener más información, consulte el Azure. documentación de Messaging.EventHubs para obtener ejemplos sobre el uso de EventHubProducerClient.

Uso del host de la aplicación

Para agregar compatibilidad con el hospedaje de Azure Event Hub a la IDistributedApplicationBuilder, instale el paquete NuGet 📦Aspire.Hosting.Azure.EventHubs en el proyecto de host de la aplicación .

dotnet add package Aspire.Hosting.Azure.EventHubs

En el proyecto host de la aplicación, agregue una conexión de Event Hubs y un recurso de Event Hubs y consuma la conexión mediante los métodos siguientes:

var builder = DistributedApplication.CreateBuilder(args);

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

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

El método AddAzureEventHubs leerá la información de conexión de la configuración del AppHost, específicamente de la clave de configuración ConnectionStrings:eventHubsConnectionName, que podría incluir "secretos de usuario". El método WithReference pasa esa información de conexión a una cadena de conexión denominada eventHubsConnectionName en el proyecto de ExampleService.

A partir de .NET Aspire 8.1, la extensión Azure EventHubs para .NET Aspire admite el inicio de un emulador local para EventHubs. Puede usar el emulador aplicando el método de extensión RunAsEmulator() de la siguiente manera:

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

El emulador de Azure EventHubs da como resultado que se inicien dos recursos de contenedor dentro de .NET Aspire derivados del nombre del recurso de Event Hubs.

Importante

Aunque estamos creando un centro de eventos mediante el AddEventHub al mismo tiempo que el espacio de nombres, a partir de .NET.NET Aspire versión preview-5, la cadena de conexión no incluirá la propiedad EntityPath, por lo que la propiedad EventHubName debe establecerse en la devolución de llamada de configuración de la clientpreferida. Las versiones futuras de Aspire incluirán la propiedad EntityPath en la cadena de conexión y no requerirán que la propiedad EventHubName se establezca en este escenario.

En el archivo Program.cs de ExampleService, se puede establecer la conexión llamando a los métodos de extensión de client admitidos por Event Hubs:

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

Configuración

La biblioteca .NET AspireAzure Event Hubs proporciona varias opciones para configurar la conexión Azure Event Hubs en función de los requisitos y convenciones del proyecto. Es necesario proporcionar FullyQualifiedNamespace o ConnectionString.

Uso de una cadena de conexión

Al usar una cadena de conexión desde la sección de configuración de ConnectionStrings, asegúrese de proporcionar el nombre de la cadena de conexión al llamar a builder.AddAzureEventHubProducerClient() y a otros clientes compatibles de Event Hubs. En este ejemplo, la cadena de conexión no incluye la propiedad EntityPath, por lo que la propiedad EventHubName debe establecerse en la devolución de llamada de configuración:

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

Y, a continuación, se obtendrá la información de conexión de la sección de configuración de ConnectionStrings. Se admiten dos formatos de conexión:

Espacio de nombres completo (FQN)

El enfoque recomendado es usar un espacio de nombres completamente calificado, que funciona con la propiedad AzureMessagingEventHubsSettings.Credential para establecer una conexión. Si no se configura ninguna credencial, se usa el DefaultAzureCredential.

{
  "ConnectionStrings": {
    "eventHubsConnectionName": "{your_namespace}.servicebus.windows.net"
  }
}

Cadena de conexión

Como alternativa, use una cadena de conexión:

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

Uso de proveedores de configuración

La biblioteca de .NET AspireAzure Event Hubs admite Microsoft.Extensions.Configuration. Carga el AzureMessagingEventHubsSettings y las opciones asociadas, por ejemplo, EventProcessorClientOptions, desde la configuración mediante el prefijo de clave Aspire:Azure:Messaging:EventHubs:, seguido del nombre del client específico en uso. Por ejemplo, considere el appsettings.json que configura algunas de las opciones de un EventProcessorClient:

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

También puede configurar el tipo Options mediante el parámetro opcional Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder del método AddAzureEventProcessorClient. Por ejemplo, para establecer el identificador de client del procesador para este client:

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

Observabilidad y telemetría

.NET .NET Aspire integraciones configuran automáticamente las configuraciones de registro, seguimiento y métricas, que a veces se conocen como los pilares de la observabilidad. Para obtener más información sobre la observabilidad de integración y la telemetría, consulte información general sobre las integraciones de .NET.NET Aspire. En función del servicio de respaldo, algunas integraciones solo pueden admitir algunas de estas características. Por ejemplo, algunas integraciones admiten el registro y el seguimiento, pero no las métricas. Las funciones de telemetría también se pueden deshabilitar mediante las técnicas presentadas en la sección Configuración.

Registro

La integración de .NET AspireAzure Event Hubs usa las siguientes categorías de registro:

  • Azure.Core
  • Azure.Identity

Rastreo

La integración de .NET AspireAzure Event Hubs emitirá las siguientes actividades de seguimiento mediante OpenTelemetry:

  • "Azure.Messaging.EventHubs.*"

Métricas

La integración de .NET AspireAzure Event Hubs actualmente no admite métricas de forma predeterminada debido a limitaciones con el SDK de Azure para .NET. Si eso cambia en el futuro, esta sección se actualizará para reflejar esos cambios.

Consulte también