.NET Aspire integration for LocalStack - enables local AWS service development and testing with auto-configuration, container orchestration, and full compatibility with Aspire.Hosting.AWS patterns.
$ dotnet add package LocalStack.Aspire.Hosting
A .NET Aspire hosting integration for LocalStack that enables local development and testing of cloud applications using AWS services. This package extends the official AWS integrations for .NET Aspire to provide LocalStack-specific functionality.
dotnet add package LocalStack.Aspire.HostingPackage Note: The package is named
LocalStack.Aspire.Hostingbut uses the namespaceAspire.Hosting.LocalStackto align with .NET Aspire hosting conventions. This ensures consistency with other Aspire hosting integrations while maintaining a unique package identity.
Requirements: .NET 8.0 or later (supports both .NET 8 and .NET 9)
For access to the latest features and bug fixes:
# Add GitHub Packages source
dotnet nuget add source https://nuget.pkg.github.com/localstack-dotnet/index.json \
--name github-localstack-for-aspire \
--username YOUR_GITHUB_USERNAME \
--password YOUR_GITHUB_TOKEN
# Install development packages
dotnet add package LocalStack.Aspire.Hosting --prerelease --source github-localstack-for-aspireNote: GitHub Packages requires a Personal Access Token with
read:packagespermission.
💡 Prefer learning by example? Check out our complete working examples in the playground (CloudFormation, CDK, Lambda). Clone, run, explore - then come back here for configuration details.
When LocalStack is disabled in configuration, both host and client configurations automatically fall back to real AWS services without requiring code changes. The LocalStack.NET Client automatically switches to AWS's official client factory when LocalStack is not enabled.
Configure LocalStack integration in your Aspire AppHost project using auto-configuration:
var builder = DistributedApplication.CreateBuilder(args);
// 1. Set up AWS SDK configuration (optional)
var awsConfig = builder.AddAWSSDKConfig()
.WithProfile("default")
.WithRegion(RegionEndpoint.USWest2);
// 2. Add LocalStack container
var localstack = builder
.AddLocalStack(awsConfig: awsConfig, configureContainer: container =>
{
container.Lifetime = ContainerLifetime.Session;
container.DebugLevel = 1;
container.LogLevel = LocalStackLogLevel.Debug;
});
// 3. Add your AWS resources as usual
var awsResources = builder.AddAWSCloudFormationTemplate("resources", "template.yaml")
.WithReference(awsConfig);
var project = builder.AddProject<Projects.MyService>("api")
.WithReference(awsResources);
// 4. Auto-configure LocalStack for all AWS resources
builder.UseLocalStack(localstack);
builder.Build().Run();The UseLocalStack() method automatically:
The configureContainer parameter allows you to customize LocalStack container behavior. By default, LocalStack uses lazy loading - services start only when first accessed. For faster startup in CI or when you know which services you need, configure eager loading:
builder.AddLocalStack(configureContainer: container =>
{
// Eagerly load specific services for faster startup
container.EagerLoadedServices = [AwsService.Sqs, AwsService.DynamoDB, AwsService.S3];
// Recommended: Clean up container when application stops
container.Lifetime = ContainerLifetime.Session;
// Optional: Enable verbose logging for troubleshooting
container.DebugLevel = 1;
container.LogLevel = LocalStackLogLevel.Debug;
});Available Options:
EagerLoadedServices - Pre-load specific AWS services at startup (reduces cold start latency)Lifetime - Container lifecycle: Persistent (survives restarts) or Session (cleaned up on stop)DebugLevel - LocalStack debug verbosity (0 = default, 1 = verbose)LogLevel - Log level control (Error, Warn, Info, Debug, Trace, etc.)AdditionalEnvironmentVariables - Custom environment variables for advanced scenariosFor detailed configuration guide and best practices, see Configuration Documentation.
For fine-grained control, you can manually configure each resource:
var awsResources = builder.AddAWSCloudFormationTemplate("resources", "template.yaml")
.WithReference(localstack) // Manual LocalStack reference
.WithReference(awsConfig);
var project = builder.AddProject<Projects.MyService>("api")
.WithReference(localstack) // Manual project reference
.WithReference(awsResources);Configure AWS services in your service projects using LocalStack.NET Client (2M+ downloads, production-tested):
var builder = WebApplication.CreateBuilder(args);
// Add LocalStack configuration
builder.Services.AddLocalStack(builder.Configuration);
// Register AWS services - automatically configured for LocalStack when enabled
builder.Services.AddAwsService<IAmazonS3>();
builder.Services.AddAwsService<IAmazonDynamoDB>();
builder.Services.AddAwsService<IAmazonSNS>();
var app = builder.Build();This configuration automatically detects if LocalStack is enabled and configures the AWS SDK clients accordingly. If LocalStack is not enabled, it falls back to the official AWS SDK configuration without requiring code changes.
(Alternatively,
AddAWSServiceLocalStackmethod can be used to prevent mix-up with AddAWSService.
For more details on client configuration options, see the LocalStack.NET Client documentation.
The LocalStack.Aspire.Hosting host automatically transfers LocalStack configuration to service projects via environment variables. This works with the standard .NET configuration hierarchy: appsettings.json files -> Environment variables (can override appsettings) -> Command line arguments
Important: Ensure your service projects include the EnvironmentVariablesConfigurationProvider in the correct order for automatic configuration to work.
UseLocalStack() call automatically detects and configures all AWS resourcesWithReference() calls for each resourceBoth examples demonstrate auto-configuration and manual configuration approaches.
LocalStack is a cloud service emulator that runs in a single container on your laptop or in your CI environment. It provides a fully functional local AWS cloud stack, allowing you to develop and test your cloud applications offline.
We welcome contributions from the community! Here's how you can get involved:
For detailed contribution guidelines, development setup, and coding standards, see our Contributing Guide.
See CHANGELOG.md for a detailed history of changes, new features, and breaking changes for each release.
This project is licensed under the MIT License - see the LICENSE file for details.