The AWS SDK for .NET V3 has entered maintenance mode.
We recommend that you migrate to [AWS SDK for .NET V4](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/welcome.html). For additional details and information on how to migrate, please refer to our [maintenance mode announcement](https://aws.amazon.com/blogs/developer/aws-sdk-for-net-v3-maintenance-mode-announcement/).
# AWS Message Processing Framework for .NET
The AWS Message Processing Framework for .NET is an AWS-native framework that simplifies the development of .NET message processing applications that use AWS services such as Amazon Simple Queue Service (SQS), Amazon Simple Notification Service (SNS), and Amazon EventBridge. The framework reduces the amount of boiler-plate code developers need to write, allowing you to focus on your business logic when publishing and consuming messages. For details about how the framework can simplify your development, see the blog post [Introducing the AWS Message Processing Framework for .NET (Preview)](https://aws.amazon.com/blogs/developer/introducing-the-aws-message-processing-framework-for-net-preview/). The first part in particular provides a demonstration that shows the difference between using low-level API calls and using the framework.
The Message Processing Framework supports the following activities and features:
+ Sending messages to SQS and publishing events to SNS and EventBridge.
+ Receiving and handling messages from SQS by using a long-running poller, which is typically used in background services. This includes managing the visibility timeout while a message is being handled to prevent other clients from processing it.
+ Handling messages in AWS Lambda functions.
+ FIFO (first-in-first-out) SQS queues and SNS topics.
+ OpenTelemetry for logging.
For details about these activities and features see the **Features** section of the [blog post](https://aws.amazon.com/blogs/developer/introducing-the-aws-message-processing-framework-for-net-preview/) and the topics listed below.
Before you begin, be sure you have [set up your environment and project](net-dg-config.md). Also review the information in [SDK features](net-dg-sdk-features.md).
**Additional resources**
+ The [https://www.nuget.org/packages/AWS.Messaging/](https://www.nuget.org/packages/AWS.Messaging/) package on [NuGet.org](https://www.nuget.org/).
+ The [API reference](https://aws.github.io/aws-dotnet-messaging/).
+ The `README` file in the GitHub repo at [https://github.com/aws/aws-dotnet-messaging/](https://github.com/aws/aws-dotnet-messaging/)
+ [.NET dependency injection](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection) from Microsoft.
+ [.NET Generic Host](https://learn.microsoft.com/en-us/dotnet/core/extensions/generic-host) from Microsoft.
**Topics**
+ [Get started](msg-proc-fw-get-started.md)
+ [Publish messages](msg-proc-fw-publish.md)
+ [Consume messages](msg-proc-fw-consume.md)
+ [FIFO](msg-proc-fw-fifo.md)
+ [Logging and Open Telemetry](msg-proc-fw-telemetry.md)
+ [Customize](msg-proc-fw-customize.md)
+ [Security](msg-proc-fw-security.md)
# Get started with the AWS Message Processing Framework for .NET
Before you begin, be sure you have [set up your environment and project](net-dg-config.md). Also review the information in [SDK features](net-dg-sdk-features.md).
This topic provides information that will help you get started using the Message Processing Framework. In addition to prerequisite and configuration information, a tutorial is provided that shows you how to implement a common scenario.
## Prerequisites and configuration
+ The credentials you provide for your application must have appropriate permissions for the messaging service and operations that it uses. For more information, see the security topics for [SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-authentication-and-access-control.html), [SNS](https://docs.aws.amazon.com/sns/latest/dg/security-iam.html), and [EventBridge](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-iam.html) in their respective developer guides. Also see the portion of the [README](https://github.com/aws/aws-dotnet-messaging/) file on GitHub that discusses specific [permissions](https://github.com/aws/aws-dotnet-messaging/blob/main/README.md#permissions).
+ To use the AWS Message Processing Framework for .NET, you must add the [https://www.nuget.org/packages/AWS.Messaging](https://www.nuget.org/packages/AWS.Messaging) NuGet package to your project. For example:
```
dotnet add package AWS.Messaging
```
+ The framework integrates with .NET's [dependency injection (DI) service container](https://learn.microsoft.com/en-us/dotnet/core/extensions/dependency-injection). You can configure the framework during your application's startup by calling `AddAWSMessageBus` to add it to the DI container.
```
var builder = WebApplication.CreateBuilder(args);
// Register the AWS Message Processing Framework for .NET
builder.Services.AddAWSMessageBus(builder =>
{
// Register that you'll publish messages of type ChatMessage to an existing queue
builder.AddSQSPublisher("https://sqs.us-west-2.amazonaws.com/012345678910/MyAppProd");
});
```
## Tutorial
This tutorial demonstrates how to use the AWS Message Processing Framework for .NET. It creates two applications: an ASP.NET Core Minimal API that sends messages to an Amazon SQS queue when it receives a request at an API endpoint, and a long-running console application that polls for these messages and handles them.
+ The instructions in this tutorial favor the .NET CLI, but you can perform this tutorial by using either cross-platform tools such as the .NET CLI or Microsoft Visual Studio. For information about tools, see [Install and configure your toolchain](net-dg-dev-env.md).
+ This tutorial assumes that you're using your `[default]` profile for credentials. It also assumes that short-term credentials are available with appropriate permissions for sending and receiving Amazon SQS messages. For more information, see [Configure SDK authentication with AWS](creds-idc.md) and the security topics for [SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-authentication-and-access-control.html).
**Note**
By running this tutorial, you might incur costs for SQS messaging.
### Steps
+ [Create an SQS queue](#mpf-tutorial-queue)
+ [Create and run the publishing application](#mpf-tutorial-publish)
+ [Create and run the handling application](#mpf-tutorial-handle)
+ [Cleanup](#mpf-tutorial-cleanup)
### Create an SQS queue
This tutorial requires an SQS queue to send messages to and receive messages from. A queue can be created by using one of the following commands for the AWS CLI or the AWS Tools for PowerShell. Take note of the queue URL that is returned so that you can specify it in the framework configuration that follows.
------
#### [ AWS CLI ]
```
aws sqs create-queue --queue-name DemoQueue
```
------
#### [ AWS Tools for PowerShell ]
```
New-SQSQueue -QueueName DemoQueue
```
------
### Create and run the publishing application
Use the following procedure to create and run the publishing application.
1. Open a command prompt or terminal. Find or create an operating system folder under which you can create a .NET project.
1. In that folder, run the following command to create the .NET project.
```
dotnet new webapi --name Publisher
```
1. Navigate into the new project's folder. Add a dependency on the AWS Message Processing Framework for .NET.
```
cd Publisher
dotnet add package AWS.Messaging
```
**Note**
If you're using AWS IAM Identity Center for authentication, be sure to also add `AWSSDK.SSO` and `AWSSDK.SSOOIDC`.
1. Replace the code in `Program.cs` with the following code.
```
using AWS.Messaging;
using Microsoft.AspNetCore.Mvc;
using Publisher;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
// Configure the AWS Message Processing Framework for .NET.
builder.Services.AddAWSMessageBus(builder =>
{
// Check for input SQS URL.
// The SQS URL should be passed as a command line argument or set in the Debug launch profile.
if ((args.Length == 1) && (args[0].Contains("https://sqs.")))
{
// Register that you'll publish messages of type GreetingMessage:
// 1. To a specified queue.
// 2. Using the message identifier "greetingMessage", which will be used
// by handlers to route the message to the appropriate handler.
builder.AddSQSPublisher(args[0], "greetingMessage");
}
// You can map additional message types to queues or topics here as well.
});
var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
app.UseHttpsRedirection();
// Create an API Endpoint that receives GreetingMessage objects
// from the caller and then sends them as an SQS message.
app.MapPost("/greeting", async ([FromServices] IMessagePublisher publisher, Publisher.GreetingMessage message) =>
{
return await PostGreeting(message, publisher);
})
.WithName("SendGreeting")
.WithOpenApi();
app.Run();
public partial class Program
{
///
/// Endpoint for posting a greeting message.
///
/// The greeting message.
/// The message publisher.
/// Async task result.
public static async Task PostGreeting(GreetingMessage greetingMessage,
IMessagePublisher messagePublisher)
{
if (greetingMessage.SenderName == null || greetingMessage.Greeting == null)
{
return Results.BadRequest();
}
// Publish the message to the queue configured above.
await messagePublisher.PublishAsync(greetingMessage);
return Results.Ok();
}
}
namespace Publisher
{
///
/// This class represents the message contents.
///
public class GreetingMessage
{
public string? SenderName { get; set; }
public string? Greeting { get; set; }
}
}
```
1. Run the following command. This should open a browser window with the Swagger UI, which allows you to explore and test your API.
```
dotnet watch run
```
1. Open the `/greeting` endpoint and choose **Try it out**.
1. Specify `senderName` and `greeting` values for the message, and choose **Execute**. This invokes your API, which sends the SQS message.
### Create and run the handling application
Use the following procedure to create and run the handling application.
1. Open a command prompt or terminal. Find or create an operating system folder under which you can create a .NET project.
1. In that folder, run the following command to create the .NET project.
```
dotnet new console --name Handler
```
1. Navigate into the new project's folder. Add a dependency on the AWS Message Processing Framework for .NET. Also add the `Microsoft.Extensions.Hosting` package, which allows you to configure the framework through the [.NET Generic Host](https://learn.microsoft.com/en-us/dotnet/core/extensions/generic-host).
```
cd Handler
dotnet add package AWS.Messaging
dotnet add package Microsoft.Extensions.Hosting
```
**Note**
If you're using AWS IAM Identity Center for authentication, be sure to also add `AWSSDK.SSO` and `AWSSDK.SSOOIDC`.
1. Replace the code in `Program.cs` with the following code.
```
using AWS.Messaging;
using Handler;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
var builder = Host.CreateDefaultBuilder(args);
builder.ConfigureServices(services =>
{
// Register the AWS Message Processing Framework for .NET.
services.AddAWSMessageBus(builder =>
{
// Check for input SQS URL.
// The SQS URL should be passed as a command line argument or set in the Debug launch profile.
if ((args.Length == 1) && (args[0].Contains("https://sqs.")))
{
// Register you'll poll the following queue.
builder.AddSQSPoller(args[0]);
// And that messages of type "greetingMessage" should be:
// 1. Deserialized as GreetingMessage objects.
// 2. Which are then passed to GreetingMessageHandler.
builder.AddMessageHandler("greetingMessage");
}
// You can add additional message handlers here, using different message types.
});
});
var host = builder.Build();
await host.RunAsync();
namespace Handler
{
///
/// This class represents the message contents.
///
public class GreetingMessage
{
public string? SenderName { get; set; }
public string? Greeting { get; set; }
}
///
/// This handler is invoked each time you receive the message.
///
public class GreetingMessageHandler : IMessageHandler
{
public Task HandleAsync(
MessageEnvelope messageEnvelope,
CancellationToken token = default)
{
Console.WriteLine(
$"Received message {messageEnvelope.Message.Greeting} from {messageEnvelope.Message.SenderName}");
return Task.FromResult(MessageProcessStatus.Success());
}
}
}
```
1. Run the following command. This starts a long-running poller.
```
dotnet run
```
Shortly after startup the application will receive the message that was sent in the first part of this tutorial and log the following message:
```
Received message {greeting} from {senderName}
```
1. Press `Ctrl+C` to stop the poller.
### Cleanup
Use one of the following commands for the AWS CLI or the AWS Tools for PowerShell to delete the queue.
------
#### [ AWS CLI ]
```
aws sqs delete-queue --queue-url ""
```
------
#### [ AWS Tools for PowerShell ]
```
Remove-SQSQueue -QueueUrl ""
```
------
# Publish messages with the AWS Message Processing Framework for .NET
The AWS Message Processing Framework for .NET supports publishing one or more message types, processing one or more message types, or doing both in the same application.
The following code shows a configuration for an application that is publishing different message types to different AWS services.
```
var builder = WebApplication.CreateBuilder(args);
// Register the AWS Message Processing Framework for .NET
builder.Services.AddAWSMessageBus(builder =>
{
// Register that you'll send messages of type ChatMessage to an existing queue
builder.AddSQSPublisher("https://sqs.us-west-2.amazonaws.com/012345678910/MyAppProd");
// Register that you'll publish messages of type OrderInfo to an existing SNS topic
builder.AddSNSPublisher("arn:aws:sns:us-west-2:012345678910:MyAppProd");
// Register that you'll publish messages of type FoodItem to an existing EventBridge bus
builder.AddEventBridgePublisher("arn:aws:events:us-west-2:012345678910:event-bus/default");
});
```
Once you have registered the framework during startup, inject the generic `IMessagePublisher` into your code. Call its `PublishAsync` method to publish any of the message types that were configured above. The generic publisher will determine the destination to route the message to based on its type.
In the following example, an ASP.NET MVC controller receives both `ChatMessage` messages and `OrderInfo` events from users, and then publishes them to Amazon SQS and Amazon SNS respectively. Both message types can be published using the generic publisher that was configured above.
```
[ApiController]
[Route("[controller]")]
public class PublisherController : ControllerBase
{
private readonly IMessagePublisher _messagePublisher;
public PublisherController(IMessagePublisher messagePublisher)
{
_messagePublisher = messagePublisher;
}
[HttpPost("chatmessage", Name = "Chat Message")]
public async Task PublishChatMessage([FromBody] ChatMessage message)
{
// Perform business and validation logic on the ChatMessage here.
if (message == null)
{
return BadRequest("A chat message was not submitted. Unable to forward to the message queue.");
}
if (string.IsNullOrEmpty(message.MessageDescription))
{
return BadRequest("The MessageDescription cannot be null or empty.");
}
// Send the ChatMessage to SQS, using the generic publisher.
await _messagePublisher.PublishAsync(message);
return Ok();
}
[HttpPost("order", Name = "Order")]
public async Task PublishOrder([FromBody] OrderInfo message)
{
if (message == null)
{
return BadRequest("An order was not submitted.");
}
// Publish the OrderInfo to SNS, using the generic publisher.
await _messagePublisher.PublishAsync(message);
return Ok();
}
}
```
In order to route a message to the appropriate handling logic, the framework uses metadata called the *message type identifier*. By default, this is the full name of the message's .NET type, including its assembly name. If you're both sending and handling messages, this mechanism works well if you share the definition of your message objects across projects. However, if the messages are redefined in different namespaces, or if you're exchanging messages with other frameworks or programming languages, then you might need to override the message type identifier.
```
var builder = Host.CreateDefaultBuilder(args);
builder.ConfigureServices(services =>
{
// Register the AWS Message Processing Framework for .NET
services.AddAWSMessageBus(builder =>
{
// Register that you'll publish messages of type GreetingMessage to an existing queue
builder.AddSQSPublisher("https://sqs.us-west-2.amazonaws.com/012345678910/MyAppProd", "greetingMessage");
});
});
```
## Service-specific publishers
The example shown above uses the generic `IMessagePublisher`, which can publish to any supported AWS service based on the configured message type. The framework also provides service-specific publishers for Amazon SQS, Amazon SNS and Amazon EventBridge. These specific publishers expose options that only apply to that service, and can be injected using the types `ISQSPublisher`, `ISNSPublisher`, and `IEventBridgePublisher`.
For example, when sending messages to an SQS FIFO queue, you must set the appropriate [message group ID](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-key-terms.html). The following code shows the `ChatMessage` example again, but now using an `ISQSPublisher` to set SQS-specific options.
```
public class PublisherController : ControllerBase
{
private readonly ISQSPublisher _sqsPublisher;
public PublisherController(ISQSPublisher sqsPublisher)
{
_sqsPublisher = sqsPublisher;
}
[HttpPost("chatmessage", Name = "Chat Message")]
public async Task PublishChatMessage([FromBody] ChatMessage message)
{
// Perform business and validation logic on the ChatMessage here
if (message == null)
{
return BadRequest("A chat message was not submitted. Unable to forward to the message queue.");
}
if (string.IsNullOrEmpty(message.MessageDescription))
{
return BadRequest("The MessageDescription cannot be null or empty.");
}
// Send the ChatMessage to SQS using the injected ISQSPublisher, with SQS-specific options
await _sqsPublisher.SendAsync(message, new SQSOptions
{
DelaySeconds = ,
MessageAttributes = ,
MessageDeduplicationId = ,
MessageGroupId =
});
return Ok();
}
}
```
The same can be done for SNS and EventBridge, using `ISNSPublisher` and `IEventBridgePublisher` respectively.
```
await _snsPublisher.PublishAsync(message, new SNSOptions
{
Subject = ,
MessageAttributes = ,
MessageDeduplicationId = ,
MessageGroupId =
});
```
```
await _eventBridgePublisher.PublishAsync(message, new EventBridgeOptions
{
DetailType = ,
Resources = ,
Source = ,
Time =