Aspire Azure Event Hubs integrering

Inkluderar:Värdintegrering ingår Värdintegrering &–& integrering ingår integration

Azure Event Hubs är en intern dataströmningstjänst i molnet som kan strömma miljontals händelser per sekund, med låg svarstid, från valfri källa till valfri destination. Med integreringen AspireAzure Event Hubs kan du ansluta till Azure Event Hubs instanser från dina .NET program.

Integrering av värdtjänster

Värdintegrering AspireAzure Event Hubs modellerar de olika Event Hub-resurserna som följande typer:

• AzureEventHubsResource: Representerar en Azure Event Hubs resurs på toppnivå som används för att representera samlingar av hubbar och anslutningsinformationen till den underliggande Azure resursen.
• AzureEventHubResource: Representerar en enskild resurs för eventhubb.
• AzureEventHubsEmulatorResource: Representerar en Azure Event Hubs emulator som en containerresurs.
• AzureEventHubConsumerGroupResource: Representerar en konsumentgrupp inom en resurs för händelsehubbar.

Om du vill komma åt dessa typer och API:er för att uttrycka dem i ditt AppHost-projekt installerar du 📦Aspire. Hosting.Azure. EventHubs NuGet-paket:

dotnet add package Aspire.Hosting.Azure.EventHubs

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

Mer information finns i dotnet add package eller Hantera paketberoenden i .NET applikationer.

Lägga till en Azure Event Hubs resurs

Om du vill lägga till ett AzureEventHubsResource i ditt AppHost-projekt anropar AddAzureEventHubs du metoden som anger ett namn och anropar AddHubsedan :

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

När du lägger till en Azure Event Hubs resurs i AppHost exponeras andra användbara API:er för att lägga till Event Hub-resurser, konsumentgrupper, uttrycklig explicit etableringskonfiguration och aktivera användning av Azure Event Hubs emulatorn. Föregående kod lägger till en Azure Event Hubs resurs med namnet event-hubs och en händelsehubb med namnet messages till AppHost-projektet. Metoden WithReference skickar anslutningsinformationen till ExampleService-projektet.

Ansluta till ett befintligt Azure Event Hubs namnområde

Du kanske har en befintlig Azure Event Hubs tjänst som du vill ansluta till. Du kan kedja en anropning för att annotera att din AzureEventHubsResource är en befintlig resurs:

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

Mer information om hur du behandlar Azure Event Hubs resurser som befintliga resurser finns i Använda befintliga Azure resurser.

Lägg till händelsehubbens konsumentgrupp

Om du vill lägga till en konsumentgrupp kedjar du ett anrop på en IResourceBuilder<AzureEventHubsResource> till AddConsumerGroup-API:et:

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

När du anropar AddConsumerGroupkonfigureras din messages Event Hub-resurs till att ha en konsumentgrupp med namnet messagesConsumer. Konsumentgruppen skapas i Azure Event Hubs namnrymd som representeras av AzureEventHubsResource som du lade till tidigare. Mer information finns i Azure Event Hubs: Konsumentgrupper.

Lägga till Azure Event Hubs emulatorresurs

Den AspireAzure Event Hubs värdintegrering stöder körning av Event Hubs-resursen som en emulator lokalt, baserat på mcr.microsoft.com/azure-messaging/eventhubs-emulator/latest containeravbildning. Detta är fördelaktigt för situationer där du vill köra Event Hubs-resursen lokalt i utvecklings- och testsyfte, så att du inte behöver etablera en Azure resurs eller ansluta till en befintlig Azure Event Hubs server.

Om du vill köra Event Hubs-resursen som en emulator anropar du metoden 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...

Föregående kod konfigurerar en Azure Event Hubs resurs att köras lokalt i en container. Mer information finns i Azure Event Hubs emulatorn.

Konfigurera Event Hubs-emulatorcontainer

Det finns olika konfigurationer tillgängliga för containerresurser, till exempel kan du konfigurera containerns portar, databindningsmonteringar, datavolymer eller tillhandahålla en wholistisk JSON konfiguration som åsidosätter allt.

Konfigurera Event Hubs-emulatorns värdport för container

Som standard exponerar containern för Event Hubs-emulatorn när den konfigureras av Aspire följande slutpunkter:

