AwsLambda.Host 0.1.3

AwsLambda.Host

⚠️ Development Status: This project is actively under development and not yet production-ready. Breaking changes may occur in future versions. Use at your own discretion in production environments.

A modern .NET framework for building AWS Lambda functions using familiar ASP.NET Core patterns. Provides dependency injection, middleware support, compile-time code generation, and AOT support—all optimized for Lambda's execution model.

Packages

The framework is divided into focused packages:

Package	NuGet	Downloads
AwsLambda.Host
AwsLambda.Host.Abstractions
AwsLambda.Host.OpenTelemetry

Installation

Install the NuGet package:

dotnet add package AwsLambda.Host

Ensure your project uses C# 11 or later:

<PropertyGroup>
  <LangVersion>11</LangVersion>
  
</PropertyGroup>

Quick Start

Create a simple Lambda handler:

using AwsLambda.Host;

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

// The [Event] attribute marks the parameter that receives the deserialized Lambda event
lambda.MapHandler(([Event] string input) => $"Hello {input}!");

await lambda.RunAsync();

The [Event] attribute tells the framework which parameter receives the deserialized event. You can also inject dependencies:

lambda.MapHandler(([Event] Order order, IOrderService service) =>
    service.Process(order)
);

Add middleware for cross-cutting concerns:

lambda.Use(async (context, next) =>
{
    Console.WriteLine("Before handler");
    await next();
    Console.WriteLine("After handler");
});

Use OnInit() for setup and OnShutdown() for cleanup:

lambda.OnInit(async (services, token) =>
{
    // Runs once - perfect for initializing resources
    return true;
});

lambda.OnShutdown(async (services, token) =>
{
    // Runs once at shutdown - cleanup resources
});

Key Features

• Source Generators – Compile-time code generation eliminates reflection; zero runtime overhead
• Interceptors – Handler parameters resolved at compile time, not runtime
• Dependency Injection – Built-in scoped lifetime management per invocation
• Middleware Pipeline – Familiar ASP.NET Core-style middleware for cross-cutting concerns
• AOT Ready – Full support for .NET Native AOT compilation
• Lambda Lifecycle – Explicit control over Init, Invocation, and Shutdown phases
• Automatic Cancellation – Cancellation tokens respect Lambda timeout with configurable buffer

Core Concepts

Handlers & Middleware

Register your Lambda handler with the builder. The framework uses source generation to analyze your handler signature:

• The [Event] attribute marks the input parameter type
• The return type determines the response type
• Source generation handles serialization/deserialization automatically

Handlers can inject dependencies alongside the event:

lambda.MapHandler(([Event] Order order, IOrderService service) =>
    service.Process(order)  // Return type automatically serialized to JSON
);

Middleware wraps the handler for cross-cutting concerns. Add as many middlewares as needed—they compose into a pipeline:

lambda.UseMiddleware(async (context, next) =>
{
    // Pre-handler logic
    await next();
    // Post-handler logic
});

lambda.UseMiddleware(async (context, next) =>
{
    // Another middleware layer
    await next();
});

Lambda Lifecycle

The framework manages initialization and shutdown phases automatically. Add as many callbacks as needed—they execute in order and then all awaited:

• OnInit – Runs once when the function initializes; ideal for setting up resources like database connections
• OnShutdown – Runs once before Lambda terminates; cleanup and resource release

Both run asynchronously and should be kept as short as possible to minimize startup/shutdown time.

lambda.OnInit(async (services, token) =>
{
    // One-time setup (runs once, reused across invocations)
    return true; // or false to abort startup
});

lambda.OnShutdown(async (services, token) =>
{
    // Cleanup before shutdown
});

Dependency Injection

Register services in the builder; they're available in handlers, middleware, and lifecycle methods:

builder.Services.AddSingleton<ICache, MemoryCache>();      // Reused across invocations
builder.Services.AddScoped<IRepository, Repository>();    // New per invocation

Each invocation receives its own scope—scoped services are isolated per request. OnInit() and OnShutdown() handlers receive their own scopes as well. You can also request the ILambdaHostContext or CancellationToken in any handler, and they're automatically injected.

Source Generation & Interceptors

The framework uses C# source generators and compile-time interceptors to:

• Analyze handler signatures at compile time
• Generate optimized dependency injection code
• Resolve handler parameters without reflection

Result: Zero runtime reflection, zero performance cost.

AOT Support

To use .NET Native AOT, define a JSON serializer context and annotate with types to serialize:

using System.Text.Json.Serialization;

[JsonSerializable(typeof(Order))]
[JsonSerializable(typeof(OrderResponse))]
public partial class SerializerContext : JsonSerializerContext;

Register it with LambdaApplicationBuilder using the ConfigureLambdaHostOptions extension method:

using Amazon.Lambda.Serialization.SystemTextJson;
using AwsLambda.Host;

var builder = LambdaApplication.CreateBuilder();

builder.Services.ConfigureLambdaHostOptions(settings =>
{
    settings.LambdaSerializer = new SourceGeneratorLambdaJsonSerializer<SerializerContext>();
});

Enable AOT in your project file:

<PublishAot>true</PublishAot>
<PublishTrimmed>true</PublishTrimmed>
<TrimMode>full</TrimMode>
<PublishTrimmed>true</PublishTrimmed>

See AOT documentation for details.

Configuration

The framework supports configuration through LambdaHostOptions:

builder.Services.ConfigureLambdaHostOptions(options =>
{
    options.InitTimeout = TimeSpan.FromSeconds(10);
    options.InvocationCancellationBuffer = TimeSpan.FromSeconds(5);
});

Available options include timeout control, shutdown duration, output formatting, and custom serializers. See the configuration guide for details.

Related Packages

• AwsLambda.Host.Abstractions – Core interfaces and types
• AwsLambda.Host.OpenTelemetry – Distributed tracing integration
• Root README – Project overview and examples

Documentation

• Full Documentation – Comprehensive guides, patterns, and examples
• Examples – Sample Lambda functions demonstrating the framework

Contributing

Contributions are welcome! Please check the GitHub repository for contribution guidelines.

License

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