integración .NET AspireAzure Event Hubs

Incluye: Integración de alojamiento —&— Client integración

Azure Event Hubs es un servicio nativo de streaming de datos en la nube que puede transmitir millones de eventos por segundo, con baja latencia, desde cualquier origen a cualquier destino. La integración de .NET AspireAzure Event Hubs permite conectarse a instancias de Azure Event Hubs desde las aplicaciones de .NET.

Integración de hospedaje

Los modelos de integración de hosting del .NET.NET AspireAzure Event Hubs modelan los distintos recursos de Event Hub como los siguientes tipos:

• AzureEventHubsResource: representa un recurso de Azure Event Hubs de nivel superior, que se usa para representar colecciones de concentradores y la información de conexión al recurso de Azure subyacente.
• AzureEventHubResource: representa un único recurso del centro de eventos.
• AzureEventHubsEmulatorResource: representa un emulador de Azure Event Hubs como un recurso de contenedor.
• AzureEventHubConsumerGroupResource: representa un grupo de consumidores dentro de un recurso del centro de eventos.

Para acceder a estos tipos y a las API para expresarlos dentro de su proyecto app host, instale el paquete 📦Aspire.Hosting.Azure.EventHubs NuGet:

dotnet add package Aspire.Hosting.Azure.EventHubs

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

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

Añade un recurso Azure Event Hubs

Para agregar un AzureEventHubsResource al proyecto host de la aplicación, llame al método AddAzureEventHubs proporcionando un nombre y, a continuación, llame a 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...

Al agregar un recurso de Azure Event Hubs al host de la aplicación, expone otras API útiles para agregar recursos de Event Hub, grupos de consumidores, y permite la configuración de aprovisionamiento explícita, así como el uso del emulador de Azure Event Hubs. El código anterior agrega un recurso de Azure Event Hubs denominado event-hubs y un centro de eventos denominado messages al proyecto host de la aplicación. El método WithReference pasa la información de conexión al proyecto de ExampleService.

Bicep generado por el aprovisionamiento

Si no conoce Bicep, es un lenguaje específico de dominio para definir recursos Azure. Con .NET.NET Aspire, no es necesario escribir Bicep manualmente, sino que las API de aprovisionamiento generan Bicep automáticamente. Al publicar la aplicación, el Bicep generado se muestra junto con el archivo de manifiesto. Cuando añades un recurso Azure Event Hubs, se genera el siguiente Bicep:

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

param sku string = 'Standard'

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 messages 'Microsoft.EventHub/namespaces/eventhubs@2024-01-01' = {
  name: 'messages'
  parent: event_hubs
}

output eventHubsEndpoint string = event_hubs.properties.serviceBusEndpoint

output name string = event_hubs.name

El módulo Bicep anterior proporciona un recurso Azure Event Hubs. Además, las asignaciones de roles se crean para el Azure recurso en un módulo independiente:

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

param event_hubs_outputs_name string

param principalType string

param principalId string

resource event_hubs 'Microsoft.EventHub/namespaces@2024-01-01' existing = {
  name: event_hubs_outputs_name
}

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
}

El Bicep generado es un punto de partida y se ve influido por los cambios en la infraestructura de aprovisionamiento en C#. Las personalizaciones realizadas directamente en el archivo Bicep se sobrescribirán, por lo que los cambios deben realizarse a través de las API de aprovisionamiento de C# para garantizar que se reflejen en los archivos generados.

Personalización de la infraestructura de aprovisionamiento

Todos los recursos .NET AspireAzure son subclases del tipo AzureProvisioningResource. Este tipo permite la personalización del Bicep generado proporcionando una API fluida para configurar los recursos Azure mediante la API ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>). Por ejemplo, puede configurar el kind, consistencyPolicy, locations, etc. En el ejemplo siguiente se muestra cómo personalizar el recurso de 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");
    });

El código anterior:

• Encadena una llamada a la API ConfigureInfrastructure:
  • El parámetro infra es una instancia del tipo AzureResourceInfrastructure.
  • Los recursos aprovisionables se recuperan llamando al método GetProvisionableResources().
  • Se recupera el único recurso EventHubsNamespace.
  • La propiedad EventHubsNamespace.Sku se asigna a una nueva instancia de EventHubsSku con un nombre y un nivel de Premium, y un Capacity de 7.
  • La propiedad PublicNetworkAccess está asignada a SecuredByPerimeter.
  • Se agrega una etiqueta al recurso de Event Hubs con una clave de ExampleKey y un valor de Example value.

Hay muchas más opciones de configuración disponibles para personalizar el recurso de recursos de Event Hubs. Para obtener más información, consulte Azure.Provisioning.PostgreSql. Para obtener más información, vea Azure.Provisioning personalización.

