Upgrading the data bus from version 7 to 8

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.

Seralizer configuration made mandatory

The new data bus configuration API now requires a serializer to be explicitly configured.

endpointConfiguration.UseDataBus<FileShareDataBus, SystemJsonDataBusSerializer>();

endpointConfiguration.UseDataBus<FileShareDataBus>();

The recommended serializer is SystemJsonDataBusSerializer that is built-in and that uses the System.Text.Json library. While BinaryFormatter is still supported via the new package called NServiceBus.DataBus.BinarySerializer, customers are strongly encouraged to move away from it.

Removal of dependency injection support for serializers

The serializer interface IDataBusSerializer can no longer be resolved via the container and serializers must be configured explicitly.

endpointConfiguration.UseDataBus<FileShareDataBus, MyCustomDataBusSerializer>();

endpointConfiguration.RegisterComponents(registration => registration.ConfigureComponent<MyCustomDataBusSerializer>(DependencyLifecycle.SingleInstance));
endpointConfiguration.UseDataBus<FileShareDataBus>();

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.DataBus.BinarySerializer. Add SystemJsonDataBusSerializer as an additional deserializer using the AddDeserializer API. This ensures any data bus payload generated by NServiceBus version 8 and SystemJsonDataBusSerializer can be handled in addition to the older endpoints or in-flight data bus messages.
• Switch the serializer to SystemJsonDataBusSerializer and add BinarySerializer 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.DataBusConfig.ContentType, 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.

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 MyCustomDataBus(serviceProvider.GetRequiredService<SomeDependency>()), new SystemJsonDataBusSerializer());

endpointConfiguration.UseDataBus(typeof(MyCustomDataBus));