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