Conectar a un espacio de nombres Azure Event Hubs existente

Es posible que tenga un servicio existente Azure Event Hubs al que quiera conectarse. Puede encadenar una llamada para anotar que su AzureEventHubsResource es un recurso existente:

var builder = DistributedApplication.CreateBuilder(args);

var existingEventHubsName = builder.AddParameter("existingEventHubsName");
var existingEventHubsResourceGroup = builder.AddParameter("existingEventHubsResourceGroup");

var eventHubs = builder.AddAzureEventHubs("event-hubs")
                    .AsExisting(existingEventHubsName, existingEventHubsResourceGroup);

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

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

Para obtener más información sobre cómo tratar Azure Event Hubs los recursos como recursos existentes, consulte Uso de recursos existentesAzure.

Adición de un grupo de consumidores del centro de eventos

Para añadir un grupo de consumidores, encadena una llamada en un IResourceBuilder<AzureEventHubsResource> a la 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...

Al llamar a AddConsumerGroup, configura el recurso del centro de eventos de messages para que tenga un grupo de consumidores denominado messagesConsumer. El grupo de consumidores se crea en el espacio de nombres Azure Event Hubs que está representado por el AzureEventHubsResource que añadiste anteriormente. Para obtener más información, vea Azure Event Hubs: Grupos de consumidores.

Adición de un recurso del emulador de Azure Event Hubs

La integración de hospedaje .NET AspireAzure Event Hubs admite la ejecución del recurso Event Hubs como un emulador de forma local, basado en la imagen de contenedor mcr.microsoft.com/azure-messaging/eventhubs-emulator/latest. Esto es beneficioso para situaciones en las que desea ejecutar el recurso de Event Hubs localmente con fines de desarrollo y pruebas, evitando la necesidad de aprovisionar un recurso de Azure o conectarse a un servidor de Azure Event Hubs existente.

Para ejecutar el recurso de Event Hubs como emulador, llame al 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...

El código anterior configura un recurso de Azure Event Hubs para que se ejecute localmente en un contenedor. Para obtener más información, vea Azure Event Hubs Emulator.

Configuración del contenedor del emulador de Event Hubs

Hay varias configuraciones disponibles para los recursos de contenedor, por ejemplo, puede configurar los puertos del contenedor, los montajes de vinculación de datos, los volúmenes de datos, o bien proporcionar una configuración holística de JSON que anula todo.

Configuración del puerto de host del contenedor del emulador de Event Hubs

De forma predeterminada, el contenedor del emulador de Event Hubs cuando se configura mediante .NET.NET Aspire, expone los siguientes puntos de conexión:

El puerto en el que está escuchando es dinámico de forma predeterminada. Cuando se inicia el contenedor, el puerto se asigna a un puerto aleatorio en el equipo host. Para configurar el puerto de punto de conexión, encadene llamadas en el generador de recursos de contenedor proporcionado por el método RunAsEmulator y, a continuación, el WithHostPort(IResourceBuilder<AzureEventHubsEmulatorResource>, Nullable<Int32>) como se muestra en el ejemplo siguiente:

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

El código anterior configura el punto de conexión Azure del contenedor del emulador de eventos emulator para que escuche en el puerto 7777. El puerto del contenedor del emulador de eventos de Azure se asigna al puerto host, como se muestra en la tabla siguiente:

Añadir emulador Event Hubs con volumen de datos

Para agregar un volumen de datos al recurso del emulador de Event Hubs, llame al método WithDataVolume en el recurso del emulador de Event Hubs:

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

El volumen de datos se usa para conservar los datos del emulador de Event Hubs fuera del ciclo de vida de su contenedor. El volumen de datos se monta en la ruta /data del contenedor. Un nombre se genera de forma aleatoria a menos que proporcione un conjunto del parámetro name. Para obtener más información sobre los volúmenes de datos y detalles sobre por qué se prefieren sobre montajes de enlace, consulte Docker docs: Volúmenes.

Agregar el emulador de Event Hubs con montaje de datos vinculado

Para añadir un montaje bind al contenedor del emulador Event Hubs, encadena una llamada a la API WithDataBindMount, como se muestra en el siguiente ejemplo:

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

Los montajes bind de datos se basan en el sistema de archivos de la máquina host para persistir los datos de los recursos del emulador Azure Event Hubs a través de los reinicios del contenedor. El montaje de enlace de datos se monta en la ruta /path/to/data en la máquina host en el contenedor. Para obtener más información sobre los montajes de enlace de datos, consulte la documentación Docker: Montajes de enlace.

