Azure Eventgrid Dotnet

作者 microsoft354361d83247MIT收錄於 2026年10月8日更新於 2026年10月8日

Azure Event Grid SDK for .NET. Client library for publishing and consuming events with Azure Event Grid. Use for event-driven architectures, pub/sub messaging, CloudEvents, and EventGridEvents. Triggers: "Event Grid", "EventGridPublisherClient", "CloudEvent", "EventGridEvent", "publish events .NET", "event-driven", "pub/sub".

AI 產生的概覽

使用 Azure Event Grid .NET SDK 發佈、接收與解析事件的參考指南。

功能
此技能提供 Azure.Messaging.EventGrid 用戶端程式庫的 .NET 程式碼範例與指引。內容涵蓋驗證方式、將 EventGridEvent 與 CloudEvent 承載發佈至主題、網域與命名空間、含確認、釋放與拒絕操作的提取傳遞,以及解析傳入事件。亦記錄 Azure Functions 觸發程序、系統事件類型、錯誤處理與容錯移轉模式。
適用情境
適用於建置發佈或取用 Azure Event Grid 事件的事件驅動 .NET 應用程式。適合涉及 CloudEvents、EventGridEvent、發佈/訂閱訊息或 Event Grid 命名空間提取傳遞的工作。
執行需求
需要 .NET SDK 以及 NuGet 套件 Azure.Messaging.EventGrid,可選 Azure.Messaging.EventGrid.Namespaces、Azure.Identity 與 Microsoft.Azure.WebJobs.Extensions.EventGrid。需要 Event Grid 主題、網域或命名空間端點,以及存取金鑰、SAS 權杖或 Microsoft Entra 認證。不包含指令碼,僅為說明文件。

Azure.Messaging.EventGrid (.NET)

Client library for publishing events to Azure Event Grid topics, domains, and namespaces.

Installation

bash
# For topics and domains (push delivery)dotnet add package Azure.Messaging.EventGrid
# For namespaces (pull delivery)dotnet add package Azure.Messaging.EventGrid.Namespaces
# For CloudNative CloudEvents interopdotnet add package Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents

Current Version: 4.28.0 (stable)

Environment Variables

bash
EVENT_GRID_TOPIC_ENDPOINT=https://<topic-name>.<region>.eventgrid.azure.net/api/events  # Required: Event Grid topic or domain endpointEVENT_GRID_TOPIC_KEY=<access-key>  # Only required for AzureKeyCredential authEVENT_GRID_NAMESPACE_ENDPOINT=https://<namespace>.<region>.eventgrid.azure.net  # Optional: Event Grid namespace endpointEVENT_GRID_TOPIC_NAME=<topic-name>  # Required: Event Grid topic nameEVENT_GRID_SUBSCRIPTION_NAME=<subscription-name>  # Optional: Event Grid subscription nameAZURE_TOKEN_CREDENTIALS=prod  # Required only if DefaultAzureCredential is used in production

Client Hierarchy

Push Delivery (Topics/Domains)└── EventGridPublisherClient    ├── SendEventAsync(EventGridEvent)    ├── SendEventsAsync(IEnumerable<EventGridEvent>)    ├── SendEventAsync(CloudEvent)    └── SendEventsAsync(IEnumerable<CloudEvent>)
Pull Delivery (Namespaces)├── EventGridSenderClient│   └── SendAsync(CloudEvent)└── EventGridReceiverClient    ├── ReceiveAsync()    ├── AcknowledgeAsync()    ├── ReleaseAsync()    └── RejectAsync()

Authentication

API Key Authentication

csharp
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 Token Credential

csharp
using Azure.Identity;using Azure.Messaging.EventGrid;
// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>var credential = new DefaultAzureCredential(    DefaultAzureCredential.DefaultEnvironmentVariableName);// Or use a specific credential directly in production:// See 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 Authentication

csharp
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);

Publishing Events

EventGridEvent Schema