Porten som den lyssnar på är dynamisk som standard. När containern startar mappas porten till en slumpmässig port på värddatorn. För att konfigurera slutpunktsporten anropar kedjan containerresursverktyget som tillhandahålls av metoden RunAsEmulator och sedan WithHostPort(IResourceBuilder<AzureEventHubsEmulatorResource>, Nullable<Int32>) enligt följande exempel:

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

Föregående kod konfigurerar Azure Event-emulatorns befintliga emulator slutpunkt för att lyssna på port 7777. Containerporten för Azure-händelseemulatorn mappas till värdporten enligt följande tabell:

Lägga till Event Hubs-emulator med datavolym

Om du vill lägga till en datavolym i Event Hubs-emulatorresursen anropar du metoden WithDataVolume på Event Hubs-emulatorresursen:

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

Datavolymen används för att bevara Event Hubs-emulatordata utanför containerns livscykel. Datavolymen monteras på sökvägen /data i containern. Ett namn genereras slumpmässigt om du inte anger parametern name. Mer information om datavolymer och detaljer om varför de föredras framför bind mountsfinns i Docker dokumentationen: Volymer.

Lägga till Event Hubs-emulatorn med databindningsmontering

Lägg till en bindningsmontering till Event Hubs-emulatorcontainern, länka ett anrop till WithDataBindMount-API:et enligt följande exempel:

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

Databindningsmonteringar förlitar sig på värddatorns filsystem för att bevara Azure Event Hubs-emulatorns resursdata mellan omstarter av containrar. Databindningsmonteringen är monterad på sökvägen /path/to/data på värddatorn i containern. Mer information om databindningspunkter finns i Docker dokumentationen: Bindningspunkter.

Konfigurera konfigurationen för Event Hubs-emulatorcontainer JSON

Event Hubs-emulatorcontainern körs med en standardfil config.json. Du kan åsidosätta den här filen helt eller uppdatera JSON konfigurationen med en JsonNode representation av konfigurationen.

Om du vill ange en anpassad JSON konfigurationsfil anropar du metoden 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...

Föregående kod konfigurerar Event Hubs-emulatorcontainern för att använda en anpassad JSON konfigurationsfil som finns på ./messaging/custom-config.json. Detta kommer att monteras på sökvägen /Eventhubs_Emulator/ConfigFiles/Config.json i containern som en skrivskyddad fil. Om du i stället vill åsidosätta specifika egenskaper i standardkonfigurationen anropar du metoden 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...

Föregående kod hämtar noden UserConfig från standardkonfigurationen. Den uppdaterar sedan den första entitetens PartitionCount till en 5.

Konfigurationsgenererad Bicep

Om du är ny på Bicepär det ett domänspecifikt språk för att definiera Azure-resurser. Med Aspirebehöver du inte skriva Bicep för hand, i stället genererar etablerings-API:erna Bicep åt dig. När du publicerar din app genereras Bicep-filen tillsammans med manifestfilen. När du lägger till en Azure Event Hubs resurs genereras följande 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
  properties: {
    disableLocalAuth: true
  }
  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

Den föregående Bicep är en modul som tillhandahåller en Azure Event Hubs resurs. Dessutom skapas rolltilldelningar för resursen Azure i en separat modul:

@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
}

Den genererade Bicep är en startpunkt och påverkas av ändringar i tillhandahållandeinfrastrukturen i C#. Anpassningar till Bicep-filen skrivs över direkt, så gör ändringar via C#-etablerings-API:erna för att säkerställa att de återspeglas i de genererade filerna.

Anpassa tillhandahållandeinfrastruktur

Alla AspireAzure resurser är underklasser av den AzureProvisioningResource typen. Den här typen möjliggör att den genererade Bicep kan anpassas genom att tillhandahålla ett tydligt API för att konfigurera Azure-resurserna med hjälp av ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API:et. Du kan till exempel konfigurera kind, consistencyPolicy, locationsoch mycket mer. I följande exempel visas hur du anpassar AzureAzure Cosmos DB resursen:

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");
    });

Föregående kod:

