LocalStack.Aspire.Hosting 13.6.0

dotnet add package LocalStack.Aspire.Hosting --version 13.6.0
                    
NuGet\Install-Package LocalStack.Aspire.Hosting -Version 13.6.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="LocalStack.Aspire.Hosting" Version="13.6.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="LocalStack.Aspire.Hosting" Version="13.6.0" />
                    
Directory.Packages.props
<PackageReference Include="LocalStack.Aspire.Hosting" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add LocalStack.Aspire.Hosting --version 13.6.0
                    
#r "nuget: LocalStack.Aspire.Hosting, 13.6.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package LocalStack.Aspire.Hosting@13.6.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=LocalStack.Aspire.Hosting&version=13.6.0
                    
Install as a Cake Addin
#tool nuget:?package=LocalStack.Aspire.Hosting&version=13.6.0
                    
Install as a Cake Tool

.NET Aspire Integrations for LocalStack

License: MIT NuGet Version Github Packages CI/CD Pipeline Security Linux Tests

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.

Installation

dotnet add package LocalStack.Aspire.Hosting

Package Note: The package is named LocalStack.Aspire.Hosting but uses the namespace Aspire.Hosting.LocalStack to 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 .NET 8, .NET 9, and .NET 10)

Development Builds

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-aspire

Note: GitHub Packages requires a Personal Access Token with read:packages permission.

Note: NuGet can only encrypt stored credentials on Windows. On Linux and macOS add --store-password-in-clear-text, which writes the token unencrypted into your NuGet config.

Version Policy

This package follows Aspire's major.minor versioning but releases patch versions independently.

  • 9.5.x works with Aspire 9.5.x
  • 13.1.x works with Aspire 13.1.x
  • 13.4.x works with Aspire 13.4.x
  • 13.6.x works with Aspire 13.6.x

We may ship features and fixes between Aspire releases. When upgrading Aspire's minor version, upgrade this package to match.

Usage

💡 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 explicitly disabled, this integration leaves resources on the official AWS path, which may require real AWS credentials. This is different from an enabled LocalStack runtime missing activation: that is an error, never an automatic switch to AWS or downgrade to an older image.

Host Configuration (AppHost)

Configure LocalStack integration in your Aspire AppHost project using the package-owned hosting API:

Since 13.6.0 the package defaults to a qualified current LocalStack image, which requires LOCALSTACK_AUTH_TOKEN from secure AppHost configuration and suitable LocalStack entitlement. AWS access keys in the example are separate from this activation token. See runtime selection and activation for deferred secret parameters, precedence, custom images and the explicit token-free container.WithLegacy() compatibility preset. Legacy runtime selection is not the obsolete Client-shaped hosting API, and does not promise new-feature parity.

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 with hosting options
var localStack = builder.AddLocalStack(
    "localstack",
    awsConfig,
    options => options
        .WithEnabled(true)
        .WithCredentials("accessKey", "secretKey", "token"),
    container => container.Lifetime = ContainerLifetime.Session);

// 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();

Region precedence: the region comes from awsConfig here (us-west-2), which is why the options callback does not set one. Resolution order, lowest to highest, is defaults → legacy LocalStack:* → canonical Aspire:Hosting:LocalStack:* → the configureOptions callback → IAWSSDKConfig.Region, so an awsConfig region, when one is set, wins over .WithRegion(...).

Simpler configurations are also supported:

// Minimal: everything from configuration
var localStack = builder.AddLocalStack();

// Named resource
var localStack = builder.AddLocalStack("localstack");

// Named resource with AWS config and container options
var localStack = builder.AddLocalStack("localstack", awsConfig,
    configureContainer: container => container.Lifetime = ContainerLifetime.Session);

LocalStack is opt-in. Enabled defaults to false, so an AddLocalStack call that is not explicitly enabled returns null, UseLocalStack(null) becomes a no-op, and no container starts. Enable it with Aspire:Hosting:LocalStack:Enabled=true (or the legacy LocalStack:UseLocalStack=true), or by calling .WithEnabled(true) in a configureOptions callback.