csharp
EventGridPublisherClient client = new(    new Uri(topicEndpoint),    new AzureKeyCredential(topicKey));
// Single eventEventGridEvent egEvent = new(    subject: "orders/12345",    eventType: "Order.Created",    dataVersion: "1.0",    data: new { OrderId = "12345", Amount = 99.99 });
await client.SendEventAsync(egEvent);
// Batch of eventsList<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

csharp
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 of CloudEventsList<CloudEvent> cloudEvents = new(){    new CloudEvent("/orders", "Order.Created", new { OrderId = "1" }),    new CloudEvent("/orders", "Order.Updated", new { OrderId = "2" })};
await client.SendEventsAsync(cloudEvents);

Publishing to Event Grid Domain

csharp
// Events must specify the Topic property for domain routingList<EventGridEvent> events = new(){    new EventGridEvent(        subject: "orders/12345",        eventType: "Order.Created",        dataVersion: "1.0",        data: new { OrderId = "12345" })    {        Topic = "orders-topic"  // Domain topic name    },    new EventGridEvent(        subject: "inventory/item-1",        eventType: "Inventory.Updated",        dataVersion: "1.0",        data: new { ItemId = "item-1" })    {        Topic = "inventory-topic"    }};
await client.SendEventsAsync(events);

Custom Serialization

csharp
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 Delivery (Namespaces)

Send Events to Namespace Topic

csharp
using Azure;using Azure.Messaging;using Azure.Messaging.EventGrid.Namespaces;
var senderClient = new EventGridSenderClient(    new Uri(namespaceEndpoint),    topicName,    new AzureKeyCredential(topicKey));
// Send single eventCloudEvent cloudEvent = new("employee_source", "Employee.Created",     new { Name = "John", Age = 30 });await senderClient.SendAsync(cloudEvent);
// Send batchawait senderClient.SendAsync(new[]{    new CloudEvent("source", "type", new { Name = "Alice" }),    new CloudEvent("source", "type", new { Name = "Bob" })});

Receive and Process Events

csharp
var receiverClient = new EventGridReceiverClient(    new Uri(namespaceEndpoint),    topicName,    subscriptionName,    new AzureKeyCredential(topicKey));
// Receive eventsReceiveResult 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    {        // Process the event        Console.WriteLine($"Event: {cloudEvent.Type}, Data: {cloudEvent.Data}");        lockTokensToAck.Add(lockToken);    }    catch (Exception)    {        // Release for retry        lockTokensToRelease.Add(lockToken);    }}
// Acknowledge successfully processed eventsif (lockTokensToAck.Any()){    await receiverClient.AcknowledgeAsync(lockTokensToAck);}
// Release events for retryif (lockTokensToRelease.Any()){    await receiverClient.ReleaseAsync(lockTokensToRelease);}

Reject Events (Dead Letter)

csharp
// Reject events that cannot be processedawait receiverClient.RejectAsync(new[] { lockToken });

Consuming Events (Azure Functions)

EventGridEvent Trigger

csharp
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($"Event Type: {eventGridEvent.EventType}");        log.LogInformation($"Subject: {eventGridEvent.Subject}");        log.LogInformation($"Data: {eventGridEvent.Data}");    }}

CloudEvent Trigger

csharp
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($"Event Type: {cloudEvent.Type}");        logger.LogInformation($"Source: {cloudEvent.Source}");        logger.LogInformation($"Data: {cloudEvent.Data}");    }}

Parsing Events

Parse EventGridEvent

