[Discussion] Service Bus - Track 2 - Message Settlement Location

The intent of this issue is to solicit feedback from the community in advance of the GA of the next major version of the Service Bus library (which will follow several Preview releases). As a reference, the .NET Azure SDK guidelines can be found here: https://azure.github.io/azure-sdk/dotnet_introduction.html Terminology: Track 0 refers to the WindowsAzure.ServiceBus library Track 1 refers to the Microsoft.Azure.ServiceBus library Track 2 refers to the new library, Azure.Messaging.ServiceBus, we are working on releasing.

Background Settlement refers to the operations that can be used to settle a message. These are Complete, Abandon, Defer, and Dead Letter. In version 4 of the Service Bus library, the settlement methods are located directly on the client types. In an earlier version of the library, the settlement methods were on the message. We would like to explore the pros and cons of placing the settlement methods in each place.

Lock token overloads We are planning to include both lock token and message overloads for settlement. The lock token overload is useful for cases where the user may not want to hold onto the entire message before settling. By putting these on the receiver, we would be able to put the overloads on the same type.

var client = new ServiceBusClient("connectionString");
ServiceBusReceiver receiver = client.GetReceiver("myQueue");
ServiceBusReceivedMessage message = await receiver.ReceiveAsync();
// message overload
await receiver.CompleteAsync(message);
// lock token overload 
await receiver.CompleteAsync(message.LockToken);

If we put the settlement methods on the message, we would need to split out the location of the lock token overload:

await message.CompleteAsync();
await receiver.CompleteAsync(message.LockToken);

Batch overloads Similar to the point about lock token overloads, batch versions of the settlement methods would have to be placed on the receiver. So if we put the single message settlement on the message itself we would end up with something like this:

IList<ServiceBusReceivedMessage> messages = await receiver.ReceiveBatchAsync(maximumMessageCount: 10);
// using the single message settlement
foreach (var message in messages)
{
    await message.CompleteAsync();
}
// or with the batch version
await receiver.CompleteAsync(messages);

Other considerations Another issue to consider is how users might think about a settlement method in the context of the ServiceBusReceivedMessage type. Might they think that they are performing a local operation rather than a service call, since they are not calling the method from the receiver type? Also, separating out the settlement methods from the receiver might lead users to believe that they can safely dispose of the receiver before settling the message. This isn’t the case as the message would still be using the receiver’s underlying link to do the message settlement.

One argument in favor of settlement methods being placed on the message, is that it allows for somewhat simpler user code. For instance, users wouldn’t need to pass both the receiver and message along to any method that they write for processing a received message.

Conclusion In spite of some of the simplifying benefits that placing settlement methods on the message allows, we are planning to put the settlement methods on the receiver. This allows for a consistent API when considering the lock token and batch settlement methods. It is also more consistent with the other new Azure SDK libraries, where service operations are generally located on the client types.

[SeanFeldman]

Track 0 had settlement operations on the BrokeredMessage. Track 1 had settlement operations on the clients (receivers).

After using both variants my conclusion that the desire to simplify things should not blind the users. While the API might be interpreted as easier to grasp, there’s the undeniable need to understand how the service works. A Message is never settled on the client. A message is a loaner copy given to the client. The broker is responsible for the settlement and it doesn’t care about message ID or any other property. Except for lock token.

In addition to that, adding the settlement responsibility to the ServiceBusReceivedMessage will turn it from a simple DTO to a type with cross-cutting concerns it shouldn’t have.

The arguments against having settlement methods on the message exceed the negatives associated with the settlement methods on the clients. Personally, I fully agree with the conclusion.

[danielmarbach]

I share the conclusion. I do agree the current design makes sense. The only other option apart from the one you mentioned I see would be to expose a behavior component as a property on the event args which then users have to transitively navigate into. That though wouldn’t allow to set the property on the args and in general I’m not a huge fan of transitive dependency train wrecks