Azure Event Grid SDK für .NET

Azure.Messaging.EventGrid (.NET)

Clientbibliothek zum Veröffentlichen von Ereignissen in Azure Event Grid-Themen, -Domänen und -Namespaces.

Installation

# Für Themen und Domänen (Push-Zustellung)
dotnet add package Azure.Messaging.EventGrid

# Für Namespaces (Pull-Zustellung)
dotnet add package Azure.Messaging.EventGrid.Namespaces

# Für CloudNative CloudEvents-Interop
dotnet add package Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents

Aktuelle Version: 4.28.0 (stabil)

Umgebungsvariablen

EVENT_GRID_TOPIC_ENDPOINT=https://<topic-name>.<region>.eventgrid.azure.net/api/events  # Erforderlich: Endpunkt des Event Grid-Themas oder der Domäne
EVENT_GRID_TOPIC_KEY=<access-key>  # Nur erforderlich bei AzureKeyCredential-Authentifizierung
EVENT_GRID_NAMESPACE_ENDPOINT=https://<namespace>.<region>.eventgrid.azure.net  # Optional: Endpunkt des Event Grid-Namespace
EVENT_GRID_TOPIC_NAME=<topic-name>  # Erforderlich: Name des Event Grid-Themas
EVENT_GRID_SUBSCRIPTION_NAME=<subscription-name>  # Optional: Name des Event Grid-Abonnements
AZURE_TOKEN_CREDENTIALS=prod  # Nur erforderlich, wenn DefaultAzureCredential in der Produktion verwendet wird

Client-Hierarchie

Push-Zustellung (Themen/Domänen)
└── EventGridPublisherClient
    ├── SendEventAsync(EventGridEvent)
    ├── SendEventsAsync(IEnumerable<EventGridEvent>)
    ├── SendEventAsync(CloudEvent)
    └── SendEventsAsync(IEnumerable<CloudEvent>)

Pull-Zustellung (Namespaces)
├── EventGridSenderClient
│   └── SendAsync(CloudEvent)
└── EventGridReceiverClient
    ├── ReceiveAsync()
    ├── AcknowledgeAsync()
    ├── ReleaseAsync()
    └── RejectAsync()

Authentifizierung

API-Schlüssel-Authentifizierung

using Azure;
using Azure.Messaging.EventGrid;

EventGridPublisherClient client = new(
    new Uri("https://mytopic.eastus-1.eventgrid.azure.net/api/events"),
    new AzureKeyCredential("<access-key>"));

Microsoft Entra-Tokenanmeldeinformationen

using Azure.Identity;
using Azure.Messaging.EventGrid;

// Lokale Entwicklung: DefaultAzureCredential. Produktion: Setzen Sie AZURE_TOKEN_CREDENTIALS=prod oder AZURE_TOKEN_CREDENTIALS=<specific_credential>
var credential = new DefaultAzureCredential(
    DefaultAzureCredential.DefaultEnvironmentVariableName
);
// Oder verwenden Sie in der Produktion direkt eine bestimmte Anmeldeinformation:
// Siehe https://learn.microsoft.com/dotnet/api/overview/azure/identity-readme?view=azure-dotnet#credential-classes
// var credential = new ManagedIdentityCredential();
EventGridPublisherClient client = new(
    new Uri("https://mytopic.eastus-1.eventgrid.azure.net/api/events"),
    credential);

SAS-Token-Authentifizierung

string sasToken = EventGridPublisherClient.BuildSharedAccessSignature(
    new Uri(topicEndpoint),
    DateTimeOffset.UtcNow.AddHours(1),
    new AzureKeyCredential(topicKey));

var sasCredential = new AzureSasCredential(sasToken);
EventGridPublisherClient client = new(
    new Uri(topicEndpoint),
    sasCredential);

Veröffentlichen von Ereignissen

EventGridEvent-Schema

EventGridPublisherClient client = new(
    new Uri(topicEndpoint),
    new AzureKeyCredential(topicKey));