The UseLocalStack() method automatically:

  • Detects all AWS resources (CloudFormation, CDK stacks)
  • Configures LocalStack endpoints for all AWS services and project resources
  • Sets up proper dependency ordering and CDK bootstrap if needed
  • Transfers LocalStack configuration to service projects via environment variables
AppHost Configuration

Host-level LocalStack settings use the canonical configuration section Aspire:Hosting:LocalStack:

{
  "Aspire": {
    "Hosting": {
      "LocalStack": {
        "Enabled": true,
        "Region": "us-east-1",
        "AccessKeyId": "accessKey",
        "SecretAccessKey": "secretKey",
        "SessionToken": "token"
      }
    }
  }
}

Environment variable equivalents use standard double-underscore naming:

Aspire__Hosting__LocalStack__Enabled=true
Aspire__Hosting__LocalStack__Region=us-east-1

Migration note: The legacy LocalStack:* section (e.g. "LocalStack": { "UseLocalStack": true }) remains supported for backward compatibility. Canonical Aspire:Hosting:LocalStack:* settings take precedence when both are present.

Container Configuration

The configureContainer parameter customizes container behavior. Lazy loading starts services when first accessed; eager loading requests preloading and adds required-service health checks. Backend dependencies and provider policy also affect the enabled set:

builder.AddLocalStack("localstack", awsConfig: null, configureContainer: container =>
{
    // Eagerly load specific services for faster startup
    container.EagerLoadedServices = [AwsService.Sqs, AwsService.DynamoDb, AwsService.S3];

    // Optional: Use Persistent lifetime for container reuse between runs
    // (Default is Session - container cleaned up when application stops)
    container.Lifetime = ContainerLifetime.Persistent;

    // Optional: Enable verbose logging for troubleshooting
    container.DebugLevel = 1;
    container.LogLevel = LocalStackLogLevel.Debug;

    // Optional: Use a specific port instead of dynamic port assignment
    container.Port = 4566;
});

Available Options:

  • EagerLoadedServices - Request preloading and require these services to report running before health succeeds
  • Lifetime - Container lifecycle: Session (default - cleaned up on stop) or Persistent (survives restarts)
  • DebugLevel - LocalStack debug verbosity (0 = default, 1 = verbose)
  • LogLevel - Log level control (Error, Warn, Info, Debug, Trace, etc.)
  • Port - Static port mapping for LocalStack container. If not set, Session lifetime uses dynamic ports (avoids conflicts) and Persistent lifetime uses port 4566 (default LocalStack port). Set explicitly for predictable endpoint URLs
  • ContainerRegistry - Custom container registry (default: docker.io). Use when pulling from private registries
  • ContainerImage - Custom image name (default: localstack/localstack). Use when image is mirrored with different path
  • ContainerImageTag - Override the selected runtime preset's tag; registry/image/tag overrides remain independent and win over preset selection
  • EnableDockerSocket - Mounts /var/run/docker.sock so LocalStack can start its own containers (required for LocalStack Lambda support; default: false, and it carries security implications)
  • AdditionalEnvironmentVariables - Custom environment variables for advanced scenarios

Enabled, preloaded and health-required services are different sets. The package emits EAGER_SERVICE_LOADING=1 and SERVICES=<list>, and requires every requested service to report running. Backend provider availability, mandatory dependencies and strict-loading settings can change the enabled set; this is not a guarantee that every unlisted service is unavailable. See service loading.

For detailed configuration guide and best practices, see Configuration Documentation.

Manual Configuration

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);

Client Configuration (Service Projects)

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<IAmazonSimpleNotificationService>();

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, AddAWSServiceLocalStack can be used to prevent mix-up between LocalStack.Client's AddAwsService and the AWS SDK's AddAWSService.

For more details on client configuration options, see the LocalStack.NET Client documentation.

Configuration Integration

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.

