Skip to content

API changes and batch schedule #12796

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JoshLove-msft merged 5 commits into from
Jun 18, 2020
Merged

API changes and batch schedule #12796

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c11a505
API changes and batch schedule
JoshLove-msft Jun 16, 2020
6b109fa
Update snippets
JoshLove-msft Jun 16, 2020
2877423
PR comments
JoshLove-msft Jun 16, 2020
6137fda
Rebase issues
JoshLove-msft Jun 16, 2020
3de8404
PR comments
JoshLove-msft Jun 17, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 21 additions & 21 deletions sdk/servicebus/Azure.Messaging.ServiceBus/MigrationGuide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,27 +63,27 @@ In the interest of simplifying the API surface we've made a single top level cli

### Sending messages

The v4 client allowed for sending a single message or a list of messages, which had the potential to fail unexpectedly if the maximum allowable size was exceeded. v7 aims to prevent this by asking that you first create a batch of messages using `CreateBatchAsync` and then attempt to add messages to that using `TryAdd()`. If the batch accepts a message, you can be confident that it will not violate size constraints when calling Send to send the batch. v7 still allows sending a single message.
The v4 client allowed for sending a single message or a list of messages, which had the potential to fail unexpectedly if the maximum allowable size was exceeded. v7 aims to prevent this by allowing you to first create a batch of messages using `CreateMessageBatchAsync` and then attempt to add messages to that using `TryAddMessage()`. If the batch accepts a message, you can be confident that it will not violate size constraints when calling Send to send the batch. v7 still allows sending a single message and sending an `IEnumerable` of messages, though using the `IEnumerable` overload has the same risks as V4.

