Azure Event Hubs SDK Overview

Introduction to Azure Event Hubs SDKs

Azure Event Hubs is a highly scalable data streaming platform and event ingestion service. Our Software Development Kits (SDKs) provide developers with robust, idiomatic interfaces to interact with Event Hubs, enabling efficient creation of event producers and consumers.

These SDKs are designed for performance, reliability, and ease of use, abstracting away complex network protocols and service details. Whether you're building real-time analytics, IoT data processing pipelines, or log aggregation systems, the Event Hubs SDKs are your gateway to unlocking the power of event-driven architectures on Azure.

Key Features of the SDKs

• Event Publishing: Effortlessly send batches of events to Event Hubs with high throughput. The SDKs handle batching, retries, and load balancing.
• Event Consuming: Process events reliably using consumer groups. The SDKs provide mechanisms for checkpointing, load balancing between consumers, and handling event ordering within partitions.
• Partition Management: Gain insights into partition states, request specific partitions for processing, and manage consumer offsets.
• Authentication & Authorization: Securely connect to Event Hubs using Azure Active Directory (now Microsoft Entra ID), Shared Access Signatures (SAS), or managed identities.
• Error Handling & Resilience: Comprehensive error management with configurable retry policies and clear error propagation.
• Asynchronous Operations: Most operations are asynchronous, allowing for non-blocking I/O and improved application responsiveness.
• Protocol Support: Primarily uses the AMQP 1.0 protocol for efficient and reliable communication.

Supported Languages and Platforms

We offer comprehensive SDKs for a variety of popular programming languages, ensuring you can integrate Event Hubs seamlessly into your existing technology stack:

• .NET: Azure.Messaging.EventHubs package. Compatible with .NET Core, .NET Framework, and Mono.
• Java: com.azure:azure-messaging-eventhubs Maven artifact. Works with Java 8 and above.
• Python: azure-eventhubs PyPI package. Compatible with Python 3.7+.
• JavaScript/TypeScript: @azure/event-hubs npm package. For Node.js and browser environments.
• Go: github.com/Azure/azure-sdk-for-go/sdk/messaging/azeventhubs.
• C++: Available via the Azure SDK for C++ project.

Each SDK follows idiomatic patterns for its respective language, making them familiar and easy to learn.

Getting Started with the SDKs

To begin, you'll need an Azure subscription and an Event Hubs namespace. Once set up, follow these general steps:

1. Install the SDK: Use your language's package manager (e.g., NuGet, Maven, pip, npm).
2. Obtain Connection Information: Get your Event Hubs connection string or Microsoft Entra ID credentials.
3. Create a Client: Instantiate the appropriate Event Hubs client (e.g., EventHubProducerClient, EventHubConsumerClient).
4. Send or Receive Events: Use the client's methods to publish events or start listening for incoming events.

For detailed instructions and code examples for your specific language, please refer to the official documentation linked below.

Best Practices for Using Event Hubs SDKs

• Batching: Send events in batches to improve throughput and reduce latency. The SDKs often provide helpers for this.
• Connection Pooling: Reuse client instances and their underlying connections to avoid the overhead of establishing new connections for each operation.
• Error Handling: Implement robust error handling with appropriate retry logic. Understand the different types of transient and permanent errors.
• Checkpointing: For consumers, reliably store and retrieve consumer group offsets (checkpoints) to ensure that processing can resume from the correct position after restarts or failures.
• Partition Affinity: When possible, leverage partition affinity for consumers to improve cache locality and reduce latency, especially for stateful processing.
• Resource Management: Ensure that client objects and their associated resources are properly closed and disposed of when no longer needed.

Code Samples

Here are snippets demonstrating basic usage. Full examples are available in the respective language SDK documentation.

Publishing Events (Conceptual - .NET Example)

C#
using Azure.Messaging.EventHubs;
using System;
using System.Text;
using System.Threading.Tasks;

// Replace with your actual connection string and event hub name
string connectionString = "YOUR_EVENTHUBS_CONNECTION_STRING";
string eventHubName = "YOUR_EVENTHUB_NAME";

await using var producerClient = new EventHubProducerClient(connectionString, eventHubName);

try
{
    using EventDataBatch eventBatch = await producerClient.CreateBatchAsync();

    for (int i = 0; i < 5; i++)
    {
        var eventData = new EventData(Encoding.UTF8.GetBytes($"Event {i}"));
        if (!eventBatch.TryAddMessage(eventData))
        {
            throw new Exception($"Event {i} is too large for the batch.");
        }
    }

    await producerClient.SendAsync(eventBatch);
    Console.WriteLine("Sent a batch of events.");
}
catch (Exception ex)
{
    Console.WriteLine($"Error sending events: {ex.Message}");
}

Receiving Events (Conceptual - Python Example)

Python
import asyncio
from azure.eventhub import EventHubConsumerClient

# Replace with your actual connection string and event hub name
connection_str = "YOUR_EVENTHUBS_CONNECTION_STRING"
event_hub_name = "YOUR_EVENTHUB_NAME"
consumer_group = "$Default"  # Or your specific consumer group

async def receive_events():
    client = EventHubConsumerClient.from_connection_string(
        connection_str, consumer_group=consumer_group, event_hub_name=event_hub_name
    )

    async def on_event(partition_context, event):
        print(f"Received event: {event.body_as_str()} from partition {partition_context.partition_id}")
        # Update checkpoint here if using checkpointing
        await partition_context.update_checkpoint(event)

    async def on_error(partition_context, error):
        print(f"Error in partition {partition_context.partition_id}: {error}")

    async with client:
        await client.receive(on_event, on_error=on_error)

if __name__ == "__main__":
    asyncio.run(receive_events())

Please consult the official SDK documentation for more detailed examples, advanced features, and language-specific nuances.