Azure Service Bus Essentials — Scheduled Messages
How to schedule a message with Azure Service Bus to deliver at a later time.
Azure Service Bus is a managed message queueing service offered by Microsoft Azure. In Azure Service Bus, you can schedule a message to deliver at a later time.
This post discusses how to schedule a message, cancel a scheduled message, and browse already scheduled messages with Azure Service Bus and its .NET SDK client.
Scheduling overview
In messaging, you can send a message to a queue/topic for delayed processing. Those messages are called scheduled messages.
Unlike regular messages, scheduled messages don’t appear in the queue until the defined enqueue time. For example, you can schedule a message at 12 pm and send it to a queue at 10 pm. The message will be invisible for consumers until 12 pm. It will be appended to the queue as a new message at 12 pm.
After you schedule a message, you can cancel it. Cancellation deletes the message.
Benefits and practical use cases
Message scheduling is helpful when you want to postpone non-critical yet essential workloads to a later point in time. Then consumers can pick them up after peak hours.
For example, you can delay email sending tasks until midnight to save the computational capacity of consumers. Another example could be the consumer picking up a message and sending it to an API endpoint. By adding an explicit delay, you can prevent the consumer from being throttled out by downstream API.
Another case is a consumer writing to an eventually consistent database. Adding a delay will help the database to “catch up” with writes made by upstream components.
How to schedule messages in Azure Service Bus?
Azure Service Bus allows you to schedule messages in two ways.
- You can use the regular send API but set the
ScheduledEnqueueTimeUtcproperty on the message before sending. - Use the schedule message API, pass both the regular message and the scheduled time. That will return the scheduled message’s SequenceNumber, which you can later use to cancel the scheduled message if needed.
1. Scheduling with send API
In this method, you have to set a property called ScheduledEnqueueTimeUtcon the message to indicate how long it should be delayed.
The following shows how to do that with C#.
// create a sender for the queue
ServiceBusSender sender = client.CreateSender(queueName);// create a message that we can send
ServiceBusMessage message = new ServiceBusMessage(" ** Hello world! **");// add two minutes delay
message.ScheduledEnqueueTime = DateTimeOffset.Now.AddMinutes(2);// send the message as usual
await sender.SendMessageAsync(message);
2. Scheduling with schedule message API
Here, instead of calling the SendMessageAsync(), you have to call the ScheduleMessageAsync() method with the delay time as an argument.
// create a sender for the queue
ServiceBusSender sender = client.CreateSender(queueName);// create a message that we can send
ServiceBusMessage message = new ServiceBusMessage(" ** Hello world! **");// schedule the message with 2 minutes delay
long seq = await sender.ScheduleMessageAsync(message,
DateTimeOffset.Now.AddMinutes(2)
);
That will return the scheduled message’s SequenceNumber, which you can later use to cancel the scheduled message if needed.
Canceling scheduled messages
Scheduled messages can be canceled before the enqueued time. Canceling the scheduled message will delete it from the service. To cancel a message, you need to know its sequence number.
await sender.CancelScheduledMessageAsync(seq);If you want to cancel a message after scheduling, use the scheduleMessage() method above.
Viewing scheduled messages
The Azure portal shows the number of scheduled messages for a given queue under the MESSAGE COUNTS metric.
Although the scheduled messages can’t be received until their enqueue time, you can still peek at them. Peeking is a non-destructive operation.
For that, you use the built-in message browsing feature to view scheduled messages on the Azure portal UI.
The following shows the content of the message I scheduled with the code I used above.
Takeaways
Message scheduling is helpful when you want to add an artificial delay into the message processing. Azure Service Bus allows you to set an initial delay into a message by either setting ScheduledEnqueueTimeUtcproperty on a message or calling sender.ScheduleMessageAsync() with the delay period. The latter will return the sequence number of the scheduled message.
Scheduled messages can be canceled before the enqueue time. To cancel a message, you need its sequence number.
When the scheduled time passes, a message will be appended to the queue as if it is a brand new one. It will even have a new sequence number.
To view the contents of scheduled messages, you can use the Azure Service Bus Explorer in the Azure portal.
If you like a video version of this, you can find it below.
References
https://docs.microsoft.com/en-us/azure/service-bus-messaging/message-sequencing
