Skip to main content
Version: v2.0.0

Migration guide towards v1.0

Starting from v1.0, there are some major breaking changes. To make it easier for you migrate towards this new version, we have assembled a migration guide to help you in the process.

New Azure SDK

We have chosen to also update our library to the new Azure SDK when interacting with the Azure Service Bus (#159). This package update has some consequences on our library.

Note that Azure Service Bus plug-ins are still not supported in this new SDK.

Package update

The Microsoft.Azure.ServiceBus NuGet package is now completely removed from the library and is changed by the Arcus.Messaging.ServiceBus NuGet package. This means that possible compile errors can occur when using types or signatures that were only available in this older package.

Service Bus message update for fallback message handlers

The AzureServiceBusFallbackMessageHandler<> abstract type has an updated signature as it now uses the new ServiceBusReceivedMessage instead of the Message when providing a fallback for a message handler pipeline:

- using Microsoft.Azure.ServiceBus;
+ using Azure.Messaging.ServiceBus;

public class OrderFallbackMessageHandler : AzureServiceBusFallbackMessageHandler
public override async Task ProcessMessageAsync(
- Message message,
+ ServiceBusReceivedMessage message,
AzureServiceBusMessageContext azureMessageContext,
MessageCorrelationInfo correlationInfo,
CancellationToken cancellationToken)

Note that some Service Bus-specific operations were renamed to, see this section for more info.

Message correlation information update

The correlation information model MessageCorrelationInfo could previously be extracted from the Message of the old SDK with the extension message.GetCorrelationInfo().

This new version works with the new ServiceBusReceivedMessage, so the correlation extension is also moved.

- using Microsoft.Azure.ServiceBus;
+ using Azure.Messaging.ServiceBus;

- Message message = ...
+ ServiceBusReceivedMessage message = ...


Moved message handler types to abstraction namespaces

All your Azure Service Bus message handlers implementations will probably give compile errors. This is caused by the breaking change that moved all the 'message handler'-related types towards abstractions namespaces (#153). Practically, this means that these namespaces are renamed:

  • Arcus.Messaging.Pumps.MessagingHandling becomes Arcus.Messaging.Abstractions.MessageHandling
  • Arcus.Messaging.Pumps.ServiceBus.MessageHandling becomes Arcus.Messaging.Abstractions.MessageHandling.ServiceBus
    • Also the IAzureServiceBusMessageHandler<> is moved to this new namespace.

This has effect on the IAzureServiceBusMessageHandler<>, IAzureServiceBusFallbackMessageHandler interfaces; and the AzureServiceBusMessageHandler<>, AzureServiceBusFallbackMessageHandler<> abstract types. Following example shows how older versions has now uses non-existing namespaces in the.

- using Arcus.Messaging.Pumps.ServiceBus;
+ using Arcus.Messaging.Abstractions.MessageHandling.ServiceBus;

public class OrderMessageHandler : IAzureServiceBusMessageHandler<Order>

Renamed fallback message handler operations

Any of your custom fallback message handler implementations that inherit from the AzureServiceBusFallbackMessageHandler abstract type will probably cause compile errors. This is caused by our change that renamed the Service Bus-specific operations on this abstract type (#194).

public class OrderFallbackMessageHandler : AzureServiceBusFallbackMessageHandler<Order>
public override Task ProcessMessageAsync(...)
- base.CompleteAsync(message);
+ base.CompleteMessageAsync(message);

Fluent API discovery for message handling

It's possible that some of your Azure Service Bus message handler registrations give compile errors. This is caused because we have introduced a dedicated type as return type when registering an Azure Service Bus message pump (#152). This dedicated type helps with the discovery of the available message handler registration options.

Following example shows how older versions could register the message handler directly on the services, while now they're only available after registering the message pump:

- services.AddServiceBusQueueMessagePump(...);
- services.WithServiceBusMessageHandler<OrderMessageHandler, Order>();

+ services.AddServiceBusQueueMessagePump(...)
+ .WithServiceBusMessageHandler<OrderMessageHandler, Order>();