Partager via

intégration de .NET AspireAzure Event Hubs

  • Article

Dans cet article, vous allez apprendre à utiliser l’intégration .NET AspireAzure Event Hubs. La bibliothèque Aspire.Azure.Messaging.EventHubs offre des options pour inscrire les types suivants :

Ces types sont inscrits dans le conteneur DI pour connecter à Azure Event Hubs.

Conditions préalables

Démarrer

Pour commencer à utiliser l’intégration .NET AspireAzure Event Hubs, installez le module NuGet 📦Aspire.Azure.Messaging.EventHubs dans le projet utilisant client, autrement dit, le projet pour l’application qui utilise le Azure Event Hubsclient.

dotnet add package Aspire.Azure.Messaging.EventHubs

Pour plus d’informations, consultez dotnet add package ou Gérer les dépendances de package dans les applications .NET.

Assistance aux clients avec des classes d’options

Les clients suivants sont pris en charge par la bibliothèque, ainsi que leurs options et classes de paramètres correspondantes :

type de AzureClient classe Options Azure classe .NET.NET Aspire Settings
EventHubProducerClient EventHubProducerClientOptions AzureMessagingEventHubsProducerSettings
EventHubBufferedProducerClient EventHubBufferedProducerClientOptions AzureMessagingEventHubsBufferedProducerSettings
EventHubConsumerClient EventHubConsumerClientOptions AzureMessagingEventHubsConsumerSettings
EventProcessorClient EventProcessorClientOptions AzureMessagingEventHubsProcessorSettings
PartitionReceiver PartitionReceiverOptions AzureMessagingEventHubsPartitionReceiverSettings

Le type client provient du sdk Azure pour .NET, comme les classes d’options correspondantes. Les classes de paramètres sont fournies par la bibliothèque d’intégration .NET AspireAzure Event Hubs.

Exemple d’utilisation

L’exemple suivant suppose que vous disposez d’un espace de noms Azure Event Hubs et d’un hub d’événements créé et souhaitez configurer un EventHubProducerClient pour envoyer des événements au hub d’événements. Les EventHubBufferedProducerClient, EventHubConsumerClient, EventProcessorClientet PartitionReceiversont configurés de manière similaire.

Dans le fichier Program.cs de votre projet consommant client, appelez l'extension AddAzureEventHubProducerClient pour enregistrer un EventHubProducerClient à utiliser via le conteneur d'injection de dépendances.

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

Vous pouvez ensuite récupérer l’instance EventHubProducerClient à l’aide de l’injection de dépendances. Par exemple, pour récupérer le client à partir d’un service :

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

Pour plus d’informations, consultez la documentation Azure.Messaging.EventHubs pour des exemples sur l’utilisation du EventHubProducerClient.

Utilisation de l’hôte d’application

Pour ajouter la prise en charge de l'hébergement Azure Event Hub à votre IDistributedApplicationBuilder, installez le package NuGet 📦Aspire.Hosting.Azure.EventHubs dans le projet hôte de l'application .

dotnet add package Aspire.Hosting.Azure.EventHubs

Dans votre projet hôte d’application, ajoutez une connexion Event Hubs et une ressource Event Hub et consommez la connexion à l’aide des méthodes suivantes :

var builder = DistributedApplication.CreateBuilder(args);

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

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

La méthode AddAzureEventHubs lira les informations de connexion de la configuration d’AppHost (par exemple, à partir des « secrets utilisateur ») sous la clé de configuration ConnectionStrings:eventHubsConnectionName. La méthode WithReference transmet ces informations de connexion dans une chaîne de connexion nommée eventHubsConnectionName dans le projet ExampleService.

Depuis .NET Aspire 8.1, l’extension Azure EventHubs pour .NET Aspire prend en charge le lancement d’un émulateur local pour EventHubs. Vous pouvez utiliser l’émulateur en appliquant la méthode d’extension RunAsEmulator() comme suit :

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

L’émulateur de Azure EventHubs entraîne le lancement de deux ressources conteneur à l’intérieur .NET Aspire dérivées du nom de la ressource Event Hubs.