Features

  • Auto-Configuration: Single UseLocalStack() call automatically detects and configures all AWS resources
  • Manual Configuration: Fine-grained control with explicit WithReference() calls for each resource
  • AWS Service Integration: Works with CloudFormation templates, CDK stacks, and AWS service clients
  • Automatic Fallback: Falls back to real AWS services when LocalStack is disabled
  • Container Lifecycle Management: Configurable container with session/persistent lifetime options
  • Eager Service Loading: Pre-load specific AWS services for faster startup in CI/CD environments
  • Extension-Based: Works alongside official AWS integrations for .NET Aspire without code changes
  • Lambda Event Sources: SQS and DynamoDB Streams event-source emulators (WithSQSEventSource, WithDynamoDBStreamsEventSource) are automatically wired to LocalStack

Known Limitations

  • AddAWSDynamoDBLocal cannot be combined with UseLocalStack(). DynamoDB Local and LocalStack's DynamoDB are competing backends — data written to one is invisible to the other — so UseLocalStack() fails fast with a clear error instead of silently splitting DynamoDB state. Model DynamoDB through the CDK/CloudFormation path so LocalStack serves it, or drop UseLocalStack() to keep DynamoDB Local. Complementary compute emulators (Lambda, API Gateway, SQS/DynamoDB Streams pollers) remain fully supported.
  • DynamoDB Streams event sources currently require us-east-1. The AWS Lambda Test Tool's bundled AWS SDK signs requests for us-east-1 whenever a custom endpoint (such as LocalStack) is configured, regardless of the configured region. LocalStack namespaces resources per signing region, so the stream poller only finds tables deployed to us-east-1. This is an upstream SDK defect; this package's configuration is correct and needs no change once the upstream fix ships. SQS event sources are not affected.
  • Do not combine LocalStack.Client proxy configuration with AWS_ENDPOINT_URL*. If LocalStack__UseLocalStack=true, LocalStack.Client configures an AWS SDK proxy. Native endpoint variables can also populate ClientConfig.ServiceURL, creating a mixed configuration where traffic follows the Client proxy while signing behavior follows the custom endpoint. On affected AWSSDK.Core versions, a request configured for a non-default region can silently be signed for us-east-1. This package does not automatically emit, remove, or overwrite AWS_ENDPOINT_URL* values on your service projects or AWS resources. (The internal SQS and DynamoDB Streams event-source helper resources are the exception: they are external Lambda Test Tool processes with no LocalStack.Client, so they are routed through AWS_ENDPOINT_URL* by design.) Use either the LocalStack.Client integration or an explicit native AWS SDK endpoint setup, not both. Bare AWS SDK custom-endpoint users are also subject to the upstream signing-region defect. See LocalStack.Client #27 for the verified runtime matrix.
  • The conflict warning is best-effort. When the package can observe coexistence of LocalStack.Client proxy configuration and native AWS_ENDPOINT_URL* variables on the same workload, it emits a read-only warning via the resource logger. The warning does not add, remove, or overwrite environment values, and it sees the LocalStack__* settings the package adds to a referenced workload. It cannot observe environment callbacks appended after the package adapts that workload, which happens when the LocalStack connection string becomes available.

Examples

Complete Working Examples

Both examples demonstrate auto-configuration and manual configuration approaches.

What is LocalStack?

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.

Contributing

We welcome contributions from the community! Here's how you can get involved:

  • Try it out: Clone the repository and test the playground examples
  • Report issues: Share bugs or feature requests via GitHub issues
  • Submit improvements: Pull requests for enhancements and bug fixes
  • Share feedback: Join discussions about the implementation and roadmap

For detailed contribution guidelines, development setup, and coding standards, see our Contributing Guide.

Changelog

See CHANGELOG.md for a detailed history of changes, new features, and breaking changes for each release.

  • Aspire - Aspire is a unified toolchain that simplifies building, debugging, and deploying observable, production-ready distributed apps through a code-first app model.
  • AWS Integrations for .NET Aspire - Official AWS integrations that this project extends
  • LocalStack .NET Client - The .NET client library for LocalStack that we integrate with

License

This project is licensed under the MIT License - see the LICENSE file for details.

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
13.6.0 433 11/15/2026
13.4.0 55,013 7/9/2026
13.1.0 253,763 12/19/2025
9.5.3 7,755 11/5/2025
9.5.2 2,598 10/27/2025
9.4.0-rc.1 27,931 8/7/2025