Feedback: 'NServiceBus DataBus feature'

[rvriens]

Feedback for 'NServiceBus DataBus feature' https://docs.particular.net/nservicebus/messaging/claimcheck/

Location in GitHub: https://github.com/Particular/docs.particular.net/blob/master/nservicebus/messaging/claimcheck/index.md

We’re currently using NServiceBus version 8 and have been exploring the DataBus feature. The documentation examples only demonstrate the use of the byte[] type, and this remains the case even in the version 9 examples.

However, we’ve successfully tested using complex types (e.g., custom objects) and would like to clarify:

• Are types other than byte[] officially supported for use with the DataBus?
• Is it recommended to always use byte[] and handle serialization/deserialization manually?
• If complex types are supported, are there any limitations or best practices we should follow?

We understand that using byte[] requires manual serialization and deserialization, which introduces the need for consistency across endpoints. We’d appreciate guidance on whether this is the intended usage pattern or if there are more streamlined approaches supported by the framework.

Example Setup

Endpoint configuration:

.DefiningDataBusPropertiesAs(p => p.Name.EndsWith("DataBusPayload"));

.UseDataBus<AzureDataBus, SystemJsonDataBusSerializer>();

Sending the event:

var message = new TestMessage
{
    MetadataDataBusPayload = new TestMessageMetadata
    {
        RefIds = [.. Enumerable.Range(1, 100000).Select(i => Guid.NewGuid().ToString())],
    }
};
await eventPublisher.PublishAsync(message);

Handler:

internal class TestMessageHandler(ILogger<TestMessageHandler> logger) : IHandleMessages<TestMessage>
{
    public Task Handle(TestMessage message, IMessageHandlerContext context)
    {
        logger.LogInformation("Received TestMessage with MetadataDataBusPayload: {MetadataDataBusPayload}, {MetadataDataBusPayloadCount}",
            message.MetadataDataBusPayload?.RefIds?.Count > 0 
                ? string.Join(", ", message.MetadataDataBusPayload.RefIds.Take(10)) + "..." 
                : "No IDs",
            message.MetadataDataBusPayload?.RefIds?.Count);
        return Task.CompletedTask;
    }
}

We’d love to see the documentation expanded to clarify support for complex types and provide guidance on best practices for serialization with the DataBus.

[DharmishthaVPatel]

@rvriens ,

The primary purpose of the DataBus/ClaimCheck feature is to optimize message handling by offloading large payloads, helping to keep queues efficient and responsive.

The reason that the byte[] is used as the type in various places in documentation is that a common scenario is the desire to send files that are related to the message. In this case you would turn the file into a byte array before sending it as part of the message, this would also require you to turn it back into a file after you received the message, as the message would only contain a byte[].

It should be possible to use the DatabBus with other serializable types besides just the byte[],
as mentioned here ClaimCheckProperty<T> .

We appreciate your questions and comments and we will attempt to better explain this feature in our docs with in a future enhancement.