Important

Même si nous créons un Event Hub à l’aide de l'AddEventHub en même temps que l’espace de noms, à partir de .NET.NET Aspire version preview-5, la chaîne de connexion n’inclut pas la propriété EntityPath, de sorte que la propriété EventHubName doit être définie dans le rappel des paramètres pour le clientpréféré. Les versions futures de Aspire incluront la propriété EntityPath dans la chaîne de connexion et ne nécessiteront pas que la propriété EventHubName soit définie dans ce scénario.

Dans le fichier Program.cs de ExampleService, la connexion peut être consommée à l’aide de l’appel des méthodes d’extension Event Hubs prises en charge client :

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

Configuration

La bibliothèque .NET AspireAzure Event Hubs fournit plusieurs options pour configurer la connexion Azure Event Hubs en fonction des exigences et des conventions de votre projet. Soit un FullyQualifiedNamespace, soit un ConnectionString est obligatoire.

Utiliser une chaîne de connexion

Lorsque vous utilisez une chaîne de connexion à partir de la section de configuration ConnectionStrings, indiquez le nom de la chaîne de connexion lors de l’appel de builder.AddAzureEventHubProducerClient() et d’autres clients Event Hubs pris en charge. Dans cet exemple, la chaîne de connexion n’inclut pas la propriété EntityPath. Par conséquent, la propriété EventHubName doit être définie dans le rappel des paramètres :

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

Ensuite, les informations de connexion sont récupérées à partir de la section de configuration ConnectionStrings. Deux formats de connexion sont pris en charge :

Espace de noms complet (FQN)

L’approche recommandée consiste à utiliser un espace de noms complet, qui fonctionne avec la propriété AzureMessagingEventHubsSettings.Credential pour établir une connexion. Si aucune information d’identification n’est configurée, la DefaultAzureCredential est utilisée.

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

Chaîne de connexion

Vous pouvez également utiliser une chaîne de connexion :

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

Utiliser des fournisseurs de configuration

La bibliothèque .NET AspireAzure Event Hubs prend en charge Microsoft.Extensions.Configuration. Il charge les AzureMessagingEventHubsSettings ainsi que ses options associées, par exemple EventProcessorClientOptions, depuis la configuration, en utilisant le préfixe de clé Aspire:Azure:Messaging:EventHubs: suivi du nom spécifique de la client utilisée. Par exemple, considérez l'appsettings.json qui configure certaines des options d’un EventProcessorClient:

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

Vous pouvez également configurer le type Options à l’aide du paramètre facultatif Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder de la méthode AddAzureEventProcessorClient. Par exemple, pour définir l’ID de client du processeur pour cette client:

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

Observabilité et télémétrie

.NET .NET Aspire intégrations configurent automatiquement les configurations de journalisation, de suivi et de métriques, parfois appelées les piliers de l’observabilité. Pour plus d’informations sur l’observabilité de l’intégration et la télémétrie, consultez .NET.NET Aspire vue d’ensemble des intégrations. Selon le service de stockage, certaines intégrations peuvent uniquement prendre en charge certaines de ces fonctionnalités. Par exemple, certaines intégrations prennent en charge la journalisation et le suivi, mais pas les métriques. Les fonctionnalités de télémétrie peuvent également être désactivées à l’aide des techniques présentées dans la section Configuration.

Exploitation forestière

L’intégration .NET AspireAzure Event Hubs utilise les catégories de journaux suivantes :

  • Azure.Core
  • Azure.Identity

Traçage

L’intégration .NET AspireAzure Event Hubs émet les activités de suivi suivantes à l’aide de OpenTelemetry:

  • "Azure.Messaging.EventHubs.*"

Métriques

L’intégration .NET AspireAzure Event Hubs ne prend actuellement pas en charge les métriques par défaut en raison de limitations avec le SDK Azure pour .NET. Si ces modifications seront apportées à l’avenir, cette section sera mise à jour pour refléter ces modifications.

Voir aussi