// Einzelnes Ereignis
EventGridEvent egEvent = new(
    subject: "orders/12345",
    eventType: "Order.Created",
    dataVersion: "1.0",
    data: new { OrderId = "12345", Amount = 99.99 });

await client.SendEventAsync(egEvent);

// Batch von Ereignissen
List<EventGridEvent> events = new()
{
    new EventGridEvent(
        subject: "orders/12345",
        eventType: "Order.Created",
        dataVersion: "1.0",
        data: new OrderData { OrderId = "12345", Amount = 99.99 }),
    new EventGridEvent(
        subject: "orders/12346",
        eventType: "Order.Created",
        dataVersion: "1.0",
        data: new OrderData { OrderId = "12346", Amount = 149.99 })
};

await client.SendEventsAsync(events);

CloudEvent-Schema

CloudEvent cloudEvent = new(
    source: "/orders/system",
    type: "Order.Created",
    data: new { OrderId = "12345", Amount = 99.99 });

cloudEvent.Subject = "orders/12345";
cloudEvent.Id = Guid.NewGuid().ToString();
cloudEvent.Time = DateTimeOffset.UtcNow;

await client.SendEventAsync(cloudEvent);

// Batch von CloudEvents
List<CloudEvent> cloudEvents = new()
{
    new CloudEvent("/orders", "Order.Created", new { OrderId = "1" }),
    new CloudEvent("/orders", "Order.Updated", new { OrderId = "2" })
};

await client.SendEventsAsync(cloudEvents);

Veröffentlichen in einer Event Grid-Domäne

// Ereignisse müssen die Topic-Eigenschaft für das Domänen-Routing angeben
List<EventGridEvent> events = new()
{
    new EventGridEvent(
        subject: "orders/12345",
        eventType: "Order.Created",
        dataVersion: "1.0",
        data: new { OrderId = "12345" })
    {
        Topic = "orders-topic"  // Name des Domänen-Themas
    },
    new EventGridEvent(
        subject: "inventory/item-1",
        eventType: "Inventory.Updated",
        dataVersion: "1.0",
        data: new { ItemId = "item-1" })
    {
        Topic = "inventory-topic"
    }
};

await client.SendEventsAsync(events);

Benutzerdefinierte Serialisierung

using System.Text.Json;

var serializerOptions = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};

var customSerializer = new JsonObjectSerializer(serializerOptions);

EventGridEvent egEvent = new(
    subject: "orders/12345",
    eventType: "Order.Created",
    dataVersion: "1.0",
    data: customSerializer.Serialize(new OrderData { OrderId = "12345" }));

await client.SendEventAsync(egEvent);

Pull-Zustellung (Namespaces)

Ereignisse an das Namespace-Thema senden

using Azure;
using Azure.Messaging;
using Azure.Messaging.EventGrid.Namespaces;

var senderClient = new EventGridSenderClient(
    new Uri(namespaceEndpoint),
    topicName,
    new AzureKeyCredential(topicKey));

// Einzelnes Ereignis senden
CloudEvent cloudEvent = new("employee_source", "Employee.Created", 
    new { Name = "John", Age = 30 });
await senderClient.SendAsync(cloudEvent);

// Batch senden
await senderClient.SendAsync(new[]
{
    new CloudEvent("source", "type", new { Name = "Alice" }),
    new CloudEvent("source", "type", new { Name = "Bob" })
});

Ereignisse empfangen und verarbeiten

var receiverClient = new EventGridReceiverClient(
    new Uri(namespaceEndpoint),
    topicName,
    subscriptionName,
    new AzureKeyCredential(topicKey));

// Ereignisse empfangen
ReceiveResult result = await receiverClient.ReceiveAsync(maxEvents: 10);

List<string> lockTokensToAck = new();
List<string> lockTokensToRelease = new();

