AWS SDK v4 Support Update – v2.0.0 GA Released

Exciting news! The v2.0.0 GA is now live on NuGet and GitHub Packages - released earlier than expected with complete AWS SDK v4 support!

Native AOT Update: GA ships without Native AOT support as planned.
The reflection‑free path is actively being developed and targeted for v2.1 in the coming months.
Follow progress in draft‑PR #49.

✅ What's Available Now - GA Released

• 📦 Production NuGet Packages:
  • LocalStack.Client v2.0.0 GA
  • LocalStack.Client.Extensions v2.0.0 GA
• 🎯 Production Ready: Fully tested and ready for production workloads
• 🧪 Comprehensive Testing: 1168 tests passing across all target frameworks
• 🔄 Minimal Breaking Changes: Only .NET Framework requirement change (4.6.2 → 4.7.2)
• 📘 Unchanged Public APIs: Your existing code should work without modification!
• 🌟 Early Release: Released ahead of schedule due to excellent stability

🚀 Quick Start

# Install the GA packages - production ready!
dotnet add package LocalStack.Client --version 2.0.0
dotnet add package LocalStack.Client.Extensions --version 2.0.0

Looking Ahead

TL;DR (Updated)

• AWS SDK v4 broke LocalStack .NET Client v1.x due to internal API changes
• ✅ SOLVED: v2.0.0 GA now available with full AWS SDK v4 support
• Two-track strategy: v1.x maintenance in sdkv3-lts branch + v2.0 with full AWS SDK v4 support
• Timeline: ✅ v2.0.0 GA RELEASED ahead of schedule (July 25, 2025)
• Native AOT support coming in v2.1 – follow PR #49

Original Challenge & Solution

Hi everyone! 👋

First, a huge thank you to everyone who raised issues regarding the recent release of the AWS SDK for .NET v4. I know this was a critical blocker for many of you, and I appreciate your patience while I investigated the full scope of the changes.

What Happened

AWS SDK v4 introduced significant breaking changes that went beyond what I initially anticipated. While the most visible issue was in the dependency injection extensions (the ClientFactory becoming generic), the core library's extensive use of reflection against AWS SDK internals created additional risk areas.

See the issues: #42, #44

The potentially affected areas included:

• Service metadata extraction: Private field access patterns
• Client configuration creation: Constructor reflection
• Client instantiation: Type discovery mechanisms
• Property manipulation: Dynamic property setting

Rather than ship a quick fix that only addressed the visible startup crash, I made the strategic decision to take the time to properly test and validate all these reflection points.

My Decision: Quality Over Speed

I believed users deserve a high-quality, reliable solution rather than a band-aid fix. Therefore, I made the strategic decision to skip the temporary patch and go straight to a proper major version release that fully embraces AWS SDK v4.

The Plan: Two-Track Strategy for Smooth Transition

To serve both existing users and those migrating to the new SDK, I officially moved to a two-track maintenance model:

🛡️ The v1.x Line (AWS SDK v3 - Maintenance Mode)

• Status: Maintenance Mode
• Branch: sdkv3-lts branch
• Support: Critical bug fixes and security patches only
• End of Life: July 31, 2026
• Target Users: Teams staying on AWS SDK v3 for now

🚀 The v2.x Line (AWS SDK v4 - The Future)

• Status: ✅ GA RELEASED
• Branch: master branch
• Features:
  • ✅ Native AWS SDK v4 Support: Built and tested from the ground up
  • 🔧 Modern .NET Patterns: Taking advantage of latest .NET features
  • 📦 Same Great API: Familiar interface with improved internals
  • 🏎️ Future: Native AOT Ready: Planned for v2.1 in coming months

Final Timeline & Milestones

Migration Guidance

📋 If you're currently on AWS SDK v3:

• Recommended: Stay on LocalStack .NET v1.x until you're ready to upgrade both
• Support: You'll receive critical fixes until July 2026
• Planning: Use this time to plan your migration strategy

