LocalStack .NET Client

🚀 Quick Start: dotnet add package LocalStack.Client --version 2.0.0 (AWS SDK v4) | Package installation | Migration context

---

🎉 What's New: AWS SDK v4 Support Available

v2.0.0 introduced AWS SDK for .NET v4 compatibility. Service reachability depends on this library's catalog mapping and the capabilities of the LocalStack release and edition you use.

• 🧪 Unit tests, AWS client-construction tests, and container-backed functional tests cover different parts of the library. See the test and CI boundaries rather than relying on a fixed pass count.
• ⚠️ Migration changes include .NET Framework 4.6.2 → 4.7.2 and AWS SDK v3 → v4; see the changelog before upgrading.

Version Strategy:

• v2.x (AWS SDK v4) active development on master branch
• v1.x (AWS SDK v3) remains available on the sdkv3-lts branch, but support ended in July 2026. Use v2.x for maintained releases; see the security policy.

LocalStack.NET is a .NET client library for LocalStack, a local AWS cloud emulator. It configures AWS SDK clients for LocalStack when LocalStack mode is enabled; the same application registration can instead create ordinary AWS clients.

🚀 Platform Compatibility & Quality Status

Supported Platforms

• .NET 8 | .NET 9
• .NET Standard 2.0
• .NET Framework 4.7.2 and Above

⚡ Native AOT & Trimming Status

Heads‑up for dotnet publish -p:PublishAot=true / PublishTrimmed=true users

• The current v2 packages do not support Native AOT. Both client-creation paths still use reflection over AWS SDK internals. Entry points carry [RequiresDynamicCode] and [RequiresUnreferencedCode] annotations where available, and Extensions embeds a linker descriptor for its internal AWS factory; neither guarantees that an application will trim or publish successfully with Native AOT.
• The reflection-free source-generator work is in draft PR #49, not in master. Do not suppress trimming/AOT warnings or adopt an unverified service descriptor on the assumption that this draft has shipped. See the platform boundary.

Build & Test Matrix

Category	Platform/Type	Status	Description
🔧 Build	Cross-Platform		Matrix testing: Windows, Linux, macOS
🔒 Security	Static Analysis		CodeQL analysis & dependency review
🧪 Tests	Linux		All framework targets
🧪 Tests	Windows		All framework targets
🧪 Tests	macOS		All framework targets

Package Status

Package	NuGet.org	GitHub Packages (development builds)
LocalStack.Client v1.x
LocalStack.Client v2.x
LocalStack.Client.Extensions v1.x
LocalStack.Client.Extensions v2.x

Table of Contents

1. Supported Platforms
2. Why LocalStack.NET Client?
3. Prerequisites
4. Getting Started
   • Setup
   • Configuration
5. Known Issues
6. Developing
   • Building the Project
   • Sandbox Applications
   • Running Tests
7. Changelog
8. License

Why LocalStack.NET Client?

• Consistent Client Configuration: LocalStack.NET eliminates the need for manual endpoint configuration, providing a standardized and familiar approach to initializing clients.

• Adaptable Environment Transition: Easily switch between LocalStack and actual AWS services with minimal configuration changes.

• Versatile .NET Compatibility: Both packages target .NET 8, .NET 9, and .NET Standard 2.0; Core also has an explicit .NET Framework 4.7.2 target. See platform and packaging for the exact project targets.

• Reduced Learning Curve: Offers a familiar interface tailored for LocalStack, ideal for developers acquainted with the AWS SDK for .NET.

• Enhanced Development Speed: Reduces boilerplate and manual configurations, speeding up the development process.

Prerequisites

To utilize this library, you need to have LocalStack running. While LocalStack can be installed directly on your machine and accessed via the localstack cli, the recommended approach is to run LocalStack using Docker or docker-compose.

For detailed installation and setup instructions, please refer to the official LocalStack installation guide.

Getting Started

LocalStack.NET is available through multiple package sources to support different development workflows.

📦 Package Installation

To install the latest version of LocalStack.NET with AWS SDK v4 support, use the following command:

# Install the published v2 releases with AWS SDK v4 support
dotnet add package LocalStack.Client --version 2.0.0
dotnet add package LocalStack.Client.Extensions --version 2.0.1

Development Builds (GitHub Packages)

For testing 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 \
  --username YOUR_GITHUB_USERNAME \
  --password YOUR_GITHUB_TOKEN

# Install development packages
dotnet add package LocalStack.Client --prerelease --source github-localstack
dotnet add package LocalStack.Client.Extensions --prerelease --source github-localstack

🔑 GitHub Packages Authentication: You'll need a GitHub account and Personal Access Token with read:packages permission.

Refer to documentation for more information on how to install LocalStack.NET.

LocalStack.NET is a library that provides a wrapper around the aws-sdk-net. This means you can use it in a similar way to the AWS SDK for .NET and to AWSSDK.Extensions.NETCore.Setup with a few differences. For more on how to use the AWS SDK for .NET, see Getting Started with the AWS SDK for .NET.

Setup

Here's a basic example of how to setup LocalStack.NET:

public void ConfigureServices(IServiceCollection services)
{
    // Add framework services.
    services.AddMvc();

    services.AddLocalStack(Configuration);
    services.AddDefaultAWSOptions(Configuration.GetAWSOptions());
    services.AddAwsService<IAmazonS3>();
    services.AddAwsService<IAmazonDynamoDB>();
}

