LocalStack.Aspire.Hosting 13.1.0

✨ What's New in 13.1.0

This release focuses on alignment with the latest .NET ecosystem updates and significant improvements to our testing infrastructure and reliability.

🚀 Aspire 13.1 & .NET 10 Support

Full compatibility with the latest .NET Aspire 13.1 release and added support for .NET 10.0

• Aspire.Hosting: Updated to 13.1.0
• Target Frameworks: Added net10.0 alongside net8.0 and net9.0

🧪 Modern Testing with TUnit

We've completely modernized our test suite by migrating from xUnit to TUnit. This shift brings:

• Performance: Faster test execution using the Microsoft.Testing.Platform.
• Reliability: Async-first assertions throughout the entire suite.
• Maintainability: Source-generated test discovery for 450+ tests.
• Developer Experience: A more robust foundation for future features.

🛡️ Improved Health Check Reliability

Refined the LocalStackHealthCheck to better handle application shutdown scenarios.

• Fix: OperationCanceledException is now correctly propagated during cancellation, distinguishing it from genuine timeouts.
• Improvement: Added log suppression for localstack_health_client to reduce console noise during startup, keeping your logs clean.

📦 Version Updates

Aspire Alignment:

• Aspire.Hosting: 13.1.0
• Aspire.Hosting.AWS: 9.3.0

LocalStack:

• Container Image: 4.10.0 → 4.12.0

Other:

• TUnit: 1.5.70 (New testing framework)

📚 Documentation Updates

• CONTRIBUTING.md: Updated with guidance on running tests using TUnit, including specific examples for filtering and project selection.

🛠️ Installation

dotnet add package LocalStack.Aspire.Hosting

Note: Package uses namespace Aspire.Hosting.LocalStack for .NET Aspire convention alignment.

Platform Support

• ✅ .NET 8, .NET 9, and .NET 10 support
• ✅ Cross-platform (Windows, Linux, macOS)
• ✅ Integration with LocalStack.NET Client
• ✅ Compatible with official AWS integrations for .NET Aspire

👥 Contributors

We'd like to thank the community for their continued feedback and support in driving these improvements.

📚 Resources

• Documentation: README.md
• Configuration Guide: CONFIGURATION.md
• Examples: Playground
• Contributing: Contributing Guide
• Changelog: CHANGELOG.md

💬 Community & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

🔧 Dependencies

• Aspire.Hosting: 13.1.0
• Aspire.Hosting.AWS: 9.3.0
• LocalStack.Client: 2.0.0
• LocalStack Container: 4.12.0
• .NET 8.0+ required

What's Changed

• Aspire 13.1.0, .NET 10 support, and TUnit migration by @Blind-Striker in #20

Full Changelog: 9.5.3...13.1.0

LocalStack.Aspire.Hosting 9.5.3

✨ What's New in 9.5.3

🏢 Custom Container Registry Support

Pull LocalStack images from private registries, mirrors, or custom sources. Enables enterprise environments with strict security policies to use LocalStack without direct access to public registries.

builder.AddLocalStack(configureContainer: container =>
{
    // Pull from private Artifactory
    container.ContainerRegistry = "artifactory.company.com";
    container.ContainerImage = "docker-local/localstack/localstack";
    container.ContainerImageTag = "4.10.0";
});

Common Scenarios:

• Artifactory, Harbor, Nexus
• Azure Container Registry (ACR)
• AWS Elastic Container Registry (ECR)
• GitHub Container Registry (GHCR)
• Docker Hub mirrors (avoid rate limits)
• Air-gapped environments

#17

🐛 Container Recreation Issue with Persistent Lifetime

Fixed container recreation issue when using ContainerLifetime.Persistent, which caused containers to be destroyed and recreated unnecessarily.

Root Cause: Dynamic port assignment conflicted with persistent container expectations, causing containers to be treated as ephemeral
Solution: Added Port property on LocalStackContainerOptions with smart defaults based on container lifetime
Impact: Persistent containers now maintain state across application restarts with predictable port mapping

builder.AddLocalStack(configureContainer: container =>
{
    // Use Persistent lifetime for container reuse
    container.Lifetime = ContainerLifetime.Persistent;

    // Port defaults to 4566 for Persistent lifetime
    // (Session lifetime uses dynamic ports by default)
});

// Or with explicit port control
builder.AddLocalStack(configureContainer: container =>
{
    container.Lifetime = ContainerLifetime.Persistent;
    container.Port = 4566; // Explicit port assignment
});

Contributed by @nazarii-piontko - #15
Closes: #13

⚠️ Breaking Changes

Default Container Lifetime: Persistent → Session

The default container lifetime has changed from Persistent to Session to align with .NET Aspire conventions and best practices.

What Changed:

