MinimalLambda 2.6.0

MinimalLambda

Minimal API-style ergonomics, Lambda-first runtime – Build Lambda functions for any trigger using familiar .NET patterns without sacrificing Lambda-specific capabilities.

📚 View Full Documentation

Overview

Write Lambda functions with the familiar minimal API pattern from ASP.NET Core, adapted for Lambda's execution model:

var builder = LambdaApplication.CreateBuilder();
builder.Services.AddScoped<IMyService, MyService>();

var lambda = builder.Build();
lambda.MapHandler(([FromEvent] string input, IMyService service) =>
 service.Process(input));

await lambda.RunAsync();

The framework provides:

• Minimal API Pattern: lambda.MapHandler(...) in the same declarative style as app.MapGet()
• Dependency Injection: The ASP.NET Core container with scoped lifetimes tailored to Lambda invocations
• Middleware Pipeline: Familiar Use() pattern for cross-cutting concerns
• Source Generated: Compile-time code generation for zero reflection overhead
• Native AOT Ready: Full AOT support for sub-100ms cold starts
• Lambda-Optimized: Envelopes, lifecycle hooks, automatic cancellation tokens, and timeout handling

Installation

Install the NuGet package:

dotnet add package MinimalLambda

Ensure your project uses C# 11 or later:

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

Quick Start

Create a simple Lambda handler:

using MinimalLambda.Builder;
using Microsoft.Extensions.Hosting;

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

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

await lambda.RunAsync();

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

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

Add middleware for cross-cutting concerns:

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

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

// Service can be injected into the Init handler
lambda.OnInit(ICache cache =>
{
 // Runs once at startup - perfect for setting up resources
 cache.Warm();
});

// Handlers can also control if the Init phase should be continued or not
lambda.OnInit(async (services, token) =>
{
 // Returns false to abort startup
 return true;
});

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

// Service can be injected into the shutdown handler too handler
lambda.OnShutdown(ITelemetryService telemetryService =>
{
 // Runs once at shutdown - great for cleaning up resources
 telemetryService.ForceFlush();
});

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 [FromEvent] 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(([FromEvent] 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(context);
 // Post-handler logic
});

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

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 ILambdaInvocationContext 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(string))]
public partial class SerializerContext : JsonSerializerContext;

Register the serializer context with the application:

using MinimalLambda;

var builder = LambdaApplication.CreateBuilder();

builder.Services.AddLambdaSerializerWithContext<SerializerContext>();

var lambda = builder.Build();

The AddLambdaSerializerWithContext<TContext>() method registers a source-generated JSON serializer that uses your context for all Lambda event and response serialization, providing compile-time serialization metadata and eliminating runtime reflection.

Enable AOT in your project file:

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

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);
 options.ShutdownDuration = ShutdownDuration.ExternalExtensions;
 options.ShutdownDurationBuffer = TimeSpan.FromMilliseconds(100);
 options.ClearLambdaOutputFormatting = true;
});

Available options include timeout control, shutdown duration, output formatting, and JSON serialization customization. The framework automatically registers DefaultLambdaHostJsonSerializer which uses JsonSerializerOptions and JsonWriterOptions for all Lambda serialization. See the configuration guide for details.

Other Packages

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

License

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