Before migrating to the new Azure Service Bus transport, a system using the endpoint-oriented topology must be migrated to the forwarding topology. Migration works side-by-side and the steps are described below.
The endpoint-oriented topology was the first topology included in the Azure Service Bus transport. Its design was based on message-driven publish-subscribe and has several restrictions.
The forwarding topology was introduced to take advantage of the broker-style native capabilities of Azure Service Bus. It is the recommended topology for new projects. The new Azure Service Bus transport is only compatible with the forwarding topology.
Before migrating to the new Azure Service Bus transport, a system using the endpoint-oriented topology must be migrated to the forwarding topology. The migration approach described here allows migration of individual endpoints to the forwarding topology in any order, and avoids a big-bang style migration.
To proceed with migration, it's recommended to verify Azure Service Bus namespaces support the migration feature. See verification steps for migration.
All namespaces used for development, testing, and production should be validated prior to migration taking place.
Before migrating endpoints to the forwarding topology, all endpoints must have migration mode enabled. To enable migration mode:
- Pick an endpoint that is using the endpoint-oriented topology. That is, any endpoint configured with
- Update the
NServiceBus.NuGet package reference to Version 9.1 or higher.
Azure. Transports. WindowsAzureServiceBus
- Enable migration mode by calling
topologyis the object returned by
transport.. Leave all the other configuration as-is.
After applying the above steps to one or more endpoints, they should be deployed to production. This cycle should be repeated until all endpoints using the endpoint-oriented topology have migration mode enabled.
ServiceControl should now be upgraded to Version 3.5.0 or later, and both ServiceControl and Monitoring instances should be updated to the latest. The migration mode is enabled automatically.
After all the endpoints have been running in production for some time with migration mode enabled, they can be migrated to the forwarding topology by switching to the new Azure Service Bus transport as described in the next section.
When all endpoints using the legacy transport are running in migration mode, they can be migrated to the new transport. Before that is done, their compatibility with the new transport should be verified, as described in the compatibility guide. To migrate from the legacy transport:
- Uninstall the
Azure. Transports. WindowsAzureServiceBus
- Install the
- Delete any non-compiling code such as
transport.and remove any
RegisterPublishercalls in routing configuration code.
- If more advanced configuration options have been used with the legacy transport, switch those over to the new configuration options where possible. For configuration options that are not available in the new transport, defaults selected specifically for the new transport will be applied.
After applying the above steps to one or more endpoints, they should be deployed to production. This cycle should be repeated until all endpoints have been migrated to the new transport.
ServiceControl and Monitoring instances should now be switched to
Azure Service Bus transport using ServiceControl Management Utility.
After all, the endpoints have been running in production for some time using the forwarding topology, the endpoint-oriented topology topics with their subscriptions can be removed.
Migration mode has no impact on commands, it only affects events. It does not change how events are published. It only changes how events are subscribed to. Endpoints running in migration mode will continue to publish events using endpoint specific topics. Subscribers running in migration mode change the way they subscribe to events. Subscribers running in migration mode will no longer fetch messages from subscriptions. Instead, they will perform the following:
- Create forwarding topology subscription entities if not yet present; a
bundle-1topic for all events, a subscription per subscriber endpoint, and a SQL filter per event type (in green). A subscription will auto-forward an event to the endpoint's queue.
- Create a
migrationtopic, if not yet present, that performs de-duplication and auto-forwards events to the
bundle-1topic (in red).
- Auto-forward all events arriving at
subscriptions from the endpoint specific topic
migrationtopic (in grey).
Below is an example of a publisher with two events,
EventB, and a subscriber consuming those events. When an endpoint is running in migration mode, the topology is as follows:
Q: Why is the
migration topic required? A: When an instance of a publisher has been migrated to the forwarding topology, and another instance is still in migration, all events published by the endpoint still in migration need to be de-duplicated. The
migration topic ensures events are de-duplicated regardless of which instance published them.
Q: What should be migrated first, subscribers or publishers? A: The order of migration doesn't matter. A publisher could also be a subscriber and the other way around.
Q: Can I add a new endpoint while in migration mode? A: Yes.
Q: Are commands affected by migration mode? A: No. Commands work the same way in both topologies and are not affected by migration.
When migrating from the legacy Azure Service Bus transport, not all configuration settings will be found with the new Azure Service Bus transport. Certain configuration options will not be found in the new transport as it has sensible and optimal settings configured by the transports and should not be altered.
Particular Services Platform support for new transport was added in Service Control version 3 and later.