1# Azure Event Hubs SDK — .NET (C#)
2 
3Package: `Azure.Messaging.EventHubs` | [README](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/eventhub/Azure.Messaging.EventHubs/) | [Full Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/eventhub/Azure.Messaging.EventHubs/TROUBLESHOOTING.md)
4 
5## Common Errors
6 
7| Exception | Reason | Fix |
8|-----------|--------|-----|
9| `EventHubsException` (ServiceTimeout) | Service didn't respond in time | Transient — retried automatically. Verify state if persists |
10| `EventHubsException` (QuotaExceeded) | Too many active readers per consumer group | Reduce concurrent receivers or upgrade tier |
11| `EventHubsException` (ConsumerDisconnected) | Higher priority consumer took ownership | Expected during load balancing; check if scaling |
12| `EventHubsException` (MessageSizeExceeded) | Event too large | Reduce event payload; unlikely in practice since the client caps at the service link limit |
13| `UnauthorizedAccessException` | Bad credentials | Verify connection string, SAS token, or RBAC roles |
14 
15## Exception Filtering
16 
17```csharp
18try { /* receive events */ }
19catch (EventHubsException ex) when (ex.Reason == EventHubsException.FailureReason.ConsumerDisconnected)
20{
21    // Handle consumer disconnection
22}
23```
24 
25## Retry Configuration
26 
27Configure via `EventHubsRetryOptions` when creating the client. See [Configuring retry thresholds sample](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/eventhub/Azure.Messaging.EventHubs/samples).
28 
29## Key Issues
30 
31- **Socket exhaustion**: Treat clients as singletons. Share `EventHubConnection` across clients if needed. Always call `CloseAsync` or `DisposeAsync`.
32- **HTTP 412/409 from storage**: Normal during checkpoint store operations — not an error.
33- **Partitions closing frequently**: Expected when scaling. If persists >5 min without scaling, investigate. See [Troubleshooting Guide](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/eventhub/Azure.Messaging.EventHubs/TROUBLESHOOTING.md) for detailed diagnostics.
34- **High CPU**: Limit to 1.5–3 partitions per CPU core and test at scale thoroughly if above that threshold.
35- **Azure Functions**: After upgrading to v5.0+ extensions, update binding types. Reduce logging noise by filtering `Azure.Messaging.EventHubs` to Warning.
36- **WebSockets**: Use `EventHubsTransportType.AmqpWebSockets` to connect over port 443 when AMQP ports (5761, 5762) are blocked.
37 
38## Checkpointing (BlobCheckpointStore)
39 
40Package: `Azure.Messaging.EventHubs.Processor` (includes `EventProcessorClient` + blob checkpoint store)
41 
42> **Auth:** `DefaultAzureCredential` is for local development. See [auth-best-practices.md](auth-best-practices.md) for production patterns.
43 
44```csharp
45var credential = new DefaultAzureCredential();
46 
47var storageClient = new BlobContainerClient(
48    new Uri("https://<storage-account>.blob.core.windows.net/<checkpoint-container>"),
49    credential);
50 
51var processor = new EventProcessorClient(
52    storageClient,
53    "$Default",
54    "<your-namespace>.servicebus.windows.net",
55    "<your-eventhub>",
56    credential);
57 
58processor.ProcessEventAsync += async (args) =>
59{
60    // process event
61    await args.UpdateCheckpointAsync();
62};
63```
64 
65**Common issues:**
66- **Soft delete / blob versioning**: Disable both on the storage account — they cause delays during load balancing.
67- **HTTP 412/409 from storage**: Normal during partition ownership negotiation; not an error.
68- **Checkpoint frequency**: Call `UpdateCheckpointAsync()` per batch, not per event, to reduce storage calls.
69