Aspect	Before (Persistent)	After (Session)
Container cleanup	Survives app restarts	Cleaned up on stop
Port assignment	Static (4566)	Dynamic (no conflicts)
Best for	Local development	CI/CD, testing

Migration:

// To restore previous Persistent behavior:
builder.AddLocalStack(configureContainer: container =>
{
    container.Lifetime = ContainerLifetime.Persistent;
});

Rationale:

• ✅ Aligns with .NET Aspire's default convention (Session is standard)
• ✅ Better CI/CD experience with clean state guarantees
• ✅ Prevents port conflicts in parallel test scenarios
• ✅ Matches our own documentation recommendations

Technical Details: PR #17

📦 Version Updates

Aspire Alignment:

• Aspire.Hosting: 9.5.2 (unchanged)
• Aspire.Hosting.AWS: 9.2.6 → 9.3.0

LocalStack:

• Container Image: 4.9.2 → 4.10.0

Other:

• SDK Centralization: Aspire.AppHost.Sdk version now centralized in Directory.Build.props
• All analyzer packages updated to latest versions

📚 Documentation Updates

Expanded Configuration Guide

Comprehensive updates to CONFIGURATION.md:

• New: Custom Container Registry - Complete guide with authentication, common scenarios, and troubleshooting
• New: Port Configuration - Default behavior, static vs dynamic ports, conflict resolution
• Updated: Container Lifetime - Reflects new Session default with clear migration path
• Updated: Configuration Patterns - Real-world patterns for Dev/CI/CD/Debugging/Testing

README Enhancements

• Added Version Policy section explaining Aspire version alignment
• Updated container configuration examples with new properties
• Clearer separation of host vs client configuration

🛠️ Installation

dotnet add package LocalStack.Aspire.Hosting

Note: Package uses namespace Aspire.Hosting.LocalStack for .NET Aspire convention alignment.

Platform Support

• ✅ .NET 8 and .NET 9 support
• ✅ Cross-platform (Windows, Linux, macOS)
• ✅ Integration with LocalStack.NET Client (2M+ downloads)
• ✅ Compatible with official AWS integrations for .NET Aspire

👥 Contributors

We'd like to thank the following contributors for their work and feedback on this release:

