This is part of the NServiceBus Upgrade Guide from Version 7 to 8, which also includes the following individual upgrade guides for specific components:
- 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
- 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
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.
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
SystemJsonDataBusSerializeras an additional deserializer using the
AddDeserializerAPI. This ensures any data bus payload generated by NServiceBus version 8 and
SystemJsonDataBusSerializercan be handled in addition to the older endpoints or in-flight data bus messages.
- Switch the serializer to
BinarySerializeras 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
BinarySerializeras 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:
A runtime exception is thrown if the
IDataBusSerializer is still registered in the container.
Implementing custom serializers
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
public object Deserialize(Type propertyType, Stream stream)
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());