AwsLambda.Host.Envelopes.Sqs 1.3.1

AwsLambda.Host.Envelopes.Sqs

Strongly-typed SQS event handling for the AwsLambda.Host framework.

Overview

This package provides SqsEnvelope<T>, which extends the base SQSEvent class with a generic Records collection that deserializes message bodies into strongly-typed objects. Instead of manually parsing JSON from record.Body, you access deserialized payloads directly via record.BodyContent. This package also provides SqsSnsEnvelope<T> for handling SNS messages delivered via SQS queues (SNS-to-SQS subscription pattern).

Quick Start

Define your message type and handler:

using Amazon.Lambda.SQSEvents;
using AwsLambda.Host.Builder;
using AwsLambda.Host.Envelopes.Sqs;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

var builder = LambdaApplication.CreateBuilder();
var lambda = builder.Build();

// SqsEnvelope<Message> provides access to the SQS event and deserialized Message payloads
lambda.MapHandler(
 ([Event] SqsEnvelope<Message> envelope, ILogger<Program> logger) =>
 {
 // In order to handle any errors or unprocessed messages, you must return a SQSBatchResponse
 var batchResponse = new SQSBatchResponse();

 foreach (var record in envelope.Records)
 {
 // For this example, we'll add a failure to the batch response if the message body is null
 if (record.BodyContent is null)
 batchResponse.BatchItemFailures.Add(
 new SQSBatchResponse.BatchItemFailure { ItemIdentifier = record.MessageId }
 );

 logger.LogInformation("Message: {Name}", record.BodyContent?.Name);
 }

 // Return the batch response regardless of whether there were any failures
 return batchResponse;
 }
);

await lambda.RunAsync();

// Your message payload - will be deserialized from SQS message body
internal record Message(string Name);

Custom Envelopes

To implement custom deserialization logic, extend SqsEnvelopeBase<T> and override the ExtractPayload method:

// Example: Custom XML deserialization
public sealed class SqsXmlEnvelope<T> : SqsEnvelopeBase<T>
{
 private static readonly XmlSerializer Serializer = new(typeof(T));

 public override void ExtractPayload(EnvelopeOptions options)
 {
 foreach (var record in Records)
 {
 using var stringReader = new StringReader(record.Body);
 using var xmlReader = XmlReader.Create(stringReader, options.XmlReaderSettings);
 record.BodyContent = (T)Serializer.Deserialize(xmlReader)!;
 }
 }
}

This pattern allows you to support multiple serialization formats while maintaining the same envelope interface.

AOT Support

When using .NET Native AOT, register both the envelope and payload types in your JsonSerializerContext:

[JsonSerializable(typeof(SqsEnvelope<Message>))]
[JsonSerializable(typeof(Message))]
internal partial class SerializerContext : JsonSerializerContext;

Register the serializer and configure envelope options to use the context:

builder.Services.AddLambdaSerializerWithContext<SerializerContext>();

builder.Services.ConfigureEnvelopeOptions(options =>
{
 options.JsonOptions.TypeInfoResolver = SerializerContext.Default;
});

SqsSnsEnvelope - SNS-to-SQS Subscription Pattern

This package also provides SqsSnsEnvelope<T> for handling SNS messages delivered via SQS queues (SNS-to-SQS subscription pattern). Unlike SqsEnvelope<T> which performs single-stage deserialization, SqsSnsEnvelope<T> performs two-stage deserialization:

1. The SQS message body is deserialized into an SNS message envelope
2. The SNS message content is then deserialized into your payload type

This envelope is useful when you have an SNS topic that delivers messages to an SQS queue, and your Lambda function processes messages from that queue.

[JsonSerializable(typeof(SqsSnsEnvelope<Request>))]
[JsonSerializable(typeof(SnsEnvelope<Request>.SnsMessageEnvelope))]
[JsonSerializable(typeof(SNSEvent.MessageAttribute), TypeInfoPropertyName = "SnsMessageAttribute")]
[JsonSerializable(typeof(SQSEvent.MessageAttribute), TypeInfoPropertyName = "SqsMessageAttribute")]
[JsonSerializable(typeof(Request))]
internal partial class SerializerContext : JsonSerializerContext;

Other Packages

Additional packages in the aws-lambda-host framework for abstractions, observability, and event source handling.

License

This project is licensed under the MIT License. See for details.