Merge branch 'dev'

Author: aws-sdk-dotnet-automation

CHANGELOG.md

@@ -1,3 +1,8 @@
+## Release 2026-03-31
+
+### AWS.Messaging (1.2.0)
+* Added SendBatchAsync API
+
 ## Release 2026-02-25
 
 ### AWS.Messaging (1.1.2)

README.md

@@ -162,6 +162,100 @@ await _eventBridgePublisher.PublishAsync(message, new EventBridgeOptions
 });
 ```
 
+## Batch publishing to SQS
+
+The `ISQSPublisher` also supports sending messages in batches using the SQS [`SendMessageBatch`](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html) API. This can significantly increase throughput — from 300 messages per second with individual sends to up to 3,000 messages per second with batching.
+
+The `SendBatchAsync` method accepts a collection of messages and automatically chunks them into groups of 10 (the SQS maximum per batch request).
+
+### Simple batch — no per-message options
+For standard (non-FIFO) queues where no per-message options are needed, you can pass the messages as a simple collection:
+
+```csharp
+var sqsPublisher = serviceProvider.GetRequiredService<ISQSPublisher>();
+
+var messages = new List<ChatMessage>
+{
+    new ChatMessage { MessageDescription = "Hello" },
+    new ChatMessage { MessageDescription = "World" },
+    new ChatMessage { MessageDescription = "Batch!" }
+};
+
+// Send all messages in a batch
+var response = await sqsPublisher.SendBatchAsync(messages);
+
+// Check the results
+Console.WriteLine($"Successful: {response.Successful.Count}");
+Console.WriteLine($"Failed: {response.Failed.Count}");
+```
+
+### Per-message options using `SQSBatchEntry`
+When each message in the batch needs its own options (e.g., different `MessageGroupId` values for FIFO queues), use `SQSBatchEntry<T>` to pair each message with its own `SQSMessageOptions`:
+
+```csharp
+var entries = new List<SQSBatchEntry<ChatMessage>>
+{
+    new SQSBatchEntry<ChatMessage>(
+        new ChatMessage { MessageDescription = "User A's message" },
+        new SQSMessageOptions { MessageGroupId = "userA" }),
+    new SQSBatchEntry<ChatMessage>(
+        new ChatMessage { MessageDescription = "User B's message" },
+        new SQSMessageOptions { MessageGroupId = "userB" }),
+};
+
+// Send with per-message options
+var response = await sqsPublisher.SendBatchAsync(entries);
+```
+
+You can also override the queue URL or SQS client for the entire batch using `SQSBatchOptions`:
+
+```csharp
+var response = await sqsPublisher.SendBatchAsync(entries, new SQSBatchOptions
+{
+    QueueUrl = "https://sqs.us-west-2.amazonaws.com/012345678910/AnotherQueue"
+});
+```
+
+### Handling the batch response
+`SendBatchAsync` returns a `SQSSendBatchResponse` that contains:
+* `Successful` — a list of `SQSSendBatchResponseEntry` with the `Id` and `MessageId` (SQS-assigned ID) for each successfully sent message.
+* `Failed` — a list of `SQSSendBatchResponseFailedEntry` with `Id`, `Code`, `Message`, and `SenderFault` for each message that failed.
+
+The `Id` on each response entry corresponds to the `MessageEnvelope.Id` that the framework generated for that message, so you can correlate successes and failures back to your original inputs.
+
+```csharp
+var response = await sqsPublisher.SendBatchAsync(messages);
+
+foreach (var success in response.Successful)
+{
+    Console.WriteLine($"Sent message {success.Id} with SQS MessageId: {success.MessageId}");
+}
+
+foreach (var failure in response.Failed)
+{
+    Console.WriteLine($"Failed to send {failure.Id}: [{failure.Code}] {failure.Message}");
+}
+```
+
+> **Note:** Messages are automatically chunked into groups of 10. If you send 25 messages, the framework will make 3 SQS `SendMessageBatch` API calls (10 + 10 + 5) and aggregate the results into a single `SQSSendBatchResponse`.
+
+### Error handling and partial results
+If an `AmazonSQSException` is thrown during a batch send (e.g., on the second chunk after the first chunk already succeeded), the framework throws a `FailedToPublishBatchException`. This exception includes a `PartialResponse` property containing any results from chunks that were sent before the failure occurred, so you can determine what was already published and avoid duplicate retries.
+
+```csharp
+try
+{
+    var response = await sqsPublisher.SendBatchAsync(messages);
+}
+catch (FailedToPublishBatchException ex)
+{
+    // Some messages from earlier chunks may have been sent successfully
+    var alreadySent = ex.PartialResponse?.Successful ?? new List<SQSSendBatchResponseEntry>();
+    Console.WriteLine($"{alreadySent.Count} message(s) were sent before the failure.");
+    Console.WriteLine($"Error: {ex.InnerException?.Message}");
+}
+```
+
 # Consuming Messages
 
 To consume messages, implement a message handler using the `IMessageHandler` interface for each message type you wish to process. The mapping between message types and message handlers is configured in the project startup.
@@ -438,7 +532,8 @@ To use the AWS Message Processing Framework for .NET to publish a message to an
             "Sid": "Statement1",
             "Effect": "Allow",
             "Action": [
-                "sqs:sendmessage"
+                "sqs:sendmessage",
+                "sqs:sendmessagebatch"
             ],
             "Resource": [
                 "arn:aws:sqs:<region>:<account>:<queue>"

src/AWS.Messaging/AWS.Messaging.csproj

@@ -18,7 +18,7 @@
     <NoWarn>CS1591</NoWarn>
     <SignAssembly>true</SignAssembly>
     <AssemblyOriginatorKeyFile>..\..\public.snk</AssemblyOriginatorKeyFile>
-    <Version>1.1.2</Version>
+    <Version>1.2.0</Version>
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
     <EmbedUntrackedSources>true</EmbedUntrackedSources>
     <IncludeSymbols>true</IncludeSymbols>

src/AWS.Messaging/Exceptions.cs

@@ -273,6 +273,28 @@ public class InvalidFifoPublishingRequestException : AWSMessagingException
     public InvalidFifoPublishingRequestException(string message, Exception? innerException = null) : base(message, innerException) { }
 }
 
+/// <summary>
+/// Thrown if an exception occurs while publishing a batch of messages.
+/// Contains partial results from chunks that may have already succeeded before the failure.
+/// </summary>
+public class FailedToPublishBatchException : FailedToPublishException
+{
+    /// <summary>
+    /// The partial response containing results from batch chunks that were sent before the failure occurred.
+    /// Earlier chunks may have succeeded even though a later chunk failed.
+    /// </summary>
+    public Publishers.SQS.SQSSendBatchResponse? PartialResponse { get; }
+
+    /// <summary>
+    /// Creates an instance of <see cref="FailedToPublishBatchException"/>.
+    /// </summary>
+    public FailedToPublishBatchException(string message, Exception? innerException = null, Publishers.SQS.SQSSendBatchResponse? partialResponse = null)
+        : base(message, innerException)
+    {
+        PartialResponse = partialResponse;
+    }
+}
+
 /// <summary>
 /// Thrown if the <see cref="EventBridgePublishResponse"/> contains a message with an error code
 /// </summary>

src/AWS.Messaging/Publishers/SQS/ISQSPublisher.cs

@@ -8,6 +8,9 @@ namespace AWS.Messaging.Publishers.SQS
     /// <summary>
     /// This interface allows sending messages from application code to Amazon SQS.
     /// It exposes the <see cref="SendAsync{T}(T, SQSOptions?, CancellationToken)"/> method which takes in a user-defined message, and <see cref="SQSOptions"/> to set additional parameters while sending messages to SQS.
+    /// It also exposes <see cref="SendBatchAsync{T}(IEnumerable{T}, CancellationToken)"/> and
+    /// <see cref="SendBatchAsync{T}(IEnumerable{SQSBatchEntry{T}}, SQSBatchOptions?, CancellationToken)"/> methods
+    /// for sending up to multiple messages in batches using the SQS SendMessageBatch API.
     /// Using dependency injection, this interface is available to inject anywhere in the code.
     /// </summary>
     public interface ISQSPublisher : ICommandPublisher
@@ -19,5 +22,34 @@ public interface ISQSPublisher : ICommandPublisher
         /// <param name="sqsOptions">Contains additional parameters that can be set while sending a message to an SQS queue</param>
         /// <param name="token">The cancellation token used to cancel the request.</param>
         Task<SQSSendResponse> SendAsync<T>(T message, SQSOptions? sqsOptions, CancellationToken token = default);
+
+        /// <summary>
+        /// Sends a batch of application messages to SQS using the SendMessageBatch API.
+        /// Messages are automatically chunked into groups of 10 (the SQS maximum per batch request).
+        /// <para>
+        /// This is a convenience overload for sending simple batches where no per-message options
+        /// are needed. For FIFO queues or when per-message options are required, use
+        /// <see cref="SendBatchAsync{T}(IEnumerable{SQSBatchEntry{T}}, SQSBatchOptions?, CancellationToken)"/> instead.
+        /// </para>
+        /// </summary>
+        /// <typeparam name="T">The .NET type of the application message.</typeparam>
+        /// <param name="messages">The application messages that will be serialized and sent to an SQS queue.</param>
+        /// <param name="token">The cancellation token used to cancel the request.</param>
+        /// <returns>A <see cref="SQSSendBatchResponse"/> containing the results for each message in the batch.</returns>
+        Task<SQSSendBatchResponse> SendBatchAsync<T>(IEnumerable<T> messages, CancellationToken token = default);
+
+        /// <summary>
+        /// Sends a batch of application messages to SQS using the SendMessageBatch API,
+        /// with per-message <see cref="SQSMessageOptions"/> allowing different options (e.g. <see cref="SQSMessageOptions.MessageGroupId"/>)
+        /// for each message in the batch.
+        /// Messages are automatically chunked into groups of 10 (the SQS maximum per batch request).
+        /// </summary>
+        /// <typeparam name="T">The .NET type of the application message.</typeparam>
+        /// <param name="entries">The batch entries, each containing a message and optional per-message options.</param>
+        /// <param name="batchOptions">Optional batch-level parameters such as <see cref="SQSBatchOptions.QueueUrl"/>
+        /// and <see cref="SQSBatchOptions.OverrideClient"/>.</param>
+        /// <param name="token">The cancellation token used to cancel the request.</param>
+        /// <returns>A <see cref="SQSSendBatchResponse"/> containing the results for each message in the batch.</returns>
+        Task<SQSSendBatchResponse> SendBatchAsync<T>(IEnumerable<SQSBatchEntry<T>> entries, SQSBatchOptions? batchOptions = null, CancellationToken token = default);
     }
 }

src/AWS.Messaging/Publishers/SQS/SQSBatchEntry.cs

@@ -0,0 +1,42 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+namespace AWS.Messaging.Publishers.SQS;
+
+/// <summary>
+/// Represents a single entry in a batch send operation to SQS.
+/// Pairs an application message with optional per-message <see cref="SQSMessageOptions"/>.
+/// </summary>
+/// <typeparam name="T">The .NET type of the application message.</typeparam>
+public class SQSBatchEntry<T>
+{
+    /// <summary>
+    /// Creates an instance of <see cref="SQSBatchEntry{T}"/>.
+    /// </summary>
+    public SQSBatchEntry()
+    {
+    }
+
+    /// <summary>
+    /// Creates an instance of <see cref="SQSBatchEntry{T}"/> with the specified message and options.
+    /// </summary>
+    /// <param name="message">The application message to send.</param>
+    /// <param name="options">Optional per-message SQS options.</param>
+    public SQSBatchEntry(T message, SQSMessageOptions? options = null)
+    {
+        Message = message;
+        Options = options;
+    }
+
+    /// <summary>
+    /// The application message that will be serialized and sent to an SQS queue.
+    /// </summary>
+    public T Message { get; set; } = default!;
+
+    /// <summary>
+    /// Optional per-message options such as <see cref="SQSMessageOptions.MessageGroupId"/>,
+    /// <see cref="SQSMessageOptions.MessageDeduplicationId"/>, <see cref="SQSMessageOptions.DelaySeconds"/>,
+    /// and <see cref="SQSMessageOptions.MessageAttributes"/>.
+    /// </summary>
+    public SQSMessageOptions? Options { get; set; }
+}

src/AWS.Messaging/Publishers/SQS/SQSBatchOptions.cs

@@ -0,0 +1,29 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+using Amazon.SQS;
+
+namespace AWS.Messaging.Publishers.SQS;
+
+/// <summary>
+/// Contains batch-level properties that apply to an entire batch send operation to SQS.
+/// <para>
+/// This class is used on the <see cref="ISQSPublisher.SendBatchAsync{T}(IEnumerable{SQSBatchEntry{T}}, SQSBatchOptions?, CancellationToken)"/>
+/// method to override the queue URL or SQS client for the batch. Per-message properties such as
+/// <see cref="SQSMessageOptions.MessageGroupId"/> should be set on each <see cref="SQSBatchEntry{T}.Options"/> instead.
+/// </para>
+/// </summary>
+public class SQSBatchOptions
+{
+    /// <summary>
+    /// The SQS queue URL which the publisher will use for the batch. This can be used to override the queue URL
+    /// that is configured for a given message type when publishing a batch.
+    /// </summary>
+    public string? QueueUrl { get; set; }
+
+    /// <summary>
+    /// An alternative SQS client that can be used to publish this batch,
+    /// instead of the client provided by the registered <see cref="Configuration.IAWSClientProvider"/> implementation.
+    /// </summary>
+    public IAmazonSQS? OverrideClient { get; set; }
+}

src/AWS.Messaging/Publishers/SQS/SQSMessageOptions.cs

@@ -0,0 +1,54 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+using Amazon.SQS.Model;
+
+namespace AWS.Messaging.Publishers.SQS;
+
+/// <summary>
+/// Contains per-message properties that can be set when sending individual messages
+/// within a batch to an SQS queue.
+/// <para>
+/// This class is used on <see cref="SQSBatchEntry{T}.Options"/> to specify message-level
+/// settings such as <see cref="MessageGroupId"/> and <see cref="MessageDeduplicationId"/>.
+/// </para>
+/// </summary>
+public class SQSMessageOptions
+{
+    /// <summary>
+    /// The length of time, in seconds, for which to delay a specific message.
+    /// Its valid values are between 0 to 900.
+    /// Messages with a positive DelaySeconds value become available for processing after the delay period is finished.
+    /// If you don't specify a value, the default value for the queue applies.
+    /// When you set FifoQueue, you can't set DelaySeconds per message. You can set this parameter only on a queue level.
+    /// </summary>
+    public int? DelaySeconds { get; set; }
+
+    /// <summary>
+    /// Each message attribute consists of a Name, Type, and Value.
+    /// For more information, see <see href="https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-message-metadata.html#sqs-message-attributes">the Amazon SQS developer guide.</see>
+    /// </summary>
+    public Dictionary<string, MessageAttributeValue>? MessageAttributes { get; set; }
+
+    /// <summary>
+    /// This parameter applies only to FIFO(first-in-first-out) queues and is used for deduplication of sent messages.
+    /// If a message with a particular MessageDeduplicationId is sent successfully, any messages sent with the same
+    /// MessageDeduplicationId are accepted successfully but aren't delivered during the 5-minute deduplication interval.
+    /// For more information, see <see href="https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues-exactly-once-processing.html">Exactly-once processing</see>
+    /// in the Amazon SQS Developer Guide.
+    /// <para>
+    /// Each message in a batch should have a unique MessageDeduplicationId. Setting the same deduplication ID
+    /// across multiple messages in a batch would incorrectly indicate they are duplicates of each other.
+    /// </para>
+    /// </summary>
+    public string? MessageDeduplicationId { get; set; }
+
+    /// <summary>
+    /// This parameter applies only to FIFO(first-in-first-out) queues and specifies that a message belongs to a specific message group.
+    /// Messages that belong to the same message group are processed in a FIFO manner
+    /// (however, messages in different message groups might be processed out of order).
+    /// To interleave multiple ordered streams within a single queue, use MessageGroupId values
+    /// (for example, session data for multiple users).
+    /// </summary>
+    public string? MessageGroupId { get; set; }
+}