This is part of the NServiceBus Upgrade Guide from Version 7 to 8, which also includes the following individual upgrade guides for specific components:
Feature Details
- Upgrading the data bus from version 7 to 8
- Dependency Injection changes
- Upgrade NServiceBus downstreams from Version 7 to 8
- Upgrading message contracts from Version 7 to 8
- Upgrade NServiceBus pipeline extensions from Version 7 to 8
- Transport configuration changes
Transports
- Upgrade AmazonSQS Transport Version 5 to 6
- Azure Service Bus Transport Upgrade Version 2 to 3
- Azure Storage Queues Transport Upgrade Version 10 to 11
- MSMQ Transport Upgrade Version 1 to 2
- RabbitMQ Transport Upgrade Version 7 to 8
- SQL Server Transport Upgrade Version 6 to 7
Persistence
Other
The BinaryFormatter serializer that was used internally in NServiceBus version 7 is moved to a separate package. The BinaryFormatter is unsafe by nature and could cause security vulnerabilities and as a result is being phased out by Microsoft. The new data bus configuration API now requires a serializer.
endpointConfiguration.UseDataBus<FileShareDataBus, SystemJsonDataBusSerializer>();
The recommended serializer is SystemJsonDataBusSerializer
that is built-in and that uses the System.
library. While BinaryFormatter is still supported via the new package called NServiceBus.
, customers are strongly encouraged to move away from it.
Migration from BinaryFormatter
When an exception is thrown during deserialization of data bus messages, additional deserializers will be evaluated. This can be used to roll out a migration strategy and remove the binary formatter usage over time. Consider the following plan:
- Roll out endpoints using NServiceBus version 8 and keep using the binary formatter through the new package
NServiceBus.
. AddDataBus. BinarySerializer SystemJsonDataBusSerializer
as an additional deserializer using theAddDeserializer
API. This ensures any data bus payload generated by NServiceBus version 8 andSystemJsonDataBusSerializer
can be handled in addition to the older endpoints or in-flight data bus messages. - Switch the serializer to
SystemJsonDataBusSerializer
and addBinarySerializer
as an additional deserializer. This can be done per endpoint so that the selected endpoints start using the new serializer for data bus payloads serialization. The additional deserializer can handle messages from endpoints still using on the older serializer. - Once all endpoints are migrated and the in-flight messages are processed, remove the
BinarySerializer
as the additional deserializer.
Note that the newly added header, NServiceBus.
, in NServiceBus version 8 determines which deserializer should be used. If the header is missing, the main deserializer will be used first, followed by the additional configured deserializers.
Removal of dependency injection support for serializers
The serializer interface IDataBusSerializer
can no longer be resolved via the container. Registered custom data bus serializers now must be provided in code and the registration code can be removed:
endpointConfiguration.UseDataBus<FileShareDataBus, SystemJsonDataBusSerializer>();
A runtime exception is thrown if the IDataBusSerializer
is still registered in the container.
Implementing custom serializers
The IDataBusSerializer
interface is changed to better isolate type information causing security concerns. Custom implementations of this interface should ignore type information embedded in the persisted payload and use the propertyType
passed to the Deserialize
method:
public object Deserialize(Type propertyType, Stream stream)
An additional ContentType
property is now also required when implementing this interface.
Configuring custom IDataBus implementations
The API to provide a custom IDataBus
implementation has been changed from accepting a Type
to a factory method. The new API is:
endpointConfiguration.UseDataBus(serviceProvider => new MyDataBus(serviceProvider.GetRequiredService<SomeDependency>()), new SystemJsonDataBusSerializer());