Udostępnij za pośrednictwem

integracja .NET AspireAzure Event Hubs

  • Artykuł

Z tego artykułu dowiesz się, jak korzystać z integracji .NET AspireAzure Event Hubs. Biblioteka Aspire.Azure.Messaging.EventHubs oferuje opcje rejestrowania następujących typów:

Ten typ jest zarejestrowany w kontenerze DI na potrzeby nawiązywania połączenia z usługą Azure Event Hubs.

Warunki wstępne

Zaczynaj

Aby rozpocząć pracę z integracją .NET AspireAzure Event Hubs, zainstaluj pakiet NuGet 📦Aspire.Azure. Messaging.EventHubs w projekcie, który korzysta z client, czyli w projekcie przeznaczonym dla aplikacji korzystającej z Azure Event Hubsclient.

dotnet add package Aspire.Azure.Messaging.EventHubs

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzanie zależnościami pakietów w aplikacjach .NET.

Obsługiwani klienci z klasami opcji

Następujący klienci są obsługiwani przez bibliotekę wraz z odpowiednimi opcjami i klasami ustawień:

typ AzureClient Azure Klasa opcji .NET .NET Aspire Klasa ustawień
EventHubProducerClient EventHubProducerClientOptions AzureMessagingEventHubsProducerSettings
EventHubBufferedProducerClient EventHubBufferedProducerClientOptions AzureMessagingEventHubsBufferedProducerSettings
EventHubConsumerClient EventHubConsumerClientOptions AzureMessagingEventHubsConsumerSettings
EventProcessorClient EventProcessorClientOptions AzureMessagingEventHubsProcessorSettings
PartitionReceiver PartitionReceiverOptions AzureMessagingEventHubsPartitionReceiverSettings

Typ client pochodzi z zestawu SDK Azure dla .NET, podobnie jak odpowiednie klasy opcji. Klasy ustawień są udostępniane przez bibliotekę integracji .NET AspireAzure Event Hubs.

Przykładowe użycie

W poniższym przykładzie przyjęto założenie, że masz przestrzeń nazw Azure Event Hubs i utworzone centrum zdarzeń, i chcesz skonfigurować EventHubProducerClient do wysyłania zdarzeń do centrum zdarzeń. EventHubBufferedProducerClient, EventHubConsumerClient, EventProcessorClienti PartitionReceiversą konfigurowane w podobny sposób.

W pliku Program.cs projektu używającego clientwywołaj rozszerzenie AddAzureEventHubProducerClient, aby zarejestrować EventHubProducerClient do użycia za pośrednictwem kontenera wstrzykiwania zależności.

builder.AddAzureEventHubProducerClient("eventHubsConnectionName");

Następnie można pobrać wystąpienie EventHubProducerClient przy użyciu wstrzykiwania zależności. Aby na przykład pobrać client z usługi:

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

Aby uzyskać więcej informacji, zobacz dokumentację AzureMessaging.EventHubs, aby uzyskać przykłady dotyczące korzystania z EventHubProducerClient.

Użycie hosta aplikacji

Aby dodać obsługę hostingu centrum zdarzeń Azure do IDistributedApplicationBuilder, zainstaluj pakiet NuGet 📦Aspire.Hosting.Azure.EventHubs w projekcie hosta aplikacji .

dotnet add package Aspire.Hosting.Azure.EventHubs

W projekcie hosta aplikacji dodaj połączenie z Event Hubs oraz zasób Event Hub i skorzystaj z połączenia, stosując następujące metody:

var builder = DistributedApplication.CreateBuilder(args);

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

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

Metoda AddAzureEventHubs odczytuje informacje o połączeniu z konfiguracji hosta AppHost (na przykład z "wpisów tajnych użytkownika") w kluczu konfiguracji ConnectionStrings:eventHubsConnectionName. Metoda WithReference przekazuje te informacje o połączeniu do ciągu połączenia o nazwie eventHubsConnectionName w projekcie ExampleService.

Od wersji .NET Aspire 8.1 rozszerzenie Azure EventHubs dla .NET Aspire obsługuje uruchamianie lokalnego emulatora dla usługi EventHubs. Emulator można użyć, stosując metodę rozszerzenia RunAsEmulator() w następujący sposób:

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