⚡ If you need AWS SDK v4 now:

• ✅ Available Now: Install v2.0.0 GA from NuGet or GitHub Packages
• 🚀 Easy Migration: Public APIs unchanged, minimal breaking changes
• 🧪 Production Ready: 1,168+ tests passing across all frameworks
• 📋 Requirements: Ensure .NET Framework 4.7.2+ and AWS SDK v4 packages

🔄 Migration from v1.x to v2.x:

• ✅ Simplified Process: Much easier than initially anticipated!
• 📘 API Compatibility: Public APIs remain unchanged - your code should work as-is
• 🔧 Main Changes:
  • Update to .NET Framework 4.7.2 (from 4.6.2) if using .NET Framework
  • Update AWS SDK packages to v4.x series
  • Update LocalStack.Client packages to v2.0.0
• 📖 Documentation: See CHANGELOG.md for complete details

Why This Approach Benefited You

🎯 Quality & Reliability

• No rushed fixes that could break in production
• Comprehensive testing against AWS SDK v4 across all supported services
• Clean architecture without legacy compatibility hacks

⚡ Performance & Modern Features

• Improved reliability and stability with AWS SDK v4
• Coming Soon: Native AOT support for faster cold starts and smaller deployments

🛣️ Clear Migration Path

• Predictable timeline and milestones (delivered early!)
• Side-by-side version support during transition

What's Different in v2.0

🔧 Under the Hood

• AWS SDK v4 Compatibility: Full support for new SDK internal structures
• Improved Reliability: Comprehensive testing with 1,168+ tests passing
• Modern .NET Features: Taking advantage of latest .NET capabilities
• Future Optimization: Reflection removal and AOT support planned for v2.1

📦 API Changes

• ✅ Same Core Experience: Familiar AddLocalStack() and service registration patterns unchanged
• ✅ No Breaking API Changes: Your existing code should work without modification
• 🔧 Framework Requirement: .NET Framework 4.7.2+ now required (upgrade from 4.6.2)
• 📦 Package Dependencies: AWS SDK v4 packages now required

🏗️ Architecture

• Proven Compatibility: Successfully tested against LocalStack v3.7.1 and v4.6.0
• Cleaner Implementation: Better internal structure while maintaining public API compatibility
• Future Proof: Designed to handle future AWS SDK changes more gracefully

Commitment to the Community

This transition represents our commitment to providing you with:

• Long-term Support: Clear support lifecycle for both version lines
• Quality Software: Well-tested, reliable releases over quick fixes
• Transparent Communication: Regular updates on progress and timeline
• Early Delivery: Released GA ahead of schedule due to excellent stability

Next Steps

1. ✅ COMPLETED: sdkv3-lts branch creation and v1.x freeze
2. ✅ COMPLETED: v2.0.0-preview1 released on NuGet and GitHub Packages
3. ✅ COMPLETED: v2.0.0 GA released early (July 25, 2025)
4. 🔄 ONGOING: Community adoption and feedback
5. 📋 UPCOMING: v2.1 development with Native AOT support

Questions & Discussion

This announcement thread will serve as the central place for:

• Questions about the migration strategy
• Feedback on the GA release
• Early testing coordination for v2.1 AOT features
• Migration planning discussions

I'm here to help make this transition as smooth as possible for everyone. Don't hesitate to ask questions or share your specific requirements!

Thank you for your continued support of LocalStack .NET Client.

Key Links:

• 📋 Current v1.x (stable): NuGet Package
• 🔧 v1.x Maintenance Branch: sdkv3-lts
• 🚀 v2.0.0 GA (AWS SDK v4): NuGet Package
• 📦 v2.x GitHub Packages: GitHub Packages
• 📖 Project Documentation: GitHub Wiki
• 📋 Full Changelog: CHANGELOG.md

This announcement has been updated to reflect the successful GA release on July 25, 2025.