• Kedjar ett anrop till ConfigureInfrastructure-API:et:
  • Parametern infra är en instans av den AzureResourceInfrastructure typen.
  • De tillgängliga resurserna hämtas genom att anropa GetProvisionableResources()-metoden.
  • Den enda EventHubsNamespace resursen har hämtats.
  • Egenskapen EventHubsNamespace.Sku tilldelas en ny instans av EventHubsSku med ett Premium namn och nivå samt en Capacity av 7.
  • Egenskapen PublicNetworkAccess tilldelas till SecuredByPerimeter.
  • En tagg läggs till i Event Hubs-resursen med nyckeln ExampleKey och värdet Example value.

Det finns många fler konfigurationsalternativ för att anpassa resursresursen för Event Hubs. Mer information finns i Azure.Provisioning.PostgreSql. För mer information, se anpassningi .

Utför hälsokontroller för integration

Azure Event Hubs värdintegrering lägger automatiskt till en hälsokontroll för Event Hubs-resursen. Hälsokontrollen verifierar att Event Hubs körs och att en anslutning kan upprättas till den.

Värdintegrering förlitar sig på 📦 AspNetCore.HealthChecks.Azure.Messaging.EventHubs NuGet-paket.

Client integration

Kom igång med AspireAzure Event Hubs-klientintegrering genom att installera 📦Aspire.Azure. Messaging.EventHubs NuGet-paket i det klientkrävande projektet, dvs. projektet för programmet som använder Event Hubs-klienten.

dotnet add package Aspire.Azure.Messaging.EventHubs

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

Event Hubs-klienttyper som stöds

Följande Event Hub-klienter stöds av biblioteket, tillsammans med deras motsvarande alternativ och inställningsklasser:

Klienttyperna kommer från Azure SDK för .NET, liksom motsvarande alternativklasser. Inställningsklasserna tillhandahålls av Aspire. Inställningsklasserna används för att konfigurera klientinstanserna.

Lägga till en Event Hubs-producentklient

I Program.cs-filen för ditt klientprojekt anropar du AddAzureEventHubProducerClient-tilläggsmetoden på alla IHostApplicationBuilder för att registrera en EventHubProducerClient för användning via beroendeinjiceringscontainern. Metoden tar en parameter för anslutningsnamn.

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

När du har lagt till EventHubProducerClientkan du hämta klientinstansen med hjälp av beroendeinjektion. Om du till exempel vill hämta datakällobjektet från en exempeltjänst definierar du det som en konstruktorparameter och kontrollerar att klassen ExampleService är registrerad med containern för beroendeinmatning:

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

Mer information finns i:

• Azure. Messaging.EventHubs-dokumentation exempel på användning av EventHubProducerClient.
• Beroendeinjektion i .NET för mer information om beroendeinjektion.

Ytterligare API:er att överväga

Klientintegrering innehåller ytterligare API:er för att konfigurera klientinstanser. När du behöver registrera en Event Hubs-klient bör du överväga följande API:er:

Alla ovan nämnda API:er innehåller valfria parametrar för att konfigurera klientinstanserna.

Lägga till en nyckelad Event Hubs-producentklient

Det kan finnas situationer där du vill registrera flera EventHubProducerClient instanser med olika anslutningsnamn. Om du vill registrera nyckelade Event Hubs-klienter anropar du metoden AddKeyedAzureServiceBusClient:

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

Sedan kan du hämta klientinstanserna med hjälp av dependency injection. Om du till exempel vill hämta klienterna från en tjänst:

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

Mer information finns i Nyckelade tjänster i .NET.

Ytterligare nyckelade API:er att överväga

Klientintegrering innehåller ytterligare API:er för att konfigurera nyckelade klientinstanser. När du behöver registrera en nyckelad Event Hubs-klient bör du överväga följande API:er:

Alla ovan nämnda API:er innehåller valfria parametrar för att konfigurera klientinstanserna.

Konfiguration

Aspire Azure Event Hubs-biblioteket innehåller flera alternativ för att konfigurera Azure Event Hubs-anslutningen baserat på kraven och konventionerna i ditt projekt. Antingen en FullyQualifiedNamespace eller en ConnectionString måste anges.

Använda en anslutningssträng

När du använder en anslutningssträng från ConnectionStrings konfigurationsavsnittet anger du namnet på anslutningssträngen när du anropar builder.AddAzureEventHubProducerClient() och andra Event Hubs-klienter som stöds. I det här exemplet innehåller anslutningssträngen inte egenskapen EntityPath, så egenskapen EventHubName måste anges i inställningsåteranropet:

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

