CoreEx.Azure.Messaging.ServiceBus 4.0.0

CoreEx.Azure.Messaging.ServiceBus

Provides Azure Service Bus integration for CoreEx: a ServiceBusPublisher implementing IEventPublisher, subscriber bases wired to EventSubscriberBase, and receiver hosts with built-in resiliency, metrics, and session support.

Overview

CoreEx.Azure.Messaging.ServiceBus is the Azure Service Bus transport binding for the CoreEx events pipeline. It maps the CloudEvents-based IEventPublisher / EventSubscriberBase abstractions defined in CoreEx.Events directly onto the Azure Service Bus SDK, so no application-level code needs to reference Service Bus types directly.

Publishing is handled by ServiceBusPublisher, which inherits EventPublisherBase and implements OnPublishAsync using the SDK's safe-batch send API. Each DestinationEvent is converted from a CloudEvent to a ServiceBusMessage (structured or binary content mode), with CloudEvents attributes optionally written to message application properties. Session-ID assignment is controlled by the ServiceBusSessionStrategy enum.

Subscribing is layered: ServiceBusSubscriberBase extends EventSubscriberBase to accept a raw ServiceBusReceivedMessage, converting it to a CloudEvent before delegating upward. ServiceBusSubscribedSubscriber adds SubscribedManager dispatch so that [Subscribe]-decorated handlers are resolved automatically from the message subject and source. The ServiceBusReceiver<TSubscriber> and ServiceBusSessionReceiver<TSubscriber> classes wrap the SDK ServiceBusProcessor / ServiceBusSessionProcessor lifetimes, and ServiceBusReceiverHostedService<TReceiver> integrates them with the .NET hosted-service model including pause/resume and health-check support.

Resiliency is provided out-of-the-box: ServiceBusReceiverResiliency supplies factory methods for a receiver-level circuit breaker and a per-message retry pipeline (via Polly), both of which are applied by default in ServiceBusReceiverOptionsBase. Both factories are now thin wrappers over CoreEx.Hosting's generic CircuitBreakerResiliency<TOwner>/RetryResiliency<TOwner> (promoted there so CoreEx.Cosmos's Change Feed Processor-based outbox relay shares the exact same self-pause/self-resume behaviour) - this package supplies only the Service-Bus-specific pause-reason/dead-letter-exclusion/retry-classification wiring.

Key capabilities

• 📤 Safe-batch publishing: ServiceBusPublisher groups DestinationEvent by destination and sends via the SDK batch API, recording send/fail counters and duration histograms via ServiceBusMetrics.
• 🛡 CloudEvents — Service Bus bridge: ServiceBusExtensions converts CloudEvent — ServiceBusMessage (structured or binary) and back, propagating distributed-tracing headers and CloudEvents attributes as application properties.
• 📥 Subscriber dispatch: ServiceBusSubscribedSubscriber uses SubscribedManager to route each received message to the correct [Subscribe]-decorated handler by subject and source.
• 🔄 Session support: ServiceBusSessionReceiver<TSubscriber> wraps ServiceBusSessionProcessor; ServiceBusSessionStrategy controls how EventData.PartitionKey is mapped to a SessionId (none, as-is, or converted to a bounded partition ID).
• 🔧 Hosted-service lifecycle: ServiceBusReceiverHostedService<TReceiver> integrates the receiver with IHostedService, forwarding start/pause/resume/stop to the underlying processor and reporting degraded health during pause.
• 🛡 Built-in resiliency: ServiceBusReceiverResiliency provides a circuit-breaker pipeline (ReceiverResiliency) and a per-message retry pipeline (MessageResiliency) pre-wired into every ServiceBusReceiverOptionsBase instance - both delegate to CoreEx.Hosting's generic CircuitBreakerResiliency<TOwner>/RetryResiliency<TOwner>.
• 📊 OpenTelemetry metrics: ServiceBusMetrics exposes a CoreEx.Azure.Messaging.ServiceBus meter with counters for sent, failed, completed, dead-lettered, and abandoned messages, plus a send-duration histogram; ServiceBusReceiverInvoker wraps receive operations in activity spans.
• 📡 Dependency injection helpers: CoreExServiceBusExtensions (AddAzureServiceBusPublisher, AddAzureServiceBusSubscribedSubscriber, AzureServiceBusReceiving()) and CoreExServiceBusExtensions.AddAzureServiceBusOpenTelemetry wire everything into the DI container with a single fluent call each.

Key types

Namespaces

Related namespaces

• CoreEx.Events - Defines IEventPublisher, EventPublisherBase, EventSubscriberBase, SubscribedManager, and IEventFormatter that this package binds to Azure Service Bus.
• CoreEx.Events.Publishing - IDestinationProvider and DestinationEvent used by ServiceBusPublisher during batched dispatch.
• CoreEx.Events.Subscribing - ErrorHandling, ErrorHandler, and subscriber exception types consumed by the receiver pipeline.
• CoreEx.Database.Outbox - Outbox relay publisher that produces events later consumed by a ServiceBusReceiver-based relay host.
• CoreEx.Hosting - CircuitBreakerResiliency<TOwner>/RetryResiliency<TOwner> are the generic self-pausing/retry pipelines that ServiceBusReceiverResiliency now delegates to; originally implemented here, promoted for reuse by CoreEx.Cosmos's outbox relay.

AI Usage Guide

An AGENTS.md file is included with this package. AI coding assistants (GitHub Copilot, Claude, Cursor, etc.) that support workspace-injected package documentation will automatically surface concise usage guidance, code examples, and Do Not rules for this package without requiring a local CoreEx checkout.