Akka.Streams.Azure.EventHub
1.5.74
Prefix Reserved
dotnet add package Akka.Streams.Azure.EventHub --version 1.5.74
NuGet\Install-Package Akka.Streams.Azure.EventHub -Version 1.5.74
<PackageReference Include="Akka.Streams.Azure.EventHub" Version="1.5.74" />
<PackageVersion Include="Akka.Streams.Azure.EventHub" Version="1.5.74" />
<PackageReference Include="Akka.Streams.Azure.EventHub" />
paket add Akka.Streams.Azure.EventHub --version 1.5.74
#r "nuget: Akka.Streams.Azure.EventHub, 1.5.74"
#:package Akka.Streams.Azure.EventHub@1.5.74
#addin nuget:?package=Akka.Streams.Azure.EventHub&version=1.5.74
#tool nuget:?package=Akka.Streams.Azure.EventHub&version=1.5.74
Akka.Streams.Azure.EventHub
Azure Event Hubs sources and a sink for Akka.NET Streams, using Azure.Messaging.EventHubs.Processor. The package targets .NET Standard 2.0 and .NET 6. It is the current Akka.Streams.Azure.EventHub package; older instructions to install the interim .V5 package no longer apply.
dotnet add package Akka.Streams.Azure.EventHub
You need an Event Hubs namespace, an event hub, send/receive credentials and a consumer group. Sources also need an existing Azure Blob container for partition ownership and checkpoints. Provision these separately. See the Azure SDK processor documentation for authentication and processor configuration.
Publish grouped events
EventHubSink.Create(producer) accepts IEnumerable<EventData> elements and materializes a Task. It sends each group in SDK batches and completes the task after upstream completion and the final send. Its EventHubProducerClient is borrowed: the caller must keep it alive until the task finishes and dispose it afterwards.
This complete example reads an Event Hubs connection string from EVENTHUB_CONNECTION_STRING. The hub name is orders.
using Akka.Actor;
using Akka.Streams;
using Akka.Streams.Azure.EventHub;
using Akka.Streams.Dsl;
using Azure.Messaging.EventHubs;
using Azure.Messaging.EventHubs.Producer;
var system = ActorSystem.Create("eventhub-publisher");
try
{
await using var producer = new EventHubProducerClient(
Environment.GetEnvironmentVariable("EVENTHUB_CONNECTION_STRING")
?? throw new InvalidOperationException("Set EVENTHUB_CONNECTION_STRING."), "orders");
await Source.From(new[] { "first", "second", "third" })
.Select(value => new EventData(value))
.Grouped(10)
.RunWith(EventHubSink.Create(producer), system.Materializer());
}
finally { await system.Terminate(); }
The sink uses the producer's default partition routing. It does not offer a partition-selection option or an exactly-once delivery guarantee. Keep each event within the service's maximum event size. SDK batching and retries, stream buffers and the sink's pending-send list still apply.
Consume and checkpoint
EventHubSource.Create(factory) emits ProcessContext and materializes the factory's EventProcessorClient. Return a new processor on each factory call; the stage installs the processor's event handlers and starts it. Do not share that processor between materializations or attach competing SDK handlers.
A context exposes Data, HasEvent, Partition, CancellationToken and UpdateCheckpointAsync(). Empty SDK receive callbacks can have HasEvent == false and Data == null; do not checkpoint those. Checkpoint explicitly after successful application processing. Emitting a context releases the SDK callback; it does not mean downstream processing or checkpointing has completed. The SDK prefetches, and the stage and stream can buffer contexts. Cross-partition ordering and exactly-once processing are not guaranteed; make effects safe to repeat.
This complete example runs for 30 seconds. Set EVENTHUB_CONNECTION_STRING and BLOB_CONNECTION_STRING; create an orders-consumer group and a checkpoints Blob container first. Its kill switch cancels the source; it does not drain in-flight application work. Shutdown can cancel a checkpoint, leaving that event to be repeated after restart.
using Akka;
using Akka.Actor;
using Akka.Streams;
using Akka.Streams.Azure.EventHub;
using Akka.Streams.Dsl;
using Azure.Messaging.EventHubs;
using Azure.Storage.Blobs;
var system = ActorSystem.Create("eventhub-consumer");
EventProcessorClient? processor = null;
try
{
var running = EventHubSource.Create(new ProcessorFactory())
.ViaMaterialized(KillSwitches.Single<ProcessContext>(), Keep.Both)
.SelectAsync(1, async context =>
{
if (context.HasEvent)
{
Console.WriteLine(context.Data!.EventBody.ToString());
await context.UpdateCheckpointAsync(context.CancellationToken);
}
return Done.Instance;
})
.ToMaterialized(Sink.Ignore<Done>(), Keep.Both)
.Run(system.Materializer());
processor = running.Item1.Item1;
await Task.Delay(TimeSpan.FromSeconds(30));
running.Item1.Item2.Shutdown();
try { await running.Item2; }
catch (OperationCanceledException)
{
Console.WriteLine("Shutdown canceled in-flight processing; uncheckpointed events can be replayed.");
}
}
finally
{
try
{
if (processor is not null)
await processor.StopProcessingAsync();
}
finally { await system.Terminate(); }
}
sealed class ProcessorFactory : IProcessorFactory<EventProcessorClient>
{
public EventProcessorClient CreateProcessor() => new(
new BlobContainerClient(Required("BLOB_CONNECTION_STRING"), "checkpoints"),
"orders-consumer", Required("EVENTHUB_CONNECTION_STRING"), "orders");
private static string Required(string name) => Environment.GetEnvironmentVariable(name)
?? throw new InvalidOperationException($"Set {name}.");
}
The source starts from the SDK's default position when no checkpoint exists. Checkpoints control subsequent starts for the same namespace, hub, consumer group and storage container. A different group or container creates an independent checkpoint history.
BatchedEventHubSource.Create(IProcessorFactory<BatchedEventProcessorClient>) instead emits BatchProcessContext, with a List<EventData> in Data, and materializes the custom BatchedEventProcessorClient. Supply that processor through its own factory. Empty batches are not emitted. Process the whole batch successfully before calling its UpdateCheckpointAsync(): that checkpoints the highest event offset/sequence in the batch, so partially processed batches must not be checkpointed. Batch boundaries come from SDK receives; they are not a fixed application batch size.
Both sources hold a receive callback until downstream accepts its context. Cancellation releases waiting callbacks and initiates asynchronous processor shutdown, including on failure. Stream termination can precede processor shutdown. Await the materialized processor's StopProcessingAsync() before disposing checkpoint dependencies. Failures during automatic shutdown are logged; they cannot change an already terminated stream. Do not synchronously stop a processor from inside its own event callbacks.
By default, SDK processing errors fail the source and send errors fail the sink's materialized task. Existing stream supervision attributes can change this behavior: the source's Resume/Restart directives resume pulling rather than recreate its processor; the sink's Resume drops the failed send and Restart retries it. Retries may duplicate delivery. Errors in application processing follow the supervision behavior of that downstream stage.
Local development and tests
The repository's Event Hubs sample AppHost starts the official Event Hubs emulator and Azurite. With Docker running:
aspire start --isolated --apphost src/Azure/Examples/Simple/EventHub/EventHub.AppHost/EventHub.AppHost.csproj
dotnet test src/Azure/Akka.Streams.Azure.EventHub.Tests/Akka.Streams.Azure.EventHub.Tests.csproj -c Release
The tests use Aspire.Hosting.Testing with the same AppHost in test mode, without sample producers/consumers, discovered connection strings and isolated containers. They cover native-SDK sink interoperability, Blob checkpoint persistence and processor recreation, plus deterministic backpressure, cancellation and failure contracts. Missing Docker or emulator startup failures fail the suite. Emulator tests do not establish Azure service identity/RBAC, production throughput, cloud partition distribution or persistence across an emulator restart.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Akka.Streams (>= 1.5.74)
- Azure.Messaging.EventHubs.Processor (>= 5.11.6)
-
net6.0
- Akka.Streams (>= 1.5.74)
- Azure.Messaging.EventHubs.Processor (>= 5.11.6)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 1.5.74 | 85 | 11/13/2026 |
| 1.5.59 | 2,471 | 1/27/2026 |
| 1.5.57 | 273 | 12/23/2025 |
| 1.5.40 | 4,976 | 4/18/2025 |
| 1.5.37 | 233 | 1/23/2025 |
| 1.5.33 | 250 | 12/26/2024 |
| 1.5.28 | 266 | 9/9/2024 |
| 1.5.18 | 327 | 3/29/2024 |
| 1.5.15 | 314 | 1/11/2024 |
| 1.5.8 | 397 | 6/30/2023 |
| 1.5.7 | 339 | 5/31/2023 |
| 1.5.0.1 | 430 | 3/7/2023 |
| 1.5.0 | 420 | 3/3/2023 |
| 1.4.49 | 401 | 3/3/2023 |
| 1.0.1-beta4 | 674 | 10/21/2022 |
| 1.0.1-beta3 | 334 | 10/21/2022 |
| 1.0.1-beta2 | 350 | 7/25/2022 |
| 1.0.1-beta1 | 352 | 6/8/2022 |
| 1.0.0-beta9 | 386 | 3/17/2022 |
| 1.0.0-beta8 | 374 | 12/21/2021 |
* Bump the minimum Akka.NET dependency to [1.5.74](https://github.com/akkadotnet/akka.net/releases/tag/1.5.74), with aligned Streams and TestKit dependencies.
* Include an individual README in each of the twelve connector packages, with usage, ownership, delivery semantics, limitations and linked NuGet version/download badges. Expand the repository README and documentation navigation.
* Update compatible Azure, AWS, AMQP and SignalR dependencies. Package READMEs document remaining SDK support and version limitations.
* Azure Service Bus JSON sources await successful message completion before emitting values and propagate settlement failures.
* Fix SQS batch-response correlation when response entries arrive in a different order.
* Improve SNS and Kinesis completion, cancellation and failure handling.
* Remove blocking SignalR send waits while preserving sequential delivery and existing materialized values.
* Propagate AMQP conversion and connection failures through the materialized completion task.
* Correct CSV parsing across split CRLF/escape sequences and XML parser empty-element/document completion, including reader and feeder cleanup.
* Improve rotating-file sink cleanup on completion and failures.
* Add required service integration, package/API, unchanged-consumer and packaged-example validation. Harden Event Hubs startup and Service Bus polling tests.
* Replace legacy FluentAssertions usages with xUnit assertions, retaining their payload, ordering, exception and deadline checks.
* Mark the historical `Akka.Streams.Channels`, `Akka.Streams.Azure.EventHub.V5` and `Akka.Streams.SignalR.AspNetCore` packages as Legacy on NuGet. See the [migration guide](https://alpakka.getakka.net/documentation/LegacyPackages.html) for their maintained replacements and compatibility requirements.
**Upstream compatibility:** Alpakka retains its public APIs and library targets. Raising the Akka.NET minimum from 1.5.60 inherits upstream binary changes: the old `RetrySupport.Retry` overload with an `int randomFactor` is replaced by a `double` overload, and `ISourceQueue<T>` requires `OfferAsync(T, CancellationToken)`. Applications using that old compiled overload or custom queue implementations need to update and rebuild against the new dependencies.