Powertools for AWS Lambda (.NET)

The AWS.Lambda.Powertools.Parameters utility allows you to retrieve one or multiple parameter values from AWS Systems Manager (SSM) Parameter Store, AWS Secrets Manager, or Amazon DynamoDB.

Key capabilities include:

• Retrieving single or multiple parameters from a provider.
• Caching parameter values for a configurable duration (defaults to 5 seconds).
• Transforming parameter values from JSON or base64 encoded strings.
• Supporting custom parameter store providers.

The Idempotency utility provides several capabilities for managing retries and duplicate prevention:

• Duplicate Prevention: Prevents the Lambda handler from executing more than once on the same event payload during a specific time window.
• Consistent Results: Ensures the Lambda handler returns the same result when called with the same payload.
• Granular Key Selection: Allows you to select a subset of the event to use as the idempotency key using JMESPath expressions.
• Configurable Time Windows: Set a specific duration in which records with the same payload are considered duplicates.
• Timeout Protection: Automatically expires in-progress executions if the Lambda function times out mid-execution.
• AOT Support: Supports Ahead-of-Time compilation to native code (Native AOT) starting from version 1.3.0.

The BatchProcessing utility simplifies handling partial failures when processing batches from Amazon SQS, Amazon Kinesis Data Streams, and Amazon DynamoDB Streams.

Instead of failing an entire batch (which causes all messages to be retried), this utility allows you to report specific failed items. This reduces unnecessary retries and improves efficiency:

• SQS Standard Queues: Only messages reported as failures return to the queue; successful ones are deleted.
• Kinesis and DynamoDB Streams: If one failure is reported, it uses that sequence number as the checkpoint. If multiple failures are reported, the lowest sequence number is used as the checkpoint.

AWS.Lambda.Powertools.Tracing is a thin wrapper around the AWS X-Ray .NET SDK designed to reduce the overhead of common tracing tasks in AWS Lambda.

Key capabilities include:

• Custom Subsegments: Helper methods to simplify creating AWS X-Ray subsegments.
• Cold Start Tracking: Automatically captures cold starts as annotations.
• Response/Error Capture: Can capture function responses and full exceptions as metadata.
• Multi-threading Support: Improved experience when developing with multiple threads.
• Auto-patching: Automatically patches supported modules by AWS X-Ray.

The Batch Processing utility is designed to handle partial failures when processing batches from Amazon SQS, Amazon Kinesis Data Streams, and Amazon DynamoDB Streams.

By default, if a Lambda function fails to process any message in a batch, the entire batch is retried. This utility allows you to report specific item failures back to the event source. This behavior changes based on the source:

• SQS queues: Only messages reported as failures return to the queue for retry; successful ones are deleted.
• Kinesis and DynamoDB streams: A single reported failure uses its sequence number as the checkpoint. Multiple reported failures use the lowest sequence number as the checkpoint.

Note: This utility reduces the chance of duplicate processing but does not guarantee it. You should always implement your processing logic in an idempotent manner.

If you want to add metadata to a specific log statement without affecting subsequent logs, use the 'extra keys' functionality. All standard logging methods (e.g., Logger.Information, Logger.Warning) accept a dictionary or keyword arguments that are added to the root structure of that specific log entry only. These keys are not persisted for subsequent messages.

// Example of adding extra keys to a specific log call
// Note: The documentation implies passing a dictionary or using keyword arguments
// which are then merged into the log root.
Logger.LogInformation("Message with extra context", new Dictionary<string, object> { { "extra_key", "value" } });

You can control how the batch processor reacts to individual item failures using the ErrorHandlingPolicy. This can be set via the POWERTOOLS_BATCH_ERROR_HANDLING_POLICY environment variable or by decorating the handler with the ErrorHandlingPolicy Enum property in the BatchProcessor attribute.

Note: When using StopOnFirstBatchItemFailure with parallel processing enabled, all items already scheduled will be allowed to complete before stopping. For strict ordering, use sequential (non-parallel) processing.

The AppSync Events resolver acts as a router for real-time WebSocket events. When you call app.resolve(event, context) (or the async version), Powertools automatically parses the incoming AppSync event and routes it to the appropriate handler based on the registered namespace and channel patterns.

Key routing methods include:

• OnPublish() / OnPublishAsync(): Handles publish events.
• OnPublishAggregate() / OnPublishAggregateAsync(): Handles batch/aggregated publish events.
• OnSubscribe() / OnSubscribeAsync(): Handles subscription events.

Powertools also handles the response contract, automatically formatting your handler's return value into the specific JSON structure required by AppSync Events.