foreach (ReceiveDetails detail in result.Details)
{
    CloudEvent cloudEvent = detail.Event;
    string lockToken = detail.BrokerProperties.LockToken;
    
    try
    {
        // Ereignis verarbeiten
        Console.WriteLine($"Ereignis: {cloudEvent.Type}, Daten: {cloudEvent.Data}");
        lockTokensToAck.Add(lockToken);
    }
    catch (Exception)
    {
        // Für wiederholte Verarbeitung freigeben
        lockTokensToRelease.Add(lockToken);
    }
}

// Erfolgreich verarbeitete Ereignisse bestätigen
if (lockTokensToAck.Any())
{
    await receiverClient.AcknowledgeAsync(lockTokensToAck);
}

// Ereignisse für Wiederholung freigeben
if (lockTokensToRelease.Any())
{
    await receiverClient.ReleaseAsync(lockTokensToRelease);
}

Ereignisse ablehnen (Dead Letter)

// Ereignisse, die nicht verarbeitet werden können, ablehnen
await receiverClient.RejectAsync(new[] { lockToken });

Empfangen von Ereignissen (Azure Functions)

EventGridEvent-Trigger

using Azure.Messaging.EventGrid;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;

public static class EventGridFunction
{
    [FunctionName("ProcessEventGridEvent")]
    public static void Run(
        [EventGridTrigger] EventGridEvent eventGridEvent,
        ILogger log)
    {
        log.LogInformation($"Ereignistyp: {eventGridEvent.EventType}");
        log.LogInformation($"Betreff: {eventGridEvent.Subject}");
        log.LogInformation($"Daten: {eventGridEvent.Data}");
    }
}

CloudEvent-Trigger

using Azure.Messaging;
using Microsoft.Azure.Functions.Worker;

public class CloudEventFunction
{
    [Function("ProcessCloudEvent")]
    public void Run(
        [EventGridTrigger] CloudEvent cloudEvent,
        FunctionContext context)
    {
        var logger = context.GetLogger("ProcessCloudEvent");
        logger.LogInformation($"Ereignistyp: {cloudEvent.Type}");
        logger.LogInformation($"Quelle: {cloudEvent.Source}");
        logger.LogInformation($"Daten: {cloudEvent.Data}");
    }
}

Ereignisse parsen

EventGridEvent parsen

// Aus JSON-String
string json = "..."; // Event Grid-Webhook-Payload
EventGridEvent[] events = EventGridEvent.ParseMany(BinaryData.FromString(json));

foreach (EventGridEvent egEvent in events)
{
    if (egEvent.TryGetSystemEventData(out object systemEvent))
    {
        // Systemereignis verarbeiten
        switch (systemEvent)
        {
            case StorageBlobCreatedEventData blobCreated:
                Console.WriteLine($"Blob erstellt: {blobCreated.Url}");
                break;
        }
    }
    else
    {
        // Benutzerdefiniertes Ereignis verarbeiten
        var customData = egEvent.Data.ToObjectFromJson<MyCustomData>();
    }
}

CloudEvent parsen

CloudEvent[] cloudEvents = CloudEvent.ParseMany(BinaryData.FromString(json));

foreach (CloudEvent cloudEvent in cloudEvents)
{
    var data = cloudEvent.Data.ToObjectFromJson<MyEventData>();
    Console.WriteLine($"Typ: {cloudEvent.Type}, Daten: {data}");
}

Systemereignisse

// Häufige Systemereignistypen
using Azure.Messaging.EventGrid.SystemEvents;

// Speicherereignisse
StorageBlobCreatedEventData blobCreated;
StorageBlobDeletedEventData blobDeleted;

// Ressourcenereignisse
ResourceWriteSuccessEventData resourceCreated;
ResourceDeleteSuccessEventData resourceDeleted;

// App Service-Ereignisse
WebAppUpdatedEventData webAppUpdated;

// Container Registry-Ereignisse
ContainerRegistryImagePushedEventData imagePushed;

// IoT Hub-Ereignisse
IotHubDeviceCreatedEventData deviceCreated;

Referenz der Schlüsseltypen