• @nazarii-piontko - Static port mapping implementation (#15)
• @Blind-Striker - Custom registry support, lifetime alignment, documentation (#17)
• @ArturasPCodes - Feature request: custom registry support (#16)
• @brendonparker - Reported persistent container issue (#13)
• @slang25 - Technical insights on port mapping and container lifetime (#13, #15)

📚 Resources

• Documentation: README.md
• Configuration Guide: CONFIGURATION.md
• Examples: Playground
• Contributing: Contributing Guide
• Changelog: CHANGELOG.md

💬 Community & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: .NET Aspire Discord #aws channel

---

🔧 Dependencies

• Aspire.Hosting: 9.5.2
• Aspire.Hosting.AWS: 9.3.0
• LocalStack.Client: 2.0.0
• LocalStack Container: 4.10.0
• .NET 8.0+ required

What's Changed

• Add static port mapping option by @nazarii-piontko in #15
• Custom Container Registry Support & Lifetime Default Alignment by @Blind-Striker in #17

New Contributors

• @nazarii-piontko made their first contribution in #15
• @ArturasPCodes reported their first issue in #16
• @brendonparker reported their first issue in #13

Full Changelog: 9.5.2...9.5.3

LocalStack.Aspire.Hosting 9.5.2

Stable Release - Full-featured .NET Aspire integration for LocalStack with eager service loading and Docker socket support.

🎉 Graduation to Stable

This release marks the graduation from Release Candidate to stable production release! The API surface is now stable and follows semantic versioning.

✨ What's New in 9.5.2

🚀 Eager Service Loading

Pre-load specific AWS services at container startup for faster, more predictable performance in CI/CD and testing scenarios.

builder.AddLocalStack(configureContainer: container =>
{
    // Eagerly load services for zero cold-start latency
    container.EagerLoadedServices = [AwsService.Sqs, AwsService.DynamoDB, AwsService.S3];
    container.Lifetime = ContainerLifetime.Session;
});

Contributed by @slang25 - #7, #8

🐳 Docker Socket Access

Enable LocalStack Lambda container-based features with configurable Docker socket mounting.

builder.AddLocalStack(configureContainer: container =>
{
    container.EnableDockerSocket = true; // For LocalStack Lambda
});

Closes: #11

🐛 Lambda SQS Event Source Fix

Fixed "Invalid URL" error when Lambda functions use SQS Event Sources with LocalStack.

Root Cause: AWS Lambda Tools process rejected LocalStack endpoints as invalid URLs
Solution: Auto-inject AWS_ENDPOINT_URL environment variable into SQS Event Source resources
Impact: Full LocalStack support for Lambda SQS Event Source triggers

Closes: #6, #9

📦 Version Updates

Aspire Alignment:

• Aspire.Hosting: 9.5.0 → 9.5.2
• Aspire.Hosting.AWS: 9.2.6 (latest stable)
• Aspire.Hosting.Testing: 9.5.0 → 9.5.2

LocalStack:

• Container Image: 4.6.0 → 4.9.2

Other:

• All other packages updated to latest stable
• Analyzers and tooling updated to latest versions

📚 Documentation & Examples

New Configuration Guide

Comprehensive Configuration Guide covering:

• Lazy vs eager loading strategies
• Docker socket configuration
• Container lifetime management
• Logging and debugging options
• Configuration patterns for Dev/CI/CD/Testing
• Troubleshooting guide with real-world scenarios

Enhanced Lambda Playground

Event-driven analytics example demonstrating:

• URL Shortener/Redirector → SQS Queue → Analyzer → DynamoDB
• Async processing with SQS Event Sources
• Real-world serverless patterns

See Lambda Playground for details.

🛠️ Installation

dotnet add package LocalStack.Aspire.Hosting

Note: Package uses namespace Aspire.Hosting.LocalStack for .NET Aspire convention alignment.

Platform Support

• ✅ .NET 8 and .NET 9 support
• ✅ Cross-platform (Windows, Linux, macOS)
• ✅ Integration with LocalStack.NET Client (2M+ downloads)
• ✅ Compatible with official AWS integrations for .NET Aspire

👥 Contributors

We'd like to thank the following contributors for their work on this release:

• @slang25 - Eager service loading feature

📚 Resources

• Documentation: README.md
• Configuration Guide: CONFIGURATION.md
• Examples: Playground
• Contributing: Contributing Guide
• Changelog: CHANGELOG.md

💬 Community & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: .NET Aspire Discord #aws channel

---

🔧 Dependencies

• Aspire.Hosting: 9.5.2
• Aspire.Hosting.AWS: 9.2.6
• LocalStack.Client: 2.0.0
• .NET 8.0+ required

⚠️ Breaking Changes

None - This release maintains full backward compatibility with 9.4.0-rc.1.

What's Changed

• Fix SQS Event Source LocalStack Integration by @Blind-Striker in #9
• Release preparations for v9.5.0 by @Blind-Striker in #10
• Eagerly load services by @slang25 in #8

New Contributors

• @slang25 made his first contribution in #8

Full Changelog: 9.4.0-rc.1...9.5.2

LocalStack.Aspire.Hosting 9.4.0-rc.1

First Release Candidate of LocalStack.Aspire.Hosting - A .NET Aspire integration for LocalStack that enables local AWS development with automatic fallback to real AWS services.

🚀 Key Features

• 🔄 Auto-Configuration: Single UseLocalStack() call configures all AWS resources automatically
• ⚙️ Manual Control: Fine-grained configuration with explicit WithReference() calls
• ☁️ AWS Fallback: Falls back to real AWS services when LocalStack is disabled
• 📦 Full Integration: Works with CloudFormation, CDK stacks, and all AWS project resources

📋 What's Included

Core Capabilities:

• LocalStack container orchestration with configurable lifetime and logging
• Automatic endpoint configuration for all AWS services
• Environment variable transfer to service projects
• Compatible with official AWS integrations for .NET Aspire

Platform Support:

• .NET 8 and .NET 9 support
• Cross-platform (Windows, Linux, macOS)
• Integration with LocalStack.NET Client (2M+ downloads)

Documentation & Examples:

• Complete provisioning examples (SNS, SQS, DynamoDB)
• Serverless examples (Lambda + API Gateway)
• Documentation and configuration guides

🛠️ Installation

dotnet add package LocalStack.Aspire.Hosting

Note: Package uses namespace Aspire.Hosting.LocalStack for .NET Aspire convention alignment.

📖 Quick Start

var builder = DistributedApplication.CreateBuilder(args);

// Add LocalStack container
var localstack = builder.AddLocalStack();

// Add your AWS resources
var awsResources = builder.AddAWSCloudFormationTemplate("resources", "template.yaml");

// Auto-configure everything
builder.UseLocalStack(localstack);

builder.Build().Run();

🎯 RC Status

This Release Candidate is feature-complete. We're seeking community feedback to finalize the API surface before the 1.0 release.

Feedback welcome via:

• GitHub Issues
• GitHub Discussions
• .NET Aspire Discord #aws channel

📚 Resources

• Documentation: README.md
• Examples: Playground
• Contributing: Contributing Guide
• Changelog: CHANGELOG.md

---

🔧 Dependencies

• Aspire.Hosting (9.4.x)
• Aspire.Hosting.AWS (9.2.x)
• LocalStack.Client (2.x)
• .NET 8.0+ required

Breaking Changes: None (initial release)