AddLocalStack binds configuration and registers the library's services. AddAwsService registers the AWS service interface; LocalStack:UseLocalStack selects whether that interface is created through the LocalStack session or the ordinary AWS SDK factory. The default is false. See client runtime and service support for what the endpoint catalog does—and does not—promise.

(Alternatively, AddAWSServiceLocalStack method can be used to prevent mix-up with AddAWSService.)

AddLocalStack extension method is responsible for both configurations and adding of LocalStack.Client dependencies to service collection.

Configuration

To configure LocalStack.NET, you can use entries in the appsettings.json files. Here's a basic example for different environments:

appsettings.Development.json

"LocalStack": {
    "UseLocalStack": true,
    "Session": {
        "RegionName": "eu-central-1"
    },
    "Config": {
        "LocalStackHost": "localhost.localstack.cloud", // or "localhost",
        "EdgePort": 4566
    }
}

appsettings.Production.json

"LocalStack": {
    "UseLocalStack": false
},
"AWS": {
    "Profile": "<your aws profile>",
    "Region": "eu-central-1"
}

The RegionName is important as LocalStack creates resources based on the specified region. For more advanced configurations and understanding how LocalStack.NET operates with LocalStack, refer to documentation.

Known Issues

• LocalStackClientConfigurationException on LocalStack.Client.Extensions v2.0.0 and earlier: If UseLocalStack is false and AWSSDK.Extensions.NETCore.Setup resolves to 4.0.4 or newer, client creation throws LocalStackClientConfigurationException. AWS changed an internal ClientFactory<T> constructor in 4.0.4; the new parameter is optional, so it shipped as a patch release and is source-compatible on their side, but it is binary-breaking for the reflection lookup used here. Because v2.0.0 declares AWSSDK.Extensions.NETCore.Setup >= 4.0.2, NuGet floats new installs straight onto the broken versions. Only the UseLocalStack: false path is affected — LocalStack-only usage never reaches this code. Fixed in v2.0.1, so upgrading is the recommended fix. If you cannot upgrade yet, pin the AWS package to the last working version, which v2.0.0's range still allows:

  <PackageReference Include="AWSSDK.Extensions.NETCore.Setup" Version="4.0.3.40" />

  See issue #52 for the full analysis.

• SNS with LocalStack v3.7.2 and v3.8.0: During development on the new version, it was discovered that SNS functional tests are not working in LocalStack versions v3.7.2 and v3.8.0. This issue was reported in LocalStack issue #11652. The LocalStack team identified a bug related to handling SNS URIs and resolved it in PR #11653. The fix will be included in an upcoming release of LocalStack. In the meantime, if you're using SNS, it is recommended to stick to version v3.7.1 of LocalStack until the fix is available.

• LocalStack Versions v2.0.1 - v2.2: In versions v2.0.1 through v2.2 of LocalStack, the URL routing logic was changed, causing issues with SQS and S3 operations. Two issues were opened in LocalStack regarding this: issue #8928 and issue #8924. LocalStack addressed this problem with PR #8962. Therefore, when using LocalStack.NET, either use version v2.0 of LocalStack (there are no issues with the v1 series as well) or the upcoming v2.3 version, or use the latest v3 series container from Docker Hub.

• Endpoint environment variables: Issue #27 records a 2026-07-10 SQS observation against Extensions 2.0.0. With UseLocalStack=true, a LocalStack proxy aimed at A and AWS_ENDPOINT_URL aimed at B sent traffic to A. With UseLocalStack=false, the proxy was unset and traffic followed B. This is a dated report, not a re-run against every SDK or service; the issue remains open and no general precedence fix is merged. AWS_SERVICE_URL can also appear in Lambda environments, but this library does not define a general override rule for it. Diagnose the actual SDK configuration before adopting an environment-variable workaround.

• IAmazonLambda Operations: There's a general issue with IAmazonLambda operations. This matter is currently under investigation.

• AWSSDK.SQS Compatibility: Starting from version 3.7.300.* of AWSSDK.SQS, there are compatibility issues with LocalStack v1 and v2 series versions. The v3 series of LocalStack does not have these issues. Therefore, it is recommended to either update your LocalStack container to the v3 series or downgrade your AWSSDK.SQS to version 3.7.200.* if you are using LocalStack v1 or v2 series containers. It is important to note that this is not a problem related to LocalStack.NET, but rather an issue with the LocalStack container and the AWS SDK for .NET.

Developing

We appreciate contributions in the form of feedback, bug reports, and pull requests.

Building the Project

To build the project, use the following commands based on your operating system:

Windows

build.ps1

Linux

./build.sh

On Unix, this Cake script runs an initialization task that changes your global Git core.autocrlf setting. Read the quality gates before running it on a shared machine.

Sandbox Applications

The LocalStack .NET repository includes several sandbox console applications located in tests/sandboxes. These applications serve both as testing tools and as examples. Refer to the documentation for more information

Running Tests

To execute the tests, use the commands below:

Windows

build.ps1 --target=tests

Linux

./build.sh --target=tests

Community

Got questions or wild feature ideas?

👉 Join the conversation in GitHub Discussions.

Changelog

Please refer to CHANGELOG.md to see the complete list of changes for each release.

License

Licensed under MIT, see LICENSE for the full text.