Typ	Zweck
EventGridPublisherClient	Veröffentlichen in Themen/Domänen
EventGridSenderClient	Senden an Namespace-Themen
EventGridReceiverClient	Empfangen von Namespace-Abonnements
EventGridEvent	Native Event Grid-Schema
CloudEvent	CloudEvents 1.0-Schema
ReceiveResult	Pull-Zustellungsantwort
ReceiveDetails	Ereignis mit Broker-Eigenschaften
BrokerProperties	Sperr-Token, Zustellungsanzahl

Vergleich der Ereignisschemata

Funktion	EventGridEvent	CloudEvent
Standard	Azure-spezifisch	CNCF-Standard
Erforderliche Felder	subject, eventType, dataVersion, data	source, type
Erweiterbarkeit	Eingeschränkt	Erweiterungsattribute
Interoperabilität	Nur Azure	Plattformübergreifend

Bewährte Methoden

1. CloudEvents verwenden – Bevorzugen Sie CloudEvents für neue Implementierungen (Industriestandard)
2. Ereignisse bündeln – Senden Sie mehrere Ereignisse in einem Aufruf für mehr Effizienz
3. Entra ID verwenden – Bevorzugen Sie verwaltete Identitäten gegenüber Zugriffsschlüsseln
4. Idempotente Handler – Ereignisse können mehrfach zugestellt werden
5. Ereignis-TTL festlegen – Konfigurieren Sie die Gültigkeitsdauer für Namespace-Ereignisse
6. Partielle Fehler behandeln – Ereignisse einzeln bestätigen/freigeben
7. Dead-Letter verwenden – Konfigurieren Sie Dead-Letter für fehlgeschlagene Ereignisse
8. Schemata validieren – Validieren Sie Ereignisdaten vor der Verarbeitung

Fehlerbehandlung

using Azure;

try
{
    await client.SendEventAsync(cloudEvent);
}
catch (RequestFailedException ex) when (ex.Status == 401)
{
    Console.WriteLine("Authentifizierung fehlgeschlagen - Anmeldeinformationen prüfen");
}
catch (RequestFailedException ex) when (ex.Status == 403)
{
    Console.WriteLine("Autorisierung fehlgeschlagen - RBAC-Berechtigungen prüfen");
}
catch (RequestFailedException ex) when (ex.Status == 413)
{
    Console.WriteLine("Payload zu groß - max. 1 MB pro Ereignis, 1 MB Gesamt-Batch");
}
catch (RequestFailedException ex)
{
    Console.WriteLine($"Event Grid-Fehler: {ex.Status} - {ex.Message}");
}

Failover-Muster

try
{
    var primaryClient = new EventGridPublisherClient(primaryUri, primaryKey);
    await primaryClient.SendEventsAsync(events);
}
catch (RequestFailedException)
{
    // Failover in die sekundäre Region
    var secondaryClient = new EventGridPublisherClient(secondaryUri, secondaryKey);
    await secondaryClient.SendEventsAsync(events);
}

Verwandte SDKs

SDK	Zweck	Installation
Azure.Messaging.EventGrid	Themen/Domänen (dieses SDK)	dotnet add package Azure.Messaging.EventGrid
Azure.Messaging.EventGrid.Namespaces	Pull-Zustellung	dotnet add package Azure.Messaging.EventGrid.Namespaces
Azure.Identity	Authentifizierung	dotnet add package Azure.Identity
Microsoft.Azure.WebJobs.Extensions.EventGrid	Azure Functions-Trigger	dotnet add package Microsoft.Azure.WebJobs.Extensions.EventGrid

Referenzlinks

Ressource	URL
NuGet-Paket	https://www.nuget.org/packages/Azure.Messaging.EventGrid
API-Referenz	https://learn.microsoft.com/dotnet/api/azure.messaging.eventgrid
Schnellstart	https://learn.microsoft.com/azure/event-grid/custom-event-quickstart
Pull-Zustellung	https://learn.microsoft.com/azure/event-grid/pull-delivery-overview
GitHub-Quelle	https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/eventgrid/Azure.Messaging.EventGrid