Azure-sdk-for-net: Rename Peek methods to Browse

[JoshLove-msft]

In our UX studies, users were confused between the concepts of Peek and ReceiveMode.PeekLock. We considered updating the ReceiveMode enum to be called something like ReceiveAndLock (which would align nicely with ReceiveAndDelete), but due to all of the existing documentation out there referring to PeekLock, it was determined the inertia was too great to move away from this name. In order to reduce the confusion, and highlight the differences in the concepts, we would like to rename the PeekAsync/PeekBatchAsync/PeekAtAsync/PeekBatchAtAsync to BrowseAsync/BrowseBatchAsync/BrowseAtAsync/BrowseBatchAtAsync.

[SeanFeldman]

We considered updating the ReceiveMode enum to be called something like ReceiveAndLock (which would align nicely with ReceiveAndDelete)

This would be a technically incorrect name. With ReceiveAndDelete that is what's happening from the user perspective. A message is received and deleted from the broker. ReceiveAndLock would have to be LockAndReceive. But that's not really relevant.

Regarding the proposal

In our UX studies, users were confused between the concepts of Peek and ReceiveMode.PeekLock.

I'm willing to bet my money that the users were not very much familiar with the Azure Service Bus and likely had most of the queuing experience with services such as Storage Queues. The term "Peek" is well established and understood among developers that work with queuing systems. And not just Service Bus. Personally, I see no value in renaming the method. Rather, I'd keep Browse for an operation where messages are peeked based on status (one or more) which is not possible with the Peek operation.

[SeanFeldman]

Just to show how ubiquitous the term 'peek' is:

• MSMQ
• Azure Storage Queue (v12)
• System.Collections.Queue

JMS is the one that is using Browsing as the term for peeking. I would advise against forcing this on the .NET SDK where the terminology is already well established.

[SeanFeldman]

Another reason to keep it as Peek - the portal now supports SBExplorer for Azure Portal and the operations on messages are 'Send', 'Receive', and 'Peek'. 'Peek' is the term developers are already familiar with from using tools such as SBExplorer for Windows, Serverless 360, Queue Explorer, etc.

[JoshLove-msft]

Wow, that is really cool that the Explorer is now integrated with the portal!
Thanks for the feedback - this is still an ongoing discussion.

[richardpark-msft]

@SeanFeldman - allright, you convinced us :)

This is one of those areas where changing the name (regardless of what it is) isn't going to be enough (and thus, probably isn't the best solution).

What we've decided to go with instead:

• Make sure that in areas where a user might mistakenly take a peek'd message and settle it, we'll throw an error indicating that you need to use peekLock mode messages for that. (runtime guard)
• Better documentation in the methods (TBD what that _is_) to give user guidance on the differences between peek() and receive()).

As always, we appreciate your feedback. Also, congratulations on getting Service Bus Explorer into the portal. Probably one of my favorite tools (especially lately!)

@JoshLove-msft , I leave it up to you to close this issue if you want to track any remaining doc/runtime work.

[JoshLove-msft]

I do think we can slightly improve our error message to instead say: "This operation is not supported for peeked messages. Only messages received in PeekLock mode can be settled."

Though maybe this might unintentionally introduce more confusion being that PeekLock is the default and users don't need to know about it if they are using defaults.

[SeanFeldman]

I do think we can slightly improve our error message to instead say: "This operation is not supported for peeked messages. Only messages received in PeekLock mode can be settled."

"Only received message can be settled." is poorly phrased. A message received in ReceiveAndDelete mode is also a received message, but cannot be settled. The suggestion to improve the error message is a good suggestion, @JoshLove-msft.

[SeanFeldman]

@JoshLove-msft should the title of the issue reflect the decision made in the thread?

[JoshLove-msft]

Yeah I will close this issue out and address the error message in a different PR that I have going.
Updated -
https://github.com/Azure/azure-sdk-for-net/pull/12276/commits/0b190ea92433175d3a895a7b83be8059c51a2b2c