Use Service Bus Explorer to run data operations on Service Bus (Preview)

Azure Service Bus allows sender and receiver client applications to decouple their business logic with the use of familiar point-to-point (Queue) and publish-subscribe (Topic-Subscription) semantics.

Note

This article highlights the functionality of the Azure Service Bus Explorer that's part of the Azure portal.

The community owned open source Service Bus Explorer is a standalone application and is different from this one.

Operations run on an Azure Service Bus namespace are of two kinds

  • Management operations - Create, update, delete of Service Bus namespace, queues, topics, and subscriptions.
  • Data operations - Send to and receive messages from queues, topics, and subscriptions.

Important

Service Bus Explorer doesn't support management operations.

Prerequisites

To use the Service Bus Explorer tool, you'll need to do the following tasks:

Use the Service Bus Explorer

To use the Service Bus Explorer, navigate to the Service Bus namespace on which you want to do data operations.

  1. If you're looking to run operations against a queue, select Queues from the navigation menu. If you're looking to run operations against a topic (and it's related subscriptions), select Topics.

    Screenshot of left side navigation, where entity can be selected.

  2. After selecting Queues or Topics, select the specific queue or topic.

  3. Select the Service Bus Explorer (preview) from the left navigation menu

    Screenshot of queue blade where Service Bus Explorer can be selected.

    Note

    When peeking or receiving from a subscription, first select the specific Subscription from the dropdown selector. Screenshot of dropdown for topic subscriptions.

Peek a message

With the peek functionality, you can use the Service Bus Explorer to view the top 100 messages in a queue, subscription or dead-letter queue.

  1. To peek messages, select Peek Mode in the Service Bus Explorer dropdown.

    Screenshot of dropdown with Peek Mode selected.

  2. Check the metrics to see if there are Active Messages or Dead-lettered Messages to peek and select either Queue / Subscription or DeadLetter sub-queue.

    Screenshot of queue and dead-letter sub-queue tabs with message metrics displayed.

  3. Select the Peek from start button.

    Screenshot indicating the Peek from start button.

  4. Once the peek operation completes, up to 100 messages will show up on the grid as below. To view the details of a particular message, select it from the grid. You can choose to view the body or the message properties.

    Screenshot with overview of peeked messages and message body content shown for peeked messages.

    Screenshot with overview of peeked messages and message properties shown for peeked messages.

    Note

    Since peek is not a destructive operation the message won't be removed from the entity.

    Note

    For performance reasons, when peeking messages from a queue or subscription which has it's maximum message size set over 1MB, the message body will not be retrieved by default. Instead, you can load the message body for a specific message by clicking on the Load message body button. If the message body is over 1MB it will be truncated before being displayed. Screenshot with overview of peeked messages and button to load message body shown.

Peek a message with advanced options

With the peek with options functionality, you can use the Service Bus Explorer to view the top messages in a queue, subscription or the dead-letter queue, specifying the number of messages to peek, and the sequence number to start peeking from.

  1. To peek messages with advanced options, select Peek Mode in the Service Bus Explorer dropdown.

    Screenshot of dropdown with Peek Mode selected for peek with advanced options.

  2. Check the metrics to see if there are Active Messages or Dead-lettered Messages to peek and select either Queue / Subscription or DeadLetter sub-queue.

    Screenshot of queue and dead-letter sub-queue tabs with message metrics displayed for peek with advanced options.

  3. Select the Peek with options button. Provide the number of messages to peek, and the sequence number to start peeking from, and select the Peek button.

    Screenshot indicating the Peek with options button, and a blade where the options can be set.

  4. Once the peek operation completes, the messages will show up on the grid as below. To view the details of a particular message, select it from the grid. You can choose to view the body or the message properties.

    Screenshot with overview of peeked messages and message body content shown for peek with advanced options.

    Screenshot with overview of peeked messages and message properties shown for peek with advanced options.

    Note

    Since peek is not a destructive operation the message won't be removed from the queue.

Receive a message

The receive function on the Service Bus Explorer permits receiving messages from a queue or subscription.

  1. To receive messages, select Receive Mode in the Service Bus Explorer dropdown.

    Screenshot of dropdown with Receive Mode selected.

  2. Check the metrics to see if there are Active Messages or Dead-lettered Messages to receive, and select either Queue / Subscription or DeadLetter.

    Screenshot of queue and dead-letter sub-queue tabs with message metrics displayed for receive mode.

  3. Select the Receive messages button, and specify the receive mode, the number of messages to receive, and the maximum time to wait for a message and click on the Receive button.

    Screenshot indicating the Receive button, and a blade where the options can be set.

    Important

    Please note that the ReceiveAndDelete mode is a destructive receive, i.e. the message is removed from the queue when it is displayed on the Service Bus Explorer tool.

    To browse messages without removing them from the queue, consider using the Peek functionality, or using the PeekLock receive mode.

  4. Once the receive operation completes, the messages will show up on the grid as below. To view the details of a particular message, select it in the grid.

    Screenshot with overview of received messages and message body content shown.

    Screenshot with overview of received messages and message properties shown.

    Note

    For performance reasons, when receiving messages from a queue or subscription which has it's maximum message size set over 1MB, only one message will be received at a time. If the message body is over 1MB it will be truncated before being displayed.

After a message has been received in PeekLock mode, there are various actions we can take on it.

Note

We can only take these actions as long as we have a lock on the message.

Complete a message

  1. In the grid, select the received message(s) we want to complete.

  2. Select the Complete button.

    Screenshot indicating the Complete button.

    Important

    Please note that completing a message is a destructive receive, i.e. the message is removed from the queue when Complete has been selected in the Service Bus Explorer tool.

Defer a message

  1. In the grid, select the received message(s) we want to defer.

  2. Select the Defer button.

    Screenshot indicating the Defer button.

Abandon lock

  1. In the grid, select the received message(s) for which we want to abandon the lock.

  2. Select the Abandon lock button.

    Screenshot indicating the Abandon Lock button.

After the lock has been abandoned, the message will be available for receive operations again.

Dead-letter

  1. In the grid, select the received message(s) we want to dead-letter.

  2. Select the Dead-letter button.

    Screenshot indicating the Dead-letter button.

After a message has been dead-lettered, it will be available from the Dead-letter sub-queue.

Send a message to a queue or topic

To send a message to a queue or a topic, select the Send messages button of the Service Bus Explorer.

  1. Select the Content Type to be either Text/Plain, Application/Xml or Application/Json.

  2. For Message body, add the message content. Ensure that it matches the Content Type set earlier.

  3. Set the Broker properties (optional) - these include Correlation ID, Message ID, ReplyTo, Label/Subject, Time to Live (TTL) and Scheduled Enqueue Time (for Scheduled Messages).

  4. Set the Custom Properties (optional) - these can be any user properties set against a dictionary key.

  5. Check Repeat send to send the same message multiple times. If no Message ID was set, this will be automatically populated with sequential values.

  6. Once the message has been composed, select the Send button.

    Screenshot showing the compose message experience.

  7. When the send operation is completed successfully, one of the following will happen:

    • If sending to a queue, Active Messages metrics counter will increment.
    • If sending to a topic, Active Messages metrics counter will increment on the Subscriptions where the message was routed to.

Re-send a message

After peeking or receiving a message, we can re-send it, which will send a copy of the message to the same entity, while allowing us to update it's content and properties.

  1. In the grid, select the message(s) we want to re-send.

  2. Select the Re-send selected messages button.

    Screenshot indicating the Re-send selected messages button.

  3. Optionally, select any message for which we want to update its details and make the desired changes.

  4. Select the Send button to send the messages to the entity.

    Screenshot showing the re-send messages experience.

    Note

    If you resend a message in a dead-letter queue of a subscription, a copy of the message is sent to the topic. Therefore, all subscriptions will receive a copy of the message.

Switch authentication type

When working with Service Bus Explorer, it's possible to use either Access Key or Azure Active Directory authentication.

  1. Select the Settings button.

  2. Choose the desired authentication method, and select the Save button.

    Screenshot indicating the Settings button and a blade showing the different authentication types.

Next Steps