Och sedan hämtas anslutningsinformationen från avsnittet ConnectionStrings konfiguration. Två anslutningsformat stöds:

Fullständigt kvalificerat namnområde (FQN)

Den rekommenderade metoden är att använda ett fullständigt kvalificerat namnområde som fungerar med egenskapen AzureMessagingEventHubsSettings.Credential för att upprätta en anslutning. Om inga autentiseringsuppgifter har konfigurerats används DefaultAzureCredential.

{
  "ConnectionStrings": {
    "event-hubs": "{your_namespace}.servicebus.windows.net"
  }
}

Anslutningssträng

Du kan också använda en anslutningssträng:

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

Använda konfigurationsprovidrar

Aspire Azure Event Hubs-biblioteket stöder Microsoft.Extensions.Configuration. Den läser in AzureMessagingEventHubsSettings och associerade alternativ, t.ex. EventProcessorClientOptions, från konfigurationen med hjälp av Aspire:Azure:Messaging:EventHubs:-nyckelprefixet följt av namnet på den specifika klient som används. Tänk till exempel på appsettings.json som konfigurerar några av alternativen för en EventProcessorClient:

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

Det fullständiga Azure Event Hubs klientintegreringsschemat JSON finns i Aspire.Azure. Messaging.EventHubs/ConfigurationSchema.json.

Använda namngiven konfiguration

Biblioteket AspireAzure Event Hubs stöder namngiven konfiguration, vilket gör att du kan konfigurera flera instanser av samma klienttyp med olika inställningar. Den namngivna konfigurationen använder anslutningsnamnet som en nyckel under det specifika klientkonfigurationsavsnittet.

{
  "Aspire": {
    "Azure": {
      "Messaging": {
        "EventHubs": {
          "EventProcessorClient": {
            "processor1": {
              "EventHubName": "MyHub1",
              "ClientOptions": {
                "Identifier": "PROCESSOR_1"
              }
            },
            "processor2": {
              "EventHubName": "MyHub2",
              "ClientOptions": {
                "Identifier": "PROCESSOR_2"
              }
            }
          }
        }
      }
    }
  }
}

I det här exemplet kan anslutningsnamnen processor1 och processor2 användas när du anropar AddAzureEventProcessorClient:

builder.AddAzureEventProcessorClient("processor1");
builder.AddAzureEventProcessorClient("processor2");

Den namngivna konfigurationen har företräde framför konfigurationen på den översta nivån. Om båda anges åsidosätter inställningarna från den namngivna konfigurationen inställningarna på den översta nivån.

Du kan också konfigurera typ av alternativ med hjälp av den valfria parametern Action<IAzureClientBuilder<EventProcessorClient, EventProcessorClientOptions>> configureClientBuilder för metoden AddAzureEventProcessorClient. Om du till exempel vill ange processorns klient-ID för den här klienten:

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

Observerbarhet och telemetri

Aspire integreringar konfigurerar automatiskt konfigurationer för loggning, spårning och mått, som ibland kallas grundpelarna för observerbarhet. Mer information om integreringsobservabilitet och telemetri finns i Aspire översikten över integreringar. Beroende på säkerhetskopieringstjänsten kanske vissa integreringar bara stöder vissa av dessa funktioner. Vissa integreringar stöder till exempel loggning och spårning, men inte mått. Telemetrifunktioner kan också inaktiveras med hjälp av de tekniker som visas i avsnittet Configuration.

Skogsavverkning

Aspire Azure Event Hubs-integreringen använder följande loggkategorier:

• Azure.Core
• Azure.Identity

Spårning

Aspire Azure Event Hubs-integreringen genererar följande spårningsaktiviteter med hjälp av OpenTelemetry:

• Azure.Messaging.EventHubs.*

Mätvärden

Den AspireAzure Event Hubs integreringen stöder för närvarande inte mått som standard på grund av begränsningar med Azure SDK för .NET. Om detta ändras i framtiden uppdateras det här avsnittet för att återspegla dessa ändringar.

Se även

• Azure Event Hubs
• översikt över AspireAzure integreringar
• Aspire Integrationer
• Aspire GitHub Repo