csharp
// From JSON stringstring json = "..."; // Event Grid webhook payloadEventGridEvent[] events = EventGridEvent.ParseMany(BinaryData.FromString(json));
foreach (EventGridEvent egEvent in events){    if (egEvent.TryGetSystemEventData(out object systemEvent))    {        // Handle system event        switch (systemEvent)        {            case StorageBlobCreatedEventData blobCreated:                Console.WriteLine($"Blob created: {blobCreated.Url}");                break;        }    }    else    {        // Handle custom event        var customData = egEvent.Data.ToObjectFromJson<MyCustomData>();    }}

Parse CloudEvent

csharp
CloudEvent[] cloudEvents = CloudEvent.ParseMany(BinaryData.FromString(json));
foreach (CloudEvent cloudEvent in cloudEvents){    var data = cloudEvent.Data.ToObjectFromJson<MyEventData>();    Console.WriteLine($"Type: {cloudEvent.Type}, Data: {data}");}

System Events

csharp
// Common system event typesusing Azure.Messaging.EventGrid.SystemEvents;
// Storage eventsStorageBlobCreatedEventData blobCreated;StorageBlobDeletedEventData blobDeleted;
// Resource eventsResourceWriteSuccessEventData resourceCreated;ResourceDeleteSuccessEventData resourceDeleted;
// App Service eventsWebAppUpdatedEventData webAppUpdated;
// Container Registry eventsContainerRegistryImagePushedEventData imagePushed;
// IoT Hub eventsIotHubDeviceCreatedEventData deviceCreated;

Key Types Reference

TypePurpose
EventGridPublisherClientPublish to topics/domains
EventGridSenderClientSend to namespace topics
EventGridReceiverClientReceive from namespace subscriptions
EventGridEventEvent Grid native schema
CloudEventCloudEvents 1.0 schema
ReceiveResultPull delivery response
ReceiveDetailsEvent with broker properties
BrokerPropertiesLock token, delivery count

Event Schemas Comparison

FeatureEventGridEventCloudEvent
StandardAzure-specificCNCF standard
Required fieldssubject, eventType, dataVersion, datasource, type
ExtensibilityLimitedExtension attributes
InteroperabilityAzure onlyCross-platform

Best Practices

  1. Use CloudEvents — Prefer CloudEvents for new implementations (industry standard)
  2. Batch events — Send multiple events in one call for efficiency
  3. Use Entra ID — Prefer managed identity over access keys
  4. Idempotent handlers — Events may be delivered more than once
  5. Set event TTL — Configure time-to-live for namespace events
  6. Handle partial failures — Acknowledge/release events individually
  7. Use dead-letter — Configure dead-letter for failed events
  8. Validate schemas — Validate event data before processing

Error Handling

csharp
using Azure;
try{    await client.SendEventAsync(cloudEvent);}catch (RequestFailedException ex) when (ex.Status == 401){    Console.WriteLine("Authentication failed - check credentials");}catch (RequestFailedException ex) when (ex.Status == 403){    Console.WriteLine("Authorization failed - check RBAC permissions");}catch (RequestFailedException ex) when (ex.Status == 413){    Console.WriteLine("Payload too large - max 1MB per event, 1MB total batch");}catch (RequestFailedException ex){    Console.WriteLine($"Event Grid error: {ex.Status} - {ex.Message}");}

Failover Pattern

csharp
try{    var primaryClient = new EventGridPublisherClient(primaryUri, primaryKey);    await primaryClient.SendEventsAsync(events);}catch (RequestFailedException){    // Failover to secondary region    var secondaryClient = new EventGridPublisherClient(secondaryUri, secondaryKey);    await secondaryClient.SendEventsAsync(events);}

Related SDKs

SDKPurposeInstall
Azure.Messaging.EventGridTopics/Domains (this SDK)dotnet add package Azure.Messaging.EventGrid
Azure.Messaging.EventGrid.NamespacesPull deliverydotnet add package Azure.Messaging.EventGrid.Namespaces
Azure.IdentityAuthenticationdotnet add package Azure.Identity
Microsoft.Azure.WebJobs.Extensions.EventGridAzure Functions triggerdotnet add package Microsoft.Azure.WebJobs.Extensions.EventGrid

Reference Links

來源與署名

來源:microsoft/skills位於.github/plugins/azure-sdk-dotnet/skills/azure-eventgrid-dotnet提交354361d

授權條款: MIT

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架