Configurar la configuración del contenedor del emulador de Event Hubs JSON

El contenedor del emulador de Event Hubs se ejecuta con un archivo config.json predeterminado. Puede anular este archivo por completo o actualizar la configuración JSON con una representación JsonNode de la configuración.

Para proporcionar un archivo de configuración de JSON personalizado, llame al 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...

El código anterior configura el contenedor del emulador de Event Hubs para usar un archivo de configuración de JSON personalizado ubicado en ./messaging/custom-config.json. Esto se montará en la ruta /Eventhubs_Emulator/ConfigFiles/Config.json del contenedor, y estará disponible como un archivo de solo lectura. Para invalidar propiedades específicas en la configuración predeterminada, llame al 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...

El código anterior recupera el nodo UserConfig de la configuración predeterminada. A continuación, actualiza el PartitionCount de la primera entidad a un 5.

Comprobaciones de estado de la integración de hospedaje

La integración Azure Event Hubs de hospedaje agrega automáticamente una comprobación de estado para el recurso de Event Hubs. La comprobación de estado comprueba que Event Hubs se está ejecutando y que se puede establecer una conexión a él.

La integración de hospedaje depende de los paquetes NuGet 📦 AspNetCore.HealthChecks.Azure.Messaging.EventHubs.

Integración con Client

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

dotnet add package Aspire.Azure.Messaging.EventHubs

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

Tipos de cliente de Event Hubs admitidos

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

Los tipos de cliente proceden del SDK de Azure para .NET, así como las clases correspondientes de opciones. Las clases de configuración son proporcionadas por el .NET.NET Aspire. Las clases de configuración se usan para configurar las instancias de cliente.

Adición de un cliente de productor de Event Hubs

En el archivo Program.cs del proyecto que consume el cliente, llame al método de extensión AddAzureEventHubProducerClient en cualquier IHostApplicationBuilder para registrar un EventHubProducerClient para su uso a través del contenedor de inyección de dependencias. El método toma un parámetro de nombre de conexión.

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

Después de añadir el EventHubProducerClient, puede recuperar la instancia del cliente utilizando la inyección de dependencias. Por ejemplo, para recuperar el objeto de origen de datos de un servicio de ejemplo, definalo como parámetro de constructor y asegúrese de que la clase ExampleService esté registrada con el contenedor de inserción de dependencias:

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

Para obtener más información, consulte:

• Azure. Documentación de Messaging.EventHubs para ejemplos de uso de la EventHubProducerClient.
• Inyección de dependencias en .NET para más detalles sobre la inyección de dependencias.

API adicionales que se deben tener en cuenta

La integración de cliente proporciona API adicionales para configurar instancias de cliente. Cuando necesite registrar un cliente de Event Hubs, tenga en cuenta las siguientes API:

Todas las API mencionadas anteriormente incluyen parámetros opcionales para configurar las instancias de cliente.

Adicionar cliente productor de Event Hubs con claves

Puede haber situaciones en las que quiera registrar varias instancias de EventHubProducerClient con nombres de conexión diferentes. Para registrar clientes de Event Hubs con claves, llame al método AddKeyedAzureServiceBusClient:

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

Luego puede recuperar las instancias del cliente usando inyección de dependencias. Por ejemplo, para recuperar los clientes de un servicio:

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

Se requiere que se proporcione un o un .NET.

API con clave adicionales que se deben tener en cuenta

La integración de cliente proporciona API adicionales para configurar instancias de cliente con claves. Cuando necesite registrar un cliente de Event Hubs con clave, tenga en cuenta las siguientes API:

Todas las API mencionadas anteriormente incluyen parámetros opcionales para configurar las instancias de cliente.

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 un FullyQualifiedNamespace o un 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(
    "event-hubs",
    static settings =>
    {
        settings.EventHubName = "MyHub";
    });

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

Fully Qualified Namespace (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": {
    "event-hubs": "{your_namespace}.servicebus.windows.net"
  }
}

Cadena de conexión

Como alternativa, use una cadena de conexión:

{
  "ConnectionStrings": {
    "event-hubs": "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 cliente 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"
            }
          }
        }
      }
    }
  }
}

Para obtener el esquema completo de integración Azure Event Hubs de cliente JSON, consulte Aspire.Azure.Messaging.EventHubs/ConfigurationSchema.json.

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 cliente del procesador para este cliente:

builder.AddAzureEventProcessorClient(
    "event-hubs",
    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

Seguimiento

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

• Azure Event Hubs
• resumen de las integraciones de .NET AspireAzure
• .NET.NET Aspire integraciones
• .NET Aspire GitHub repositorio