| In v4 | Equivalent in v7 | Sample |
|------------------------------------------------|------------------------------------------------------------------|--------|
| `QueueClient.SendAsync(Message)` or `MessageSender.SendAsync(Message)` | `ServiceBusSender.SendAsync(ServiceBusMessage)` | [Send a message](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample01_HelloWorld.md#sending-and-receiving-a-message) |
| `QueueClient.SendAsync(IList<Message>)` or `MessageSender.SendAsync(IList<Message>)` | `messageBatch = ServiceBusSender.CreateBatchAsync()` `messageBatch.TryAdd(ServiceBusMessage)` `ServiceBusSender.SendAsync(messageBatch)` | [Send a batch of messages](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample01_HelloWorld.md#sending-and-receiving-a-batch-of-messages) |
| `QueueClient.SendAsync(Message)` or `MessageSender.SendAsync(Message)` | `ServiceBusSender.SendMessageAsync(ServiceBusMessage)` | [Send a message](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample01_HelloWorld.md#sending-and-receiving-a-message) |
| `QueueClient.SendAsync(IList<Message>)` or `MessageSender.SendAsync(IList<Message>)` | `messageBatch = ServiceBusSender.CreateMessageBatchAsync()` `messageBatch.TryAddMessage(ServiceBusMessage)` `ServiceBusSender.SendMessagesAsync(messageBatch)` or `ServiceBusSender.SendMessagesAsync(IEnumerable<ServiceBusMessage>)` | [Send a batch of messages](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample01_HelloWorld.md#sending-and-receiving-a-batch-of-messages) |

### Receiving messages

| In v4 | Equivalent in v7 | Sample |
|------------------------------------------------|------------------------------------------------------------------|--------|
| `MessageReceiver.ReceiveAsync()` | `ServiceBusReceiver.ReceiveAsync()` | [Receive a message](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample01_HelloWorld.md#sending-and-receiving-a-message) |
| `MessageReceiver.ReceiveAsync()` | `ServiceBusReceiver.ReceiveBatchAsync()` | [Receive a batch of messages](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample01_HelloWorld.md#sending-and-receiving-a-batch-of-messages) |
| `MessageReceiver.ReceiveAsync()` | `ServiceBusReceiver.ReceiveMessageAsync()` | [Receive a message](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample01_HelloWorld.md#sending-and-receiving-a-message) |
| `MessageReceiver.ReceiveAsync()` | `ServiceBusReceiver.ReceiveMessagesAsync()` | [Receive a batch of messages](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample01_HelloWorld.md#sending-and-receiving-a-batch-of-messages) |
| `QueueClient.RegisterMessageHandler()` or `MessageReceiver.RegisterMessageHandler()` | `ServiceBusProcessor.ProcessMessageAsync += MessageHandler` `ServiceBusProcessor.ProcessErrorAsync += ErrorHandler` `ServiceBusProcessor.StartProcessingAsync()` | [Receive messages using processor](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample04_Processor.md) |

### Working with sessions

| In v4 | Equivalent in v7 | Sample |
|------------------------------------------------|------------------------------------------------------------------|--------|
| `MessageSender.SendAsync(new Message{SessionId = "sessionId"})` | `ServiceBusSender.SendAsync(new ServiceBusMessage{SessionId = "sessionId"})` | [Send a message to session](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample03_SendReceiveSessions.md) |
| `IMessageSession.ReceiveAsync()` | `ServiceBusSessionReceiver.ReceiveAsync()` | [Receive a message from session](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample03_SendReceiveSessions.md) |
| `MessageSender.SendAsync(new Message{SessionId = "sessionId"})` | `ServiceBusSender.SendMessageAsync(new ServiceBusMessage{SessionId = "sessionId"})` | [Send a message to session](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample03_SendReceiveSessions.md) |
| `IMessageSession.ReceiveAsync()` | `ServiceBusSessionReceiver.ReceiveMessageAsync()` | [Receive a message from session](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample03_SendReceiveSessions.md) |
| `IMessageSession.RegisterMessageHandler()` | `ServiceBusSessionProcessor.ProcessMessageAsync += MessageHandler` `ServiceBusSessionProcessor.ProcessErrorAsync += ErrorHandler` `ServiceBusSessionProcessor.StartProcessingAsync()` | [Receive messages from session processor](https://github.com/Azure/azure-sdk-for-net/blob/master/sdk/servicebus/Azure.Messaging.ServiceBus/samples/Sample05_SessionProcessor.md) |

## Migration samples
Expand All @@ -92,7 +92,7 @@ The v4 client allowed for sending a single message or a list of messages, which

In v4, `QueueClient`/`MessageSender`/`MessageReceiver` would be created directly, after which user would call `SendAsync()` method via `QueueClient`/`MessageSender` to send a message and `ReceiveAsync()` method via `MessageReceiver` to receive a message.

In v7, user would initialize the `ServiceBusClient` and call `CreateSender()` method to create a `ServiceBusSender` and `CreateReceiver()` method to create a `ServiceBusReceiver`. To send a message, user would call `SendAsync()` via `ServiceBusSender` and to receive a message, user would call `ReceiveAsync()` via `ServiceBusReceiver`.
In v7, user would initialize the `ServiceBusClient` and call `CreateSender()` method to create a `ServiceBusSender` and `CreateReceiver()` method to create a `ServiceBusReceiver`. To send a message, user would call `SendMessageAsync()` via `ServiceBusSender` and to receive a message, user would call `ReceiveMessageAsync()` via `ServiceBusReceiver`.

In v4:

Expand Down Expand Up @@ -140,13 +140,13 @@ ServiceBusSender sender = client.CreateSender(queueName);
ServiceBusMessage message = new ServiceBusMessage(Encoding.UTF8.GetBytes("Hello world!"));

// send the message
await sender.SendAsync(message);
await sender.SendMessageAsync(message);

// create a receiver that we can use to receive the message
ServiceBusReceiver receiver = client.CreateReceiver(queueName);

// the received message is a different type as it contains some service set properties
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveAsync();
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveMessageAsync();

// get the message body as a string
string body = receivedMessage.Body.ToString();
Expand All @@ -160,15 +160,15 @@ In v4, `QueueClient`/`MessageSender`/`MessageReceiver` would be created directly
In v7, user would initialize the `ServiceBusClient` and call `CreateSender()` method to create a `ServiceBusSender` and
`CreateReceiver()` method to create a `ServiceBusReceiver`. There are two ways of sending several messages at once.

The first way uses the `SendAsync`overload that accepts an IEnumerable of `ServiceBusMessage`. With this method, we will
The first way uses the `SendMessagesAsync`overload that accepts an IEnumerable of `ServiceBusMessage`. With this method, we will
attempt to fit all of the supplied messages in a single message batch that we will send to the service. If the messages are
too large to fit in a single batch, the operation will throw an exception.

The second way of doing this is using safe-batching. With safe-batching, you can create a `ServiceBusMessageBatch` object,
which will allow you to attempt to add messages one at a time to the batch using the `TryAdd` method. If the message cannot
fit in the batch, `TryAdd` will return false. If the `ServiceBusMessageBatch` accepts a message, user can be confident that
it will not violate size constraints when calling `SendAsync()` via `ServiceBusSender`. To receive a batch of messages,
user would call `ReceiveBatchAsync()` method via `ServiceBusReceiver`.
which will allow you to attempt to add messages one at a time to the batch using the `TryAddMessage` method. If the message cannot
fit in the batch, `TryAddMessage` will return false. If the `ServiceBusMessageBatch` accepts a message, user can be confident that
it will not violate size constraints when calling `SendMessagesAsync()` via `ServiceBusSender`. To receive a set of messages, a
user would call `ReceiveMessagesAsync()` method via `ServiceBusReceiver`.

In v4:

Expand Down Expand Up @@ -223,18 +223,18 @@ IList<ServiceBusMessage> messages = new List<ServiceBusMessage>();
messages.Add(new ServiceBusMessage(Encoding.UTF8.GetBytes("First")));
messages.Add(new ServiceBusMessage(Encoding.UTF8.GetBytes("Second")));
// send the messages
await sender.SendAsync(messages);
await sender.SendMessagesAsync(messages);
```

Or using the safe-batching feature:

```C# Snippet:ServiceBusSendAndReceiveSafeBatch
ServiceBusMessageBatch messageBatch = await sender.CreateBatchAsync();
messageBatch.TryAdd(new ServiceBusMessage(Encoding.UTF8.GetBytes("First")));
messageBatch.TryAdd(new ServiceBusMessage(Encoding.UTF8.GetBytes("Second")));
ServiceBusMessageBatch messageBatch = await sender.CreateMessageBatchAsync();
messageBatch.TryAddMessage(new ServiceBusMessage(Encoding.UTF8.GetBytes("First")));
messageBatch.TryAddMessage(new ServiceBusMessage(Encoding.UTF8.GetBytes("Second")));

// send the message batch
await sender.SendAsync(messageBatch);
await sender.SendMessagesAsync(messageBatch);
```

And to receive a batch:
Expand All @@ -243,7 +243,7 @@ And to receive a batch:
ServiceBusReceiver receiver = client.CreateReceiver(queueName);

// the received message is a different type as it contains some service set properties
IList<ServiceBusReceivedMessage> receivedMessages = await receiver.ReceiveBatchAsync(maxMessages: 2);
IList<ServiceBusReceivedMessage> receivedMessages = await receiver.ReceiveMessagesAsync(maxMessages: 2);

foreach (ServiceBusReceivedMessage receivedMessage in receivedMessages)
{
Expand Down
48 changes: 24 additions & 24 deletions sdk/servicebus/Azure.Messaging.ServiceBus/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,13 +116,13 @@ ServiceBusSender sender = client.CreateSender(queueName);
ServiceBusMessage message = new ServiceBusMessage(Encoding.UTF8.GetBytes("Hello world!"));

// send the message
await sender.SendAsync(message);
await sender.SendMessageAsync(message);

// create a receiver that we can use to receive the message
ServiceBusReceiver receiver = client.CreateReceiver(queueName);

// the received message is a different type as it contains some service set properties
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveAsync();
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveMessageAsync();

// get the message body as a string
string body = receivedMessage.Body.ToString();
Expand All @@ -131,7 +131,7 @@ Console.WriteLine(body);

### Send and receive a batch of messages

There are two ways of sending several messages at once. The first way uses the `SendAsync`
There are two ways of sending several messages at once. The first way uses the `SendMessagesAsync`
overload that accepts an IEnumerable of `ServiceBusMessage`. With this method, we will attempt to fit all of
the supplied messages in a single message batch that we will send to the service. If the messages are too large
to fit in a single batch, the operation will throw an exception.
Expand All @@ -141,19 +141,19 @@ IList<ServiceBusMessage> messages = new List<ServiceBusMessage>();
messages.Add(new ServiceBusMessage(Encoding.UTF8.GetBytes("First")));
messages.Add(new ServiceBusMessage(Encoding.UTF8.GetBytes("Second")));
// send the messages
await sender.SendAsync(messages);
await sender.SendMessagesAsync(messages);
```
The second way of doing this is using safe-batching. With safe-batching, you can create a
`ServiceBusMessageBatch` object, which will allow you to attempt to add messages one at a time to the
batch using the `TryAdd` method. If the message cannot fit in the batch, `TryAdd` will return false.

```C# Snippet:ServiceBusSendAndReceiveSafeBatch
ServiceBusMessageBatch messageBatch = await sender.CreateBatchAsync();
messageBatch.TryAdd(new ServiceBusMessage(Encoding.UTF8.GetBytes("First")));
messageBatch.TryAdd(new ServiceBusMessage(Encoding.UTF8.GetBytes("Second")));
ServiceBusMessageBatch messageBatch = await sender.CreateMessageBatchAsync();
messageBatch.TryAddMessage(new ServiceBusMessage(Encoding.UTF8.GetBytes("First")));
messageBatch.TryAddMessage(new ServiceBusMessage(Encoding.UTF8.GetBytes("Second")));

// send the message batch
await sender.SendAsync(messageBatch);
await sender.SendMessagesAsync(messageBatch);
```

### Complete a message
Expand All @@ -173,41 +173,41 @@ ServiceBusSender sender = client.CreateSender(queueName);
ServiceBusMessage message = new ServiceBusMessage(Encoding.UTF8.GetBytes("Hello world!"));

// send the message
await sender.SendAsync(message);
await sender.SendMessageAsync(message);

// create a receiver that we can use to receive and settle the message
ServiceBusReceiver receiver = client.CreateReceiver(queueName);

// the received message is a different type as it contains some service set properties
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveAsync();
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveMessageAsync();

// complete the message, thereby deleting it from the service
await receiver.CompleteAsync(receivedMessage);
await receiver.CompleteMessageAsync(receivedMessage);
```

### Abandon a message

Abandoning a message releases our receiver's lock, which allows the message to be received by this or other receivers.

```C# Snippet:ServiceBusAbandonMessage
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveAsync();
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveMessageAsync();

// abandon the message, thereby releasing the lock and allowing it to be received again by this or other receivers
await receiver.AbandonAsync(receivedMessage);
await receiver.AbandonMessageAsync(receivedMessage);
```

### Defer a message

Deferring a message will prevent it from being received again using the `ReceiveAsync` or `ReceiveBatchAsync` methods.
Instead, there are separate methods, `ReceiveDeferredMessageAsync` and `ReceiveDeferredMessageBatchAsync`
Deferring a message will prevent it from being received again using the `ReceiveMessageAsync` or `ReceiveMessagesAsync` methods.
Instead, there are separate methods, `ReceiveDeferredMessageAsync` and `ReceiveDeferredMessagesAsync`
for receiving deferred messages.

```C# Snippet:ServiceBusDeferMessage
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveAsync();
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveMessageAsync();

// defer the message, thereby preventing the message from being received again without using
// the received deferred message API.
await receiver.DeferAsync(receivedMessage);
await receiver.DeferMessageAsync(receivedMessage);

// receive the deferred message by specifying the service set sequence number of the original
// received message
Expand All @@ -221,14 +221,14 @@ by the service after they have been received a certain number of times. Applicat
their requirements. When a message is dead lettered it is actually moved to a subqueue of the original queue.

```C# Snippet:ServiceBusDeadLetterMessage
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveAsync();
ServiceBusReceivedMessage receivedMessage = await receiver.ReceiveMessageAsync();

// deadletter the message, thereby preventing the message from being received again without receiving from the dead letter queue.
await receiver.DeadLetterAsync(receivedMessage);
await receiver.DeadLetterMessageAsync(receivedMessage);

// receive the dead lettered message with receiver scoped to the dead letter queue.
ServiceBusReceiver dlqReceiver = client.CreateDeadLetterReceiver(queueName);
ServiceBusReceivedMessage dlqMessage = await dlqReceiver.ReceiveAsync();
ServiceBusReceivedMessage dlqMessage = await dlqReceiver.ReceiveMessageAsync();
```

### Using the Processor
Expand All @@ -249,12 +249,12 @@ await using var client = new ServiceBusClient(connectionString);
ServiceBusSender sender = client.CreateSender(queueName);

// create a message batch that we can send
ServiceBusMessageBatch messageBatch = await sender.CreateBatchAsync();
messageBatch.TryAdd(new ServiceBusMessage(Encoding.UTF8.GetBytes("First")));
messageBatch.TryAdd(new ServiceBusMessage(Encoding.UTF8.GetBytes("Second")));
ServiceBusMessageBatch messageBatch = await sender.CreateMessageBatchAsync();
messageBatch.TryAddMessage(new ServiceBusMessage(Encoding.UTF8.GetBytes("First")));
messageBatch.TryAddMessage(new ServiceBusMessage(Encoding.UTF8.GetBytes("Second")));

// send the message batch
await sender.SendAsync(messageBatch);
await sender.SendMessagesAsync(messageBatch);

// get the options to use for configuring the processor
var options = new ServiceBusProcessorOptions
Expand Down
Loading