Azure Eventgrid Dotnet

1---
2name: azure-eventgrid-dotnet
3description: |
4  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".
5package: Azure.Messaging.EventGrid
6---
7 
8# Azure.Messaging.EventGrid (.NET)
9 
10Client library for publishing events to Azure Event Grid topics, domains, and namespaces.
11 
12## Installation
13 
14```bash
15# For topics and domains (push delivery)
16dotnet add package Azure.Messaging.EventGrid
17 
18# For namespaces (pull delivery)
19dotnet add package Azure.Messaging.EventGrid.Namespaces
20 
21# For CloudNative CloudEvents interop
22dotnet add package Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents
23```
24 
25**Current Version**: 4.28.0 (stable)
26 
27## Environment Variables
28 
29```bash
30# Topic/Domain endpoint
31EVENT_GRID_TOPIC_ENDPOINT=https://<topic-name>.<region>.eventgrid.azure.net/api/events
32EVENT_GRID_TOPIC_KEY=<access-key>
33 
34# Namespace endpoint (for pull delivery)
35EVENT_GRID_NAMESPACE_ENDPOINT=https://<namespace>.<region>.eventgrid.azure.net
36EVENT_GRID_TOPIC_NAME=<topic-name>
37EVENT_GRID_SUBSCRIPTION_NAME=<subscription-name>
38```
39 
40## Client Hierarchy
41 
42```
43Push Delivery (Topics/Domains)
44└── EventGridPublisherClient
45    ├── SendEventAsync(EventGridEvent)
46    ├── SendEventsAsync(IEnumerable<EventGridEvent>)
47    ├── SendEventAsync(CloudEvent)
48    └── SendEventsAsync(IEnumerable<CloudEvent>)
49 
50Pull Delivery (Namespaces)
51├── EventGridSenderClient
52│   └── SendAsync(CloudEvent)
53└── EventGridReceiverClient
54    ├── ReceiveAsync()
55    ├── AcknowledgeAsync()
56    ├── ReleaseAsync()
57    └── RejectAsync()
58```
59 
60## Authentication
61 
62### API Key Authentication
63 
64```csharp
65using Azure;
66using Azure.Messaging.EventGrid;
67 
68EventGridPublisherClient client = new(
69    new Uri("https://mytopic.eastus-1.eventgrid.azure.net/api/events"),
70    new AzureKeyCredential("<access-key>"));
71```
72 
73### Microsoft Entra ID (Recommended)
74 
75```csharp
76using Azure.Identity;
77using Azure.Messaging.EventGrid;
78 
79EventGridPublisherClient client = new(
80    new Uri("https://mytopic.eastus-1.eventgrid.azure.net/api/events"),
81    new DefaultAzureCredential());
82```
83 
84### SAS Token Authentication
85 
86```csharp
87string sasToken = EventGridPublisherClient.BuildSharedAccessSignature(
88    new Uri(topicEndpoint),
89    DateTimeOffset.UtcNow.AddHours(1),
90    new AzureKeyCredential(topicKey));
91 
92var sasCredential = new AzureSasCredential(sasToken);
93EventGridPublisherClient client = new(
94    new Uri(topicEndpoint),
95    sasCredential);
96```
97 
98## Publishing Events
99 
100### EventGridEvent Schema
101 
102```csharp
103EventGridPublisherClient client = new(
104    new Uri(topicEndpoint),
105    new AzureKeyCredential(topicKey));
106 
107// Single event
108EventGridEvent egEvent = new(
109    subject: "orders/12345",
110    eventType: "Order.Created",
111    dataVersion: "1.0",
112    data: new { OrderId = "12345", Amount = 99.99 });
113 
114await client.SendEventAsync(egEvent);
115 
116// Batch of events
117List<EventGridEvent> events = new()
118{
119    new EventGridEvent(
120        subject: "orders/12345",
121        eventType: "Order.Created",
122        dataVersion: "1.0",
123        data: new OrderData { OrderId = "12345", Amount = 99.99 }),
124    new EventGridEvent(
125        subject: "orders/12346",
126        eventType: "Order.Created",
127        dataVersion: "1.0",
128        data: new OrderData { OrderId = "12346", Amount = 149.99 })
129};
130 
131await client.SendEventsAsync(events);
132```
133 
134### CloudEvent Schema
135 
136```csharp
137CloudEvent cloudEvent = new(
138    source: "/orders/system",
139    type: "Order.Created",
140    data: new { OrderId = "12345", Amount = 99.99 });
141 
142cloudEvent.Subject = "orders/12345";
143cloudEvent.Id = Guid.NewGuid().ToString();
144cloudEvent.Time = DateTimeOffset.UtcNow;
145 
146await client.SendEventAsync(cloudEvent);
147 
148// Batch of CloudEvents
149List<CloudEvent> cloudEvents = new()
150{
151    new CloudEvent("/orders", "Order.Created", new { OrderId = "1" }),
152    new CloudEvent("/orders", "Order.Updated", new { OrderId = "2" })
153};
154 
155await client.SendEventsAsync(cloudEvents);
156```
157 
158### Publishing to Event Grid Domain
159 
160```csharp
161// Events must specify the Topic property for domain routing
162List<EventGridEvent> events = new()
163{
164    new EventGridEvent(
165        subject: "orders/12345",
166        eventType: "Order.Created",
167        dataVersion: "1.0",
168        data: new { OrderId = "12345" })
169    {
170        Topic = "orders-topic"  // Domain topic name
171    },
172    new EventGridEvent(
173        subject: "inventory/item-1",
174        eventType: "Inventory.Updated",
175        dataVersion: "1.0",
176        data: new { ItemId = "item-1" })
177    {
178        Topic = "inventory-topic"
179    }
180};
181 
182await client.SendEventsAsync(events);
183```
184 
185### Custom Serialization
186 
187```csharp
188using System.Text.Json;
189 
190var serializerOptions = new JsonSerializerOptions
191{
192    PropertyNamingPolicy = JsonNamingPolicy.CamelCase
193};
194 
195var customSerializer = new JsonObjectSerializer(serializerOptions);
196 
197EventGridEvent egEvent = new(
198    subject: "orders/12345",
199    eventType: "Order.Created",
200    dataVersion: "1.0",
201    data: customSerializer.Serialize(new OrderData { OrderId = "12345" }));
202 
203await client.SendEventAsync(egEvent);
204```
205 
206## Pull Delivery (Namespaces)
207 
208### Send Events to Namespace Topic
209 
210```csharp
211using Azure;
212using Azure.Messaging;
213using Azure.Messaging.EventGrid.Namespaces;
214 
215var senderClient = new EventGridSenderClient(
216    new Uri(namespaceEndpoint),
217    topicName,
218    new AzureKeyCredential(topicKey));
219 
220// Send single event
221CloudEvent cloudEvent = new("employee_source", "Employee.Created", 
222    new { Name = "John", Age = 30 });
223await senderClient.SendAsync(cloudEvent);
224 
225// Send batch
226await senderClient.SendAsync(new[]
227{
228    new CloudEvent("source", "type", new { Name = "Alice" }),
229    new CloudEvent("source", "type", new { Name = "Bob" })
230});
231```
232 
233### Receive and Process Events
234 
235```csharp
236var receiverClient = new EventGridReceiverClient(
237    new Uri(namespaceEndpoint),
238    topicName,
239    subscriptionName,
240    new AzureKeyCredential(topicKey));
241 
242// Receive events
243ReceiveResult result = await receiverClient.ReceiveAsync(maxEvents: 10);
244 
245List<string> lockTokensToAck = new();
246List<string> lockTokensToRelease = new();
247 
248foreach (ReceiveDetails detail in result.Details)
249{
250    CloudEvent cloudEvent = detail.Event;
251    string lockToken = detail.BrokerProperties.LockToken;
252    
253    try
254    {
255        // Process the event
256        Console.WriteLine($"Event: {cloudEvent.Type}, Data: {cloudEvent.Data}");
257        lockTokensToAck.Add(lockToken);
258    }
259    catch (Exception)
260    {
261        // Release for retry
262        lockTokensToRelease.Add(lockToken);
263    }
264}
265 
266// Acknowledge successfully processed events
267if (lockTokensToAck.Any())
268{
269    await receiverClient.AcknowledgeAsync(lockTokensToAck);
270}
271 
272// Release events for retry
273if (lockTokensToRelease.Any())
274{
275    await receiverClient.ReleaseAsync(lockTokensToRelease);
276}
277```
278 
279### Reject Events (Dead Letter)
280 
281```csharp
282// Reject events that cannot be processed
283await receiverClient.RejectAsync(new[] { lockToken });
284```
285 
286## Consuming Events (Azure Functions)
287 
288### EventGridEvent Trigger
289 
290```csharp
291using Azure.Messaging.EventGrid;
292using Microsoft.Azure.WebJobs;
293using Microsoft.Azure.WebJobs.Extensions.EventGrid;
294 
295public static class EventGridFunction
296{
297    [FunctionName("ProcessEventGridEvent")]
298    public static void Run(
299        [EventGridTrigger] EventGridEvent eventGridEvent,
300        ILogger log)
301    {
302        log.LogInformation($"Event Type: {eventGridEvent.EventType}");
303        log.LogInformation($"Subject: {eventGridEvent.Subject}");
304        log.LogInformation($"Data: {eventGridEvent.Data}");
305    }
306}
307```
308 
309### CloudEvent Trigger
310 
311```csharp
312using Azure.Messaging;
313using Microsoft.Azure.Functions.Worker;
314 
315public class CloudEventFunction
316{
317    [Function("ProcessCloudEvent")]
318    public void Run(
319        [EventGridTrigger] CloudEvent cloudEvent,
320        FunctionContext context)
321    {
322        var logger = context.GetLogger("ProcessCloudEvent");
323        logger.LogInformation($"Event Type: {cloudEvent.Type}");
324        logger.LogInformation($"Source: {cloudEvent.Source}");
325        logger.LogInformation($"Data: {cloudEvent.Data}");
326    }
327}
328```
329 
330## Parsing Events
331 
332### Parse EventGridEvent
333 
334```csharp
335// From JSON string
336string json = "..."; // Event Grid webhook payload
337EventGridEvent[] events = EventGridEvent.ParseMany(BinaryData.FromString(json));
338 
339foreach (EventGridEvent egEvent in events)
340{
341    if (egEvent.TryGetSystemEventData(out object systemEvent))
342    {
343        // Handle system event
344        switch (systemEvent)
345        {
346            case StorageBlobCreatedEventData blobCreated:
347                Console.WriteLine($"Blob created: {blobCreated.Url}");
348                break;
349        }
350    }
351    else
352    {
353        // Handle custom event
354        var customData = egEvent.Data.ToObjectFromJson<MyCustomData>();
355    }
356}
357```
358 
359### Parse CloudEvent
360 
361```csharp
362CloudEvent[] cloudEvents = CloudEvent.ParseMany(BinaryData.FromString(json));
363 
364foreach (CloudEvent cloudEvent in cloudEvents)
365{
366    var data = cloudEvent.Data.ToObjectFromJson<MyEventData>();
367    Console.WriteLine($"Type: {cloudEvent.Type}, Data: {data}");
368}
369```
370 
371## System Events
372 
373```csharp
374// Common system event types
375using Azure.Messaging.EventGrid.SystemEvents;
376 
377// Storage events
378StorageBlobCreatedEventData blobCreated;
379StorageBlobDeletedEventData blobDeleted;
380 
381// Resource events
382ResourceWriteSuccessEventData resourceCreated;
383ResourceDeleteSuccessEventData resourceDeleted;
384 
385// App Service events
386WebAppUpdatedEventData webAppUpdated;
387 
388// Container Registry events
389ContainerRegistryImagePushedEventData imagePushed;
390 
391// IoT Hub events
392IotHubDeviceCreatedEventData deviceCreated;
393```
394 
395## Key Types Reference
396 
397| Type | Purpose |
398|------|---------|
399| `EventGridPublisherClient` | Publish to topics/domains |
400| `EventGridSenderClient` | Send to namespace topics |
401| `EventGridReceiverClient` | Receive from namespace subscriptions |
402| `EventGridEvent` | Event Grid native schema |
403| `CloudEvent` | CloudEvents 1.0 schema |
404| `ReceiveResult` | Pull delivery response |
405| `ReceiveDetails` | Event with broker properties |
406| `BrokerProperties` | Lock token, delivery count |
407 
408## Event Schemas Comparison
409 
410| Feature | EventGridEvent | CloudEvent |
411|---------|----------------|------------|
412| Standard | Azure-specific | CNCF standard |
413| Required fields | subject, eventType, dataVersion, data | source, type |
414| Extensibility | Limited | Extension attributes |
415| Interoperability | Azure only | Cross-platform |
416 
417## Best Practices
418 
4191. **Use CloudEvents** — Prefer CloudEvents for new implementations (industry standard)
4202. **Batch events** — Send multiple events in one call for efficiency
4213. **Use Entra ID** — Prefer managed identity over access keys
4224. **Idempotent handlers** — Events may be delivered more than once
4235. **Set event TTL** — Configure time-to-live for namespace events
4246. **Handle partial failures** — Acknowledge/release events individually
4257. **Use dead-letter** — Configure dead-letter for failed events
4268. **Validate schemas** — Validate event data before processing
427 
428## Error Handling
429 
430```csharp
431using Azure;
432 
433try
434{
435    await client.SendEventAsync(cloudEvent);
436}
437catch (RequestFailedException ex) when (ex.Status == 401)
438{
439    Console.WriteLine("Authentication failed - check credentials");
440}
441catch (RequestFailedException ex) when (ex.Status == 403)
442{
443    Console.WriteLine("Authorization failed - check RBAC permissions");
444}
445catch (RequestFailedException ex) when (ex.Status == 413)
446{
447    Console.WriteLine("Payload too large - max 1MB per event, 1MB total batch");
448}
449catch (RequestFailedException ex)
450{
451    Console.WriteLine($"Event Grid error: {ex.Status} - {ex.Message}");
452}
453```
454 
455## Failover Pattern
456 
457```csharp
458try
459{
460    var primaryClient = new EventGridPublisherClient(primaryUri, primaryKey);
461    await primaryClient.SendEventsAsync(events);
462}
463catch (RequestFailedException)
464{
465    // Failover to secondary region
466    var secondaryClient = new EventGridPublisherClient(secondaryUri, secondaryKey);
467    await secondaryClient.SendEventsAsync(events);
468}
469```
470 
471## Related SDKs
472 
473| SDK | Purpose | Install |
474|-----|---------|---------|
475| `Azure.Messaging.EventGrid` | Topics/Domains (this SDK) | `dotnet add package Azure.Messaging.EventGrid` |
476| `Azure.Messaging.EventGrid.Namespaces` | Pull delivery | `dotnet add package Azure.Messaging.EventGrid.Namespaces` |
477| `Azure.Identity` | Authentication | `dotnet add package Azure.Identity` |
478| `Microsoft.Azure.WebJobs.Extensions.EventGrid` | Azure Functions trigger | `dotnet add package Microsoft.Azure.WebJobs.Extensions.EventGrid` |
479 
480## Reference Links
481 
482| Resource | URL |
483|----------|-----|
484| NuGet Package | https://www.nuget.org/packages/Azure.Messaging.EventGrid |
485| API Reference | https://learn.microsoft.com/dotnet/api/azure.messaging.eventgrid |
486| Quickstart | https://learn.microsoft.com/azure/event-grid/custom-event-quickstart |
487| Pull Delivery | https://learn.microsoft.com/azure/event-grid/pull-delivery-overview |
488| GitHub Source | https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/eventgrid/Azure.Messaging.EventGrid |
489