Emulator Azure EventHubs powoduje uruchomienie dwóch zasobów kontenera wewnątrz .NET Aspire pochodnych od nazwy zasobu usługi Event Hubs.

Ważny

Mimo że tworzymy centrum zdarzeń przy użyciu AddEventHub w tym samym czasie co przestrzeń nazw, od wersji .NET.NET Aspirepreview-5, parametry połączenia nie będą zawierać właściwości EntityPath, więc należy ustawić właściwość EventHubName w wywołaniu zwrotnym ustawień dla preferowanego client. Przyszłe wersje Aspire będą zawierać właściwość EntityPath w parametrach połączenia i nie będą wymagać ustawienia właściwości EventHubName w tym scenariuszu.

W pliku Program.csExampleServicepołączenie można wykorzystać, poprzez wywołanie obsługiwanych metod rozszerzenia Event Hubs client.

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

Konfiguracja

Biblioteka .NET AspireAzure Event Hubs udostępnia wiele opcji konfigurowania połączenia Azure Event Hubs na podstawie wymagań i konwencji projektu. Wymagane jest dostarczenie FullyQualifiedNamespace lub ConnectionString.

Używanie parametrów połączenia

W przypadku używania parametrów połączenia z sekcji konfiguracji ConnectionStrings podaj nazwę parametrów połączenia podczas wywoływania builder.AddAzureEventHubProducerClient() i innych obsługiwanych klientów usługi Event Hubs. W tym przykładzie parametry połączenia nie zawierają właściwości EntityPath, więc właściwość EventHubName musi być ustawiona w wywołaniu zwrotnym ustawień:

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

Następnie informacje o połączeniu zostaną pobrane z sekcji konfiguracji ConnectionStrings. Obsługiwane są dwa formaty połączeń:

Pełna kwalifikowana przestrzeń nazw (FQN)

Zalecaną metodą jest użycie w pełni kwalifikowanej przestrzeni nazw, która współpracuje z właściwością AzureMessagingEventHubsSettings.Credential w celu nawiązania połączenia. Jeśli nie skonfigurowano poświadczeń, zostanie użyta DefaultAzureCredential.

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

Ciąg połączenia

Alternatywnie użyj parametrów połączenia:

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

Korzystanie z dostawców konfiguracji

Biblioteka .NET AspireAzure Event Hubs obsługuje Microsoft.Extensions.Configuration. Ładuje AzureMessagingEventHubsSettings i skojarzone opcje, np. EventProcessorClientOptions, z konfiguracji przy użyciu prefiksu klucza Aspire:Azure:Messaging:EventHubs:, a następnie nazwy określonego client używanego. Rozważmy na przykład appsettings.json, która konfiguruje niektóre opcje dla EventProcessorClient:

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

Typ opcji można również skonfigurować przy użyciu opcjonalnego parametru Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder metody AddAzureEventProcessorClient. Aby na przykład ustawić identyfikator client procesora dla tego client:

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

Obserwowanie i telemetria

.NET .NET Aspire integracje automatycznie ustawiają konfiguracje do rejestrowania, śledzenia i metryk, które są czasami nazywane filarami obserwowalności. Aby uzyskać więcej informacji na temat możliwości obserwacji integracji i telemetrii, zobacz omówienie integracji .NET.NET Aspire. W zależności od usługi pomocniczej niektóre integracje mogą obsługiwać tylko niektóre z tych funkcji. Na przykład niektóre integracje obsługują rejestrowanie i śledzenie, ale nie metryki. Funkcje telemetrii można również wyłączyć przy użyciu technik przedstawionych w sekcji konfiguracji .

Rejestrowanie

Integracja .NET AspireAzure Event Hubs używa następujących kategorii dzienników:

  • Azure.Core
  • Azure.Identity

Śledzenie

Integracja .NET AspireAzure Event Hubs spowoduje emitowanie następujących działań śledzenia przy użyciu OpenTelemetry:

  • "Azure.Messaging.EventHubs.*"

Metryki

Integracja .NET AspireAzure Event Hubs obecnie nie obsługuje metryk domyślnie ze względu na ograniczenia SDK Azure dla .NET. Jeśli ta zmiana nastąpi w przyszłości, ta sekcja zostanie zaktualizowana, aby odzwierciedlić te zmiany.

Zobacz też