diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index fcd6758..1a56131 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -22,12 +22,10 @@ This project follows the [.NET Foundation Code of Conduct](CODE_OF_CONDUCT.md). ## 🎯 Version Strategy -We maintain a **dual-track versioning strategy**: +New work targets `master` (3.x): -- **v2.x (AWS SDK v4)** - Active development on [`master`](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/master) branch -- **v1.x (AWS SDK v3)** - The [`sdkv3-lts`](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/sdkv3-lts) branch preserves published releases but is no longer supported; its maintenance window ended in July 2026. See the [security policy](SECURITY.md). +- **3.x (AWS SDK v4)** - Current development on [`master`](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/master). Earlier versions are not supported; see the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md). -New changes target v2.x on `master`. The v1.x branch is not accepting maintenance fixes. ## 🚀 Getting Started @@ -53,22 +51,33 @@ New changes target v2.x on `master`. The v1.x branch is not accepting maintenanc 2. **Build the Project** - ```bash + ```powershell # Windows .\build.ps1 - - # Linux/macOS + ``` + + ```bash + # Linux/macOS ./build.sh ``` 3. **Run Tests** - ```bash + ```powershell # Default unit and client-construction tests (functional tests are skipped) .\build.ps1 --target tests ``` - Functional tests are opt-in and start LocalStack containers through Testcontainers, so they need a running Docker engine. The tests against the current LocalStack image also need a `LOCALSTACK_AUTH_TOKEN` environment variable; without one, exclude them as [quality gates](../docs/engineering/quality-gates.md) describes. + ```bash + # Linux/macOS + ./build.sh --target tests + ``` + + Functional tests are opt-in and start LocalStack containers through Testcontainers, so they need a running Docker engine. The tests against the current LocalStack image also need a `LOCALSTACK_AUTH_TOKEN` environment variable; without one, exclude them as [quality gates](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/engineering/quality-gates.md) describes. + +### Sandbox Applications + +The LocalStack .NET repository includes several sandbox console applications in [tests/sandboxes](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/master/tests/sandboxes). These applications serve as testing tools and examples. ## 🐛 Reporting Issues @@ -142,7 +151,7 @@ We love new ideas! Here's how to suggest features: - Use our [PR Template](https://github.com/localstack-dotnet/localstack-dotnet-client/compare) - Provide clear description of changes - Link related issues - - Target the supported v2.x line + - Target the current 3.x line on `master` ### Code Quality Standards diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 987403e..7034cf5 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -30,23 +30,25 @@ A clear and concise description of what you expected to happen. ## 📋 Environment Information -**LocalStack.Client Version:** +**Package Versions:** -- [ ] v1.x (AWS SDK v3) - Unsupported historical release -- [ ] v2.x (AWS SDK v4) - Current Branch -- Version: +- LocalStack.Client version: +- LocalStack.Client.Extensions version (if used): -The v1.x maintenance window ended in July 2026; new fixes target v2.x. See the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md). +Fixes target the supported 3.x line. See the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md). **LocalStack Information:** - LocalStack Version: -- LocalStack Image: (e.g., `localstack/localstack:4.14.0` or `localstack/localstack:2026.10.2`) +- LocalStack image tag: (e.g., `localstack/localstack:4.14.0` or `localstack/localstack:2026.10.2`) - LocalStack Services Used: (e.g., S3, DynamoDB, SNS) **.NET Information:** - .NET Version: (e.g., .NET 8, .NET Framework 4.7.2) +- Target framework (TFM): (e.g., `net10.0`, `net11.0`, `netstandard2.0`, `net472`) +- Native AOT used: (yes/no) +- Trimming used: (yes/no) - Operating System: (e.g., Windows 11, Ubuntu 22.04, macOS 14) - IDE/Editor: (e.g., Visual Studio 2022, Rider, VS Code) @@ -60,10 +62,9 @@ The v1.x maintenance window ended in July 2026; new fixes target v2.x. See the [ **Configuration (Optional):** ```json -// Your LocalStack configuration (appsettings.json snippet) { "LocalStack": { - // ... + "UseLocalStack": true } } ``` diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 8e9bf6e..89dfa8e 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -26,9 +26,7 @@ Provide a clear and concise description of the changes. ## 🎯 Target Version Track -- [ ] v2.x (AWS SDK v4) - Supported branch (`master`) - -The v1.x / AWS SDK v3 line is no longer supported; do not target new fixes to `sdkv3-lts`. See the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md). +- [ ] 3.x (AWS SDK v4) - `master` ## 🧪 Testing diff --git a/.github/SECURITY.md b/.github/SECURITY.md index b86889e..9ce38a2 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -2,20 +2,20 @@ ## Supported Versions -Security patches are released for the supported v2.x line according to the CVSS v3.0 rating below. Previously published v1.x packages remain available, but availability does not mean the line is still maintained. +Security patches for the current 3.x line follow the CVSS v3.0 ratings below. Previously published packages remain available even when their release line is no longer maintained. ### Version Tracks -- **v2.x (AWS SDK v4)**: Active development on [master branch](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/master) -- **v1.x (AWS SDK v3)**: The [sdkv3-lts branch](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/sdkv3-lts) is no longer supported. Its announced maintenance window ended in **July 2026**. We do not plan further v1.x bug fixes, security patches, or service updates; migrate to v2.x. The upstream [AWS SDK for .NET v3 reached end-of-support on June 1, 2026](https://aws.amazon.com/blogs/devops/announcing-the-end-of-support-for-the-aws-sdk-for-net-v3/). +- **3.x (AWS SDK v4)**: Current development on [master](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/master); receives patches according to the table below. +- **Earlier versions**: Not supported and receive no fixes; upgrade to 3.x. ### Security Patch Policy -| CVSS v3.0 | v2.x (Current) | -| --------- | -------------- | -| 9.0-10.0 | ✅ All releases within previous 3 months | -| 4.0-8.9 | ✅ Most recent release | -| < 4.0 | ⚠️ Best effort | +| CVSS v3.0 | 3.x (Current) | +| --- | --- | +| 9.0-10.0 | All 3.x releases within the previous 3 months | +| 4.0-8.9 | Most recent release | +| < 4.0 | Best effort | ## Reporting a Vulnerability diff --git a/CHANGELOG.md b/CHANGELOG.md index 6925c2c..d23a0ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,30 +1,46 @@ -# LocalStack .NET Client v2.x Change Log +# Changelog -This document outlines the changes, updates, and important notes for the LocalStack .NET Client v2.x series, including the latest preview release. +## [Unreleased] -See v1.x change log for previous versions: [CHANGELOG.md](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/sdkv3-lts/CHANGELOG.md) +Planned as **3.0.0** for both packages; not yet published. -## [Unreleased] +### Breaking changes + +- Dropped the `net8.0` and `net9.0` assets. .NET 8 and .NET 9 apps still install both packages and use `netstandard2.0` under JIT, without Native AOT; both runtimes reach end of support on November 10, 2026. +- `TryAddAwsService(lifetime, useServiceUrl)` now honors `useServiceUrl`. Callers that passed `true` now get `ServiceURL` instead of a region endpoint ([#63](https://github.com/localstack-dotnet/localstack-dotnet-client/issues/63)). + +### Added + +- Added `net10.0` and `net11.0` assets to Core (`LocalStack.Client`) and Extensions (`LocalStack.Client.Extensions`). .NET 11 is not generally available yet; the `net11.0` assets are built with a .NET 11 preview SDK. +- Both packages support Native AOT and trimming on these targets with zero trim/AOT warnings, no suppressions, and no consumer code changes. This includes `AddLocalStack(configuration)`, all Add/TryAdd/alias registration overloads, Core `Session` / `SessionStandalone`, and the `Type`-based APIs. +- On `net10.0` and `net11.0`, both packages use no runtime reflection for AWS SDK service clients and configs, or for custom clients and configs that follow the SDK's shape (public or internal, concrete, non-generic, with the standard `(AWSCredentials, XConfig)` constructors). The generic APIs (`AddAwsService` and every overload, `CreateClientByInterface()`) use the AWS SDK v4 static factories and do not depend on source generation, so they also work in F# and Visual Basic. The `Type`-based APIs use a build-time source generator that ships in Core and turns itself on for C# projects targeting `net10.0` or later, with no setup or extra package. Other client shapes (private or generic custom clients, F# and Visual Basic projects for the `Type`-based APIs, assemblies loaded at run time) keep the previous behavior through a reflection fallback that runs only under JIT; trimmed and Native AOT apps do not include it. These claims cover LocalStack.NET's own code; the AWS SDK, dependency injection and BCL internals have their own AOT status, and LocalStack determines its own service coverage. + +### Changed + +- With `UseLocalStack: false`, Extensions now creates clients through the AWS SDK's public `AddAWSService` factory instead of private SDK reflection. No consumer code changes are needed. ### Documentation -- The README prerequisites now explain that LocalStack images from 2026.03.0 on, including `latest`, need `LOCALSTACK_AUTH_TOKEN` to start. They show how to pass it with Docker and docker-compose and name 4.14.0 as the last token-free release, which gets no further updates ([#51](https://github.com/localstack-dotnet/localstack-dotnet-client/issues/51)). -- Known Issues now states that the SNS fix first shipped in LocalStack v4.0.0. Removed the LocalStack v2 routing, AWS SDK v3 `AWSSDK.SQS` and untracked `IAmazonLambda` notes; the v1.x README keeps the historical entries. - -### General - -- Replaced the AWS-mode wrapper's private SDK reflection with the public `AddAWSService` factory, preserving provider options fallback and client lifetimes. Removed its obsolete linker descriptor and reflection/AOT annotations. -- Added automatic Core source generation that roots existing reflection operations, plus lazy fixed-schema configuration binding, preserving existing C# `AddLocalStack`, AWS service registration, and Core `Session` calls. Local-package Native AOT validation covers .NET 10 on `win-x64` and `linux-x64`, including S3 requests and endpoint, region, credentials, and configured-value parity with JIT; see the [scope boundary](docs/architecture/platform-and-packaging.md#native-aot-and-trimming). -- Added `Microsoft.Extensions.Options` 8.0.2 only to modern Extensions assets for Native AOT, implying `Microsoft.Extensions.Primitives >= 8.0.0` there. Legacy dependency floors and existing intentional minimums are unchanged. -- Added explicit `net10.0` target assets to both packages while retaining their existing target frameworks. -- Set the development SDK baseline to 10.0.402 and configured test projects and CI workflows to cover `net10.0`. -- Updated all existing non-Core centrally managed NuGet versions to their latest stable releases, including build, test, and analyzer packages (Extensions' consumer minimums are preserved below). Build-tool updates include Cake.Frosting 6.3.0 and NuGet.Versioning 7.9.0. -- Updated centrally managed Microsoft.Extensions versions to 10.0.13 for test and sandbox consumers. Extensions retains its existing consumer minimums: `Microsoft.Extensions.Configuration.Abstractions`, `Microsoft.Extensions.Configuration.Binder`, `Microsoft.Extensions.Logging.Abstractions`, and `Microsoft.Extensions.Options.ConfigurationExtensions` at 3.1.32 on all targets; `Microsoft.Extensions.DependencyInjection.Abstractions` at 3.1.32 on `netstandard2.0` and 8.0.0 on `net8.0`, `net9.0`, and `net10.0`. -- Updated SourceLink to 10.0.402 and Testcontainers plus Testcontainers.LocalStack to 4.16.0; restore resolves Microsoft.Build.Tasks.Git 10.0.402 and SSH.NET 2026.0.0. -- Set the declared `AWSSDK.Core` minimum to 4.0.102.6, the recent compatible stable candidate with the highest version-level downloads among stable AWS SDK v4 releases in a six-week comparison of [NuGet.org releases](https://www.nuget.org/packages/AWSSDK.Core), checked 2026-10-19. Core-only projects resolve 4.0.102.6; Extensions and service-package consumers resolve 4.0.102.11 under their actual dependency ranges. `AWSSDK.Extensions.NETCore.Setup` remains at 4.0.102.4; refreshed 112 existing AWS service SDK test-dependency pins, retained six already-latest entries, and made no catalog additions or removals. -- Updated the build dependency `System.Security.Cryptography.Pkcs` to 10.0.13; repository-wide `NuGetAuditMode=all` remains enabled. -- The Cake build no longer changes the global Git `core.autocrlf` setting on Unix; a repository `.gitattributes` now normalizes line endings. The Cake test task no longer deletes every Docker container before functional tests, because Testcontainers removes the containers each run starts, and the `Cake.Docker` build dependency was removed. -- Functional tests now run against two LocalStack images instead of 3.7.1 and 4.6.0: 4.14.0, the last release that starts without an auth token, and 2026.10.2, which needs `LOCALSTACK_AUTH_TOKEN`. Without that variable the 2026.10.2 tests fail with a message naming it; `--filter "LocalStackAuth!=Required"` or the Cake flag `--skipAuthenticatedFunctionalTest true` excludes them. CI passes the `LOCALSTACK_AUTH_TOKEN` Actions secret to the Linux functional run and skips those tests, with a warning, on pull requests that cannot read the secret. +- The README states that LocalStack images from 2026.03.0 on, including `latest`, need `LOCALSTACK_AUTH_TOKEN`, and links the official [auth-token](https://docs.localstack.cloud/aws/getting-started/auth-token/) and [CI documentation](https://docs.localstack.cloud/aws/ci-pipelines/). It names 4.14.0 as the last token-free release, which gets no further updates ([#51](https://github.com/localstack-dotnet/localstack-dotnet-client/issues/51)). +- Known issues now states that the SNS fix first shipped in LocalStack v4.0.0. Removed the LocalStack v2 routing, AWS SDK v3 `AWSSDK.SQS` and untracked `IAmazonLambda` notes. +- The security policy, contribution guide and templates list 3.x as the only supported line. +- Rewrote the README for 3.0.0 with package selection, configuration defaults, registration APIs, standalone usage, and upgrade guidance; moved contributor instructions to the contribution guide. + +### Dependencies + +- Core: `AWSSDK.Core` >= 4.0.102.6. +- Extensions: `AWSSDK.Extensions.NETCore.Setup` >= 4.0.102.4. +- Extensions: `Microsoft.Extensions.Configuration.Abstractions`, `Microsoft.Extensions.Configuration.Binder`, `Microsoft.Extensions.Logging.Abstractions`, and `Microsoft.Extensions.Options.ConfigurationExtensions` >= 3.1.32 on all targets. +- Extensions: `Microsoft.Extensions.DependencyInjection.Abstractions` >= 3.1.32 on `netstandard2.0` and >= 8.0.0 on `net10.0`/`net11.0`. +- Extensions: `Microsoft.Extensions.Options` >= 8.0.2 on `net10.0`/`net11.0` only. + +### Build, tests and CI + +- The repository now builds with the .NET 11 SDK pinned in `global.json`; test projects and CI cover `net10.0` and `net11.0`. +- Refreshed build, test, and analyzer dependencies, including Cake.Frosting 6.3.0, NuGet.Versioning 7.9.0, SourceLink 10.0.402, Testcontainers and Testcontainers.LocalStack 4.16.0, and `System.Security.Cryptography.Pkcs` 10.0.13. Restore resolves Microsoft.Build.Tasks.Git 10.0.402 and SSH.NET 2026.0.0; repository-wide `NuGetAuditMode=all` remains enabled. +- Test and sandbox consumers use centrally managed Microsoft.Extensions 10.0.13. Refreshed 112 AWS service SDK pins and retained six already-latest entries, with no catalog additions or removals. Core-only projects resolve 4.0.102.6; Extensions and service-package consumers resolve 4.0.102.11 under their dependency ranges. +- Cake no longer changes global Git `core.autocrlf` on Unix; `.gitattributes` normalizes line endings. The test task no longer deletes every Docker container; Testcontainers removes the containers each run starts. Removed `Cake.Docker`. +- Functional tests now use LocalStack 4.14.0 and 2026.10.2 instead of 3.7.1 and 4.6.0. The 2026.10.2 tests require `LOCALSTACK_AUTH_TOKEN` and fail with a message naming it when absent; `--filter "LocalStackAuth!=Required"` or Cake's `--skipAuthenticatedFunctionalTest true` excludes them. CI passes the Actions secret to the Linux functional run and skips those tests with a warning on pull requests that cannot read it. ## [v2.0.1](https://github.com/localstack-dotnet/localstack-dotnet-client/releases/tag/v2.0.1) diff --git a/README.md b/README.md index c9520b1..a5be0c3 100644 --- a/README.md +++ b/README.md @@ -1,274 +1,195 @@ -# LocalStack .NET Client +# LocalStack.NET -[![Nuget](https://img.shields.io/nuget/dt/LocalStack.Client)](https://www.nuget.org/packages/LocalStack.Client/) [![NuGet v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2F%3Fpackage%3Dlocalstack.client%26source%3Dnuget%26track%3D2%26includeprerelease%3Dtrue%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client/) [![NuGet v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2F%3Fpackage%3Dlocalstack.client%26source%3Dnuget%26track%3D1%26includeprerelease%3Dtrue%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client/) [![CI/CD Pipeline](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml) [![Security](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql) [![Linux Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/linux?label=Tests)](https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/redirect/test-results/linux) - -> **🚀 Quick Start**: `dotnet add package LocalStack.Client --version 2.0.0` (AWS SDK v4) | [Package installation](#-package-installation) | [Migration context](https://github.com/orgs/localstack-dotnet/discussions/45) - ---- - -## 🎉 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](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/engineering/quality-gates.md) 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](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) before upgrading. - -**Version Strategy**: - -- v2.x (AWS SDK v4) active development on [master branch](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/master) -- v1.x (AWS SDK v3) remains available on the [sdkv3-lts branch](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/sdkv3-lts), but support ended in July 2026. Use v2.x for maintained releases; see the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md). +[![LocalStack.Client](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dnuget%26label%3DLocalStack.Client)](https://www.nuget.org/packages/LocalStack.Client/) [![LocalStack.Client.Extensions](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client.extensions%3Fsource%3Dnuget%26label%3DLocalStack.Client.Extensions)](https://www.nuget.org/packages/LocalStack.Client.Extensions/) [![Downloads](https://img.shields.io/nuget/dt/LocalStack.Client)](https://www.nuget.org/packages/LocalStack.Client/) [![CI/CD Pipeline](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml) [![Security](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql) [![Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/linux?label=Tests)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml) ![LocalStack](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/assets/localstack-dotnet.png?raw=true) -LocalStack.NET is a .NET client library for [LocalStack](https://github.com/localstack/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](https://dotnet.microsoft.com/download/dotnet/8.0) | [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) | [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) -- [.NET Standard 2.0](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) -- [.NET Framework 4.7.2 and Above](https://dotnet.microsoft.com/download/dotnet-framework) - -## ⚡ Native AOT & Trimming Status - -- **Unreleased:** Native AOT support preserves existing C# calls such as `AddLocalStack(configuration)`, `AddAwsService()`, and Core `Session` calls. Source generation flows automatically through either package; no new registration or factory API is required. It roots existing reflection operations rather than removing reflection. -- Local-package consumers have been validated with Native AOT and its mandatory trimming on .NET 10 for `win-x64` and `linux-x64`, including S3 `ListBucketsAsync` and JIT parity for endpoint, region, credentials, and configured values. This does not establish support for every service, operation, or native target, or for separately trimmed JIT deployments. Do not suppress trim/AOT warnings. -- This implementation is **not part of the published Core 2.0.0 / Extensions 2.0.1 releases**. See the [platform boundary](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/architecture/platform-and-packaging.md#native-aot-and-trimming) for scope and the [Native AOT decision](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/adr/0004-native-aot-preserves-existing-consumer-code.md) for the unchanged-consumer contract. - -### Build & Test Matrix - -| Category | Platform/Type | Status | Description | -|----------|---------------|--------|-------------| -| **🔧 Build** | Cross-Platform | [![CI/CD Pipeline](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml) | Matrix testing: Windows, Linux, macOS | -| **🔒 Security** | Static Analysis | [![Security](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql) | CodeQL analysis & dependency review | -| **🧪 Tests** | Linux | [![Linux Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/linux?label=Tests)](https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/redirect/test-results/linux) | All framework targets | -| **🧪 Tests** | Windows | [![Windows Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/windows?label=Tests)](https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/redirect/test-results/windows) | All framework targets | -| **🧪 Tests** | macOS | [![macOS Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/macos?label=Tests)](https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/redirect/test-results/macos) | All framework targets | - -## Package Status - -| Package | NuGet.org | GitHub Packages (development builds) | -|---------|-----------|---------------------------| -| **LocalStack.Client v1.x** | [![NuGet v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dnuget%26track%3D1%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client/) | [![Github v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dgithub%26track%3D1%26includeprerelease%3Dtrue%26label%3Dgithub)](https://github.com/localstack-dotnet/localstack-dotnet-client/pkgs/nuget/LocalStack.Client) | -| **LocalStack.Client v2.x** | [![NuGet v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dnuget%26track%3D2%26includeprerelease%3Dtrue%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client/) | [![Github v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dgithub%26track%3D2%26includeprerelease%3Dtrue%26label%3Dgithub)](https://github.com/localstack-dotnet/localstack-dotnet-client/pkgs/nuget/LocalStack.Client) | -| **LocalStack.Client.Extensions v1.x** | [![NuGet v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client.extensions%3Fsource%3Dnuget%26track%3D1%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client.Extensions/) | [![Github v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client.extensions%3Fsource%3Dgithub%26track%3D1%26includeprerelease%3Dtrue%26label%3Dgithub)](https://github.com/localstack-dotnet/localstack-dotnet-client/pkgs/nuget/LocalStack.Client.Extensions) | -| **LocalStack.Client.Extensions v2.x** | [![NuGet v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client.extensions%3Fsource%3Dnuget%26track%3D2%26includeprerelease%3Dtrue%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client.Extensions/) | [![GitHub Packages v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2F%3Fpackage%3Dlocalstack.client.extensions%26source%3Dgithub%26track%3D2%26includeprerelease%3Dtrue%26label%3Dgithub)](https://github.com/localstack-dotnet/localstack-dotnet-client/pkgs/nuget/LocalStack.Client.Extensions) | - -## Table of Contents - -1. [Supported Platforms](#supported-platforms) -2. [Why LocalStack.NET Client?](#why-localstacknet-client) -3. [Prerequisites](#prerequisites) -4. [Getting Started](#getting-started) - - [Setup](#setup) - - [Configuration](#configuration) -5. [Known Issues](#known-issues) -6. [Developing](#developing) - - [Building the Project](#building-the-project) - - [Sandbox Applications](#sandbox-applications) - - [Running Tests](#running-tests) -7. [Changelog](#changelog) -8. [License](#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, .NET 10, and .NET Standard 2.0; Core also has an explicit .NET Framework 4.7.2 target. See [platform and packaging](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/architecture/platform-and-packaging.md) 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](https://docs.docker.com/get-docker/) or [docker-compose](https://docs.docker.com/compose/install/). - -**LocalStack needs an auth token.** From release 2026.03.0 on, every LocalStack for AWS image, including `localstack/localstack:latest`, requires a `LOCALSTACK_AUTH_TOKEN` to start ([announcement](https://blog.localstack.cloud/localstack-for-aws-release-2026-03-0/)). Without one, the container exits with a "License activation failed" error and LocalStack.NET has nothing to connect to. A free account is available: create it at [localstack.cloud](https://localstack.cloud/), copy your token from the LocalStack Web App, and pass it to the container: - -```bash -docker run --rm -it \ - -e LOCALSTACK_AUTH_TOKEN=$LOCALSTACK_AUTH_TOKEN \ - -p 4566:4566 \ - localstack/localstack -``` - -With docker-compose, add it under the LocalStack service: +[LocalStack](https://github.com/localstack/localstack) is a local AWS cloud emulator. LocalStack.NET wires AWS SDK for .NET v4 clients to LocalStack and lets you switch between LocalStack and real AWS with one configuration setting. LocalStack's [.NET guide](https://docs.localstack.cloud/aws/connecting/aws-sdks/dotnet/) lists LocalStack.NET as an alternative to configuring endpoints by hand. -```yaml -environment: - - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} -``` - -In CI, use a CI Auth Token stored in your CI provider's secret store; see the [Auth Token documentation](https://docs.localstack.cloud/aws/getting-started/auth-token/). - -The token is a LocalStack platform credential for the container. LocalStack.NET does not read it, and it does not replace the AWS credentials in the `LocalStack:Session` configuration. - -If you cannot use a token, `localstack/localstack:4.14.0` is the last release that starts without one. LocalStack keeps such earlier tags runnable without authentication but gives them no further service or security updates ([details](https://blog.localstack.cloud/the-road-ahead-for-localstack/)). +## Features -For detailed installation and setup instructions, please refer to the [official LocalStack installation guide](https://docs.localstack.cloud/aws/getting-started/installation/). +- Create LocalStack-configured AWS clients without manual endpoint code. +- Register clients through dependency injection with APIs that mirror `AWSSDK.Extensions.NETCore.Setup`. +- Switch client creation between LocalStack and AWS with `LocalStack:UseLocalStack`. +- Use Native AOT and trimming on `net10.0` and `net11.0` without changing consumer code. +- Run on .NET Framework 4.7.2 and later, and on other `netstandard2.0` runtimes. -## Getting Started +## Packages -LocalStack.NET is available through multiple package sources to support different development workflows. +| Package | Use it when | NuGet link | +| --- | --- | --- | +| `LocalStack.Client` (Core) | You create clients directly through a session. | [Core](https://www.nuget.org/packages/LocalStack.Client/) | +| `LocalStack.Client.Extensions` (Extensions) | You use .NET configuration and dependency injection. | [Extensions](https://www.nuget.org/packages/LocalStack.Client.Extensions/) | -### 📦 Package Installation - -To install the latest version of LocalStack.NET with AWS SDK v4 support, use the following command: +Install one package, plus the AWS SDK v4 service packages your app uses (for example, `AWSSDK.S3`). Extensions already depends on Core. ```bash -# 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 +dotnet add package LocalStack.Client.Extensions # configuration and dependency injection +dotnet add package LocalStack.Client # Core only ``` -#### Development Builds (GitHub Packages) +### Prerelease builds -For testing latest features and bug fixes: +Development builds are published to GitHub Packages at the feed shown below. +Authentication requires a GitHub personal access token with `read:packages` permission. +Replace the username and token placeholders below with your GitHub credentials. ```bash -# 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 + --name github-localstack --username YOUR_GITHUB_USERNAME --password YOUR_GITHUB_TOKEN \ + --store-password-in-clear-text dotnet add package LocalStack.Client.Extensions --prerelease --source github-localstack ``` -> **🔑 GitHub Packages Authentication**: You'll need a GitHub account and [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `read:packages` permission. - -Refer to [documentation](https://github.com/localstack-dotnet/localstack-dotnet-client/wiki/Getting-Started#installation) for more information on how to install LocalStack.NET. - -`LocalStack.NET` is a library that provides a wrapper around the [aws-sdk-net](https://github.com/aws/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](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config-netcore.html) with a few differences. For more on how to use the AWS SDK for .NET, see [Getting Started with the AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-setup.html). +## Supported frameworks -### Setup +| TFM | Core | Extensions | Native AOT | +| --- | --- | --- | --- | +| `netstandard2.0` | Yes | Yes | No | +| `net472` | Yes (.NET Framework 4.7.2+) | Uses `netstandard2.0` | No | +| `net10.0` | Yes | Yes | Yes | +| `net11.0` (preview) | Yes | Yes | Yes | -Here's a basic example of how to setup `LocalStack.NET`: +.NET 11 is not generally available yet; the `net11.0` assets are built with a .NET 11 preview SDK. +.NET 8 and .NET 9 apps use both packages' `netstandard2.0` assets under JIT, without Native AOT; both runtimes reach [end of support](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core) on November 10, 2026. -```csharp -public void ConfigureServices(IServiceCollection services) -{ - // Add framework services. - services.AddMvc(); - - services.AddLocalStack(Configuration); - services.AddDefaultAWSOptions(Configuration.GetAWSOptions()); - services.AddAwsService(); - services.AddAwsService(); -} -``` +## Prerequisites -`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](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/architecture/client-runtime.md) for what the endpoint catalog does—and does not—promise. +Run LocalStack with Docker or docker-compose; follow the [installation guide](https://docs.localstack.cloud/aws/getting-started/installation/). -(Alternatively, `AddAWSServiceLocalStack` method can be used to prevent mix-up with `AddAWSService`.) +From 2026.03.0 on, every LocalStack for AWS image (including `localstack/localstack:latest`) needs `LOCALSTACK_AUTH_TOKEN`, even on the Hobby plan, which is free for non-commercial use. +The token belongs to the container: LocalStack.NET does not read it, and it is not an AWS credential. +`localstack/localstack:4.14.0` is the last image that starts without a token; it receives no further updates. +See the official [auth-token documentation](https://docs.localstack.cloud/aws/getting-started/auth-token/) and [CI guidance](https://docs.localstack.cloud/aws/ci-pipelines/). -`AddLocalStack` extension method is responsible for both configurations and adding of `LocalStack.Client` dependencies to service collection. +## Quick start -### Configuration +In a minimal-hosting `Program.cs`, register LocalStack and your AWS service interfaces: -To configure LocalStack.NET, you can use entries in the appsettings.json files. Here's a basic example for different environments: +```csharp +using Amazon.S3; +using LocalStack.Client.Extensions; +using Microsoft.AspNetCore.Builder; +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; + +var builder = WebApplication.CreateBuilder(args); +builder.Services.AddLocalStack(builder.Configuration); +builder.Services.AddDefaultAWSOptions(builder.Configuration.GetAWSOptions()); +builder.Services.AddAwsService(); + +var app = builder.Build(); +app.Run(); +``` -`appsettings.Development.json` +`appsettings.Development.json` selects LocalStack: ```json -"LocalStack": { +{ + "LocalStack": { "UseLocalStack": true, "Session": { - "RegionName": "eu-central-1" + "RegionName": "eu-central-1" }, "Config": { - "LocalStackHost": "localhost.localstack.cloud", // or "localhost", - "EdgePort": 4566 + "LocalStackHost": "localhost.localstack.cloud", + "EdgePort": 4566 } + } } ``` -`appsettings.Production.json` +`appsettings.Production.json` selects the ordinary AWS SDK factory: ```json -"LocalStack": { +{ + "LocalStack": { "UseLocalStack": false -}, -"AWS": { + }, + "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](https://github.com/localstack-dotnet/localstack-dotnet-client/wiki/Setup#configuration). - -## 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` 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: +## Configuration - ```xml - - ``` +| Key | Default | +| --- | --- | +| `LocalStack:UseLocalStack` | `false` | +| `LocalStack:Session:AwsAccessKeyId` | `accessKey` | +| `LocalStack:Session:AwsAccessKey` | `secretKey` | +| `LocalStack:Session:AwsSessionToken` | `token` | +| `LocalStack:Session:RegionName` | `us-east-1` | +| `LocalStack:Config:LocalStackHost` | `localhost.localstack.cloud` | +| `LocalStack:Config:UseSsl` | `false` | +| `LocalStack:Config:UseLegacyPorts` | `false` (only for LocalStack before 0.11.5) | +| `LocalStack:Config:EdgePort` | `4566` | - See [issue #52](https://github.com/localstack-dotnet/localstack-dotnet-client/issues/52) for the full analysis. +LocalStack does not validate the dummy session credentials. +When `UseLocalStack` is `false`, the ordinary `AWS` section and `AddDefaultAWSOptions(configuration.GetAWSOptions())` from `AWSSDK.Extensions.NETCore.Setup` apply. -- **SNS with LocalStack v3.7.2 through v3.8.1:** SNS operations failed on LocalStack v3.7.2 and v3.8.0 because of a request-forwarding bug ([issue #11652](https://github.com/localstack/localstack/issues/11652)). The fix ([PR #11653](https://github.com/localstack/localstack/pull/11653)) was merged after v3.8.1 shipped and first appears in **v4.0.0**; no 3.x release contains it. Use LocalStack v4.0.0 or later, or v3.7.1 if you must stay on the 3.x line. +## Registering clients -- **Endpoint environment variables:** [Issue #27](https://github.com/localstack-dotnet/localstack-dotnet-client/issues/27#issuecomment-4937111791) 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. +`AddAwsService`, `TryAddAwsService`, `AddAWSServiceLocalStack`, and `TryAddAWSServiceLocalStack` each have two overloads: -Older notes about LocalStack v1 and v2 releases and AWS SDK v3 packages remain in the [v1.x README](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/sdkv3-lts/README.md#known-issues). +- `(ServiceLifetime lifetime = ServiceLifetime.Singleton, bool useServiceUrl = false)` +- `(AWSOptions? options, ServiceLifetime lifetime = ServiceLifetime.Singleton, bool useServiceUrl = false)` -## Developing +The `Try*` methods register a client only if its service type is not registered yet. `AddAWSServiceLocalStack` is an alias of `AddAwsService` that avoids confusion with the AWS SDK's `AddAWSService`. +`AddDefaultAwsOptions(AWSOptions)` delegates to the SDK's `AddDefaultAWSOptions`. -We appreciate contributions in the form of feedback, bug reports, and pull requests. +Every LocalStack client gets the configured session credentials (dummy values by default), `ProxyHost`/`ProxyPort` pointing at LocalStack, HTTP unless `UseSsl` is `true`, and S3 path-style addressing. +With `useServiceUrl: false`, the client also gets `RegionEndpoint` from `RegionName`, which must be set; `useServiceUrl: true` sets `ServiceURL` to the service's LocalStack URL instead. +This option configures a LocalStack client; `LocalStack:UseLocalStack` selects LocalStack or AWS client creation. -### Building the Project +```csharp +builder.Services.TryAddAwsService( + lifetime: ServiceLifetime.Singleton, useServiceUrl: true); +``` -To build the project, use the following commands based on your operating system: +## Using LocalStack.Client without dependency injection -Windows +Create a session with `SessionStandalone` and choose an implementation-based or interface-based client: -```powershell -build.ps1 -``` +```csharp +using Amazon.S3; +using LocalStack.Client; +using LocalStack.Client.Options; -Linux +var session = SessionStandalone.Init() + .WithSessionOptions(new SessionOptions()) + .WithConfigurationOptions(new ConfigOptions()) + .Create(); -```bash -./build.sh +using var s3 = session.CreateClientByImplementation(); +using var s3ByInterface = session.CreateClientByInterface(); ``` -### Sandbox Applications - -The LocalStack .NET repository includes several sandbox console applications located in [tests/sandboxes](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/master/tests/sandboxes). These applications serve both as testing tools and as examples. Refer to [the documentation](https://github.com/localstack-dotnet/localstack-dotnet-client/wiki/Developing#sandbox-applications) for more information - -### Running Tests +The `Type`-based overloads are `CreateClientByImplementation(Type implType, bool useServiceUrl = false)` and `CreateClientByInterface(Type serviceInterfaceType, bool useServiceUrl = false)`. -To execute the tests, use the commands below: +## Native AOT and trimming -Windows +On `net10.0` and `net11.0`, both packages support Native AOT and trimming with no consumer code changes, zero trim/AOT warnings and no suppressions. They use no runtime reflection for AWS SDK service clients and configs, or for custom clients that follow the SDK's shape; other client types keep a reflection fallback that runs only under JIT. The `Type`-based APIs rely on a source generator that runs in C# projects, so F# and Visual Basic apps should use the generic APIs under Native AOT. These statements cover LocalStack.NET's own code; the AWS SDK and LocalStack's service coverage have their own status. See [platform and packaging](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/architecture/platform-and-packaging.md#native-aot-and-trimming) for the exact boundary. -```powershell -build.ps1 --target=tests -``` +## Versions and support -Linux +3.x (AWS SDK v4) is the supported line, developed on `master`; earlier versions are not supported. .NET 8 and .NET 9 apps use the `netstandard2.0` assets under JIT, without Native AOT. See the [changelog](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) for release details and the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md) for the patch policy. -```bash -./build.sh --target=tests -``` +## Known issues -## Community +- **SNS with LocalStack v3.7.2 through v3.8.1:** SNS operations failed on LocalStack v3.7.2 and v3.8.0 because of a request-forwarding bug ([issue #11652](https://github.com/localstack/localstack/issues/11652)). The fix ([PR #11653](https://github.com/localstack/localstack/pull/11653)) was merged after v3.8.1 shipped and first appears in **v4.0.0**; no 3.x release contains it. Use LocalStack v4.0.0 or later, or v3.7.1 if you must stay on the 3.x line. +- **Endpoint environment variables:** With `UseLocalStack: true`, the LocalStack proxy settings took precedence over `AWS_ENDPOINT_URL` in a reported SQS case; with `UseLocalStack: false`, `AWS_ENDPOINT_URL` applied. The library defines no general precedence rule for `AWS_ENDPOINT_URL` or `AWS_SERVICE_URL`, so check the actual SDK configuration before relying on either. See [#27](https://github.com/localstack-dotnet/localstack-dotnet-client/issues/27#issuecomment-4937111791). -Got questions or wild feature ideas? +## Contributing -👉 Join the conversation in [GitHub Discussions](https://github.com/localstack-dotnet/localstack-dotnet-client/discussions). +See the [contribution guide](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/CONTRIBUTING.md) for build, sandbox, and test instructions. Ask questions and share ideas in [Discussions](https://github.com/localstack-dotnet/localstack-dotnet-client/discussions). ## Changelog -Please refer to [`CHANGELOG.md`](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) to see the complete list of changes for each release. +Read the [changelog](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) for changes in each release. ## License -Licensed under MIT, see [LICENSE](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/LICENSE) for the full text. +LocalStack.NET uses the [MIT License](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/LICENSE). diff --git a/src/LocalStack.Client.Extensions/README.md b/src/LocalStack.Client.Extensions/README.md index c9520b1..a5be0c3 100644 --- a/src/LocalStack.Client.Extensions/README.md +++ b/src/LocalStack.Client.Extensions/README.md @@ -1,274 +1,195 @@ -# LocalStack .NET Client +# LocalStack.NET -[![Nuget](https://img.shields.io/nuget/dt/LocalStack.Client)](https://www.nuget.org/packages/LocalStack.Client/) [![NuGet v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2F%3Fpackage%3Dlocalstack.client%26source%3Dnuget%26track%3D2%26includeprerelease%3Dtrue%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client/) [![NuGet v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2F%3Fpackage%3Dlocalstack.client%26source%3Dnuget%26track%3D1%26includeprerelease%3Dtrue%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client/) [![CI/CD Pipeline](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml) [![Security](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql) [![Linux Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/linux?label=Tests)](https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/redirect/test-results/linux) - -> **🚀 Quick Start**: `dotnet add package LocalStack.Client --version 2.0.0` (AWS SDK v4) | [Package installation](#-package-installation) | [Migration context](https://github.com/orgs/localstack-dotnet/discussions/45) - ---- - -## 🎉 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](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/engineering/quality-gates.md) 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](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) before upgrading. - -**Version Strategy**: - -- v2.x (AWS SDK v4) active development on [master branch](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/master) -- v1.x (AWS SDK v3) remains available on the [sdkv3-lts branch](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/sdkv3-lts), but support ended in July 2026. Use v2.x for maintained releases; see the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md). +[![LocalStack.Client](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dnuget%26label%3DLocalStack.Client)](https://www.nuget.org/packages/LocalStack.Client/) [![LocalStack.Client.Extensions](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client.extensions%3Fsource%3Dnuget%26label%3DLocalStack.Client.Extensions)](https://www.nuget.org/packages/LocalStack.Client.Extensions/) [![Downloads](https://img.shields.io/nuget/dt/LocalStack.Client)](https://www.nuget.org/packages/LocalStack.Client/) [![CI/CD Pipeline](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml) [![Security](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql) [![Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/linux?label=Tests)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml) ![LocalStack](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/assets/localstack-dotnet.png?raw=true) -LocalStack.NET is a .NET client library for [LocalStack](https://github.com/localstack/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](https://dotnet.microsoft.com/download/dotnet/8.0) | [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) | [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) -- [.NET Standard 2.0](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) -- [.NET Framework 4.7.2 and Above](https://dotnet.microsoft.com/download/dotnet-framework) - -## ⚡ Native AOT & Trimming Status - -- **Unreleased:** Native AOT support preserves existing C# calls such as `AddLocalStack(configuration)`, `AddAwsService()`, and Core `Session` calls. Source generation flows automatically through either package; no new registration or factory API is required. It roots existing reflection operations rather than removing reflection. -- Local-package consumers have been validated with Native AOT and its mandatory trimming on .NET 10 for `win-x64` and `linux-x64`, including S3 `ListBucketsAsync` and JIT parity for endpoint, region, credentials, and configured values. This does not establish support for every service, operation, or native target, or for separately trimmed JIT deployments. Do not suppress trim/AOT warnings. -- This implementation is **not part of the published Core 2.0.0 / Extensions 2.0.1 releases**. See the [platform boundary](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/architecture/platform-and-packaging.md#native-aot-and-trimming) for scope and the [Native AOT decision](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/adr/0004-native-aot-preserves-existing-consumer-code.md) for the unchanged-consumer contract. - -### Build & Test Matrix - -| Category | Platform/Type | Status | Description | -|----------|---------------|--------|-------------| -| **🔧 Build** | Cross-Platform | [![CI/CD Pipeline](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml) | Matrix testing: Windows, Linux, macOS | -| **🔒 Security** | Static Analysis | [![Security](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql) | CodeQL analysis & dependency review | -| **🧪 Tests** | Linux | [![Linux Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/linux?label=Tests)](https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/redirect/test-results/linux) | All framework targets | -| **🧪 Tests** | Windows | [![Windows Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/windows?label=Tests)](https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/redirect/test-results/windows) | All framework targets | -| **🧪 Tests** | macOS | [![macOS Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/macos?label=Tests)](https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/redirect/test-results/macos) | All framework targets | - -## Package Status - -| Package | NuGet.org | GitHub Packages (development builds) | -|---------|-----------|---------------------------| -| **LocalStack.Client v1.x** | [![NuGet v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dnuget%26track%3D1%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client/) | [![Github v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dgithub%26track%3D1%26includeprerelease%3Dtrue%26label%3Dgithub)](https://github.com/localstack-dotnet/localstack-dotnet-client/pkgs/nuget/LocalStack.Client) | -| **LocalStack.Client v2.x** | [![NuGet v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dnuget%26track%3D2%26includeprerelease%3Dtrue%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client/) | [![Github v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dgithub%26track%3D2%26includeprerelease%3Dtrue%26label%3Dgithub)](https://github.com/localstack-dotnet/localstack-dotnet-client/pkgs/nuget/LocalStack.Client) | -| **LocalStack.Client.Extensions v1.x** | [![NuGet v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client.extensions%3Fsource%3Dnuget%26track%3D1%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client.Extensions/) | [![Github v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client.extensions%3Fsource%3Dgithub%26track%3D1%26includeprerelease%3Dtrue%26label%3Dgithub)](https://github.com/localstack-dotnet/localstack-dotnet-client/pkgs/nuget/LocalStack.Client.Extensions) | -| **LocalStack.Client.Extensions v2.x** | [![NuGet v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client.extensions%3Fsource%3Dnuget%26track%3D2%26includeprerelease%3Dtrue%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client.Extensions/) | [![GitHub Packages v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2F%3Fpackage%3Dlocalstack.client.extensions%26source%3Dgithub%26track%3D2%26includeprerelease%3Dtrue%26label%3Dgithub)](https://github.com/localstack-dotnet/localstack-dotnet-client/pkgs/nuget/LocalStack.Client.Extensions) | - -## Table of Contents - -1. [Supported Platforms](#supported-platforms) -2. [Why LocalStack.NET Client?](#why-localstacknet-client) -3. [Prerequisites](#prerequisites) -4. [Getting Started](#getting-started) - - [Setup](#setup) - - [Configuration](#configuration) -5. [Known Issues](#known-issues) -6. [Developing](#developing) - - [Building the Project](#building-the-project) - - [Sandbox Applications](#sandbox-applications) - - [Running Tests](#running-tests) -7. [Changelog](#changelog) -8. [License](#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, .NET 10, and .NET Standard 2.0; Core also has an explicit .NET Framework 4.7.2 target. See [platform and packaging](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/architecture/platform-and-packaging.md) 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](https://docs.docker.com/get-docker/) or [docker-compose](https://docs.docker.com/compose/install/). - -**LocalStack needs an auth token.** From release 2026.03.0 on, every LocalStack for AWS image, including `localstack/localstack:latest`, requires a `LOCALSTACK_AUTH_TOKEN` to start ([announcement](https://blog.localstack.cloud/localstack-for-aws-release-2026-03-0/)). Without one, the container exits with a "License activation failed" error and LocalStack.NET has nothing to connect to. A free account is available: create it at [localstack.cloud](https://localstack.cloud/), copy your token from the LocalStack Web App, and pass it to the container: - -```bash -docker run --rm -it \ - -e LOCALSTACK_AUTH_TOKEN=$LOCALSTACK_AUTH_TOKEN \ - -p 4566:4566 \ - localstack/localstack -``` - -With docker-compose, add it under the LocalStack service: +[LocalStack](https://github.com/localstack/localstack) is a local AWS cloud emulator. LocalStack.NET wires AWS SDK for .NET v4 clients to LocalStack and lets you switch between LocalStack and real AWS with one configuration setting. LocalStack's [.NET guide](https://docs.localstack.cloud/aws/connecting/aws-sdks/dotnet/) lists LocalStack.NET as an alternative to configuring endpoints by hand. -```yaml -environment: - - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} -``` - -In CI, use a CI Auth Token stored in your CI provider's secret store; see the [Auth Token documentation](https://docs.localstack.cloud/aws/getting-started/auth-token/). - -The token is a LocalStack platform credential for the container. LocalStack.NET does not read it, and it does not replace the AWS credentials in the `LocalStack:Session` configuration. - -If you cannot use a token, `localstack/localstack:4.14.0` is the last release that starts without one. LocalStack keeps such earlier tags runnable without authentication but gives them no further service or security updates ([details](https://blog.localstack.cloud/the-road-ahead-for-localstack/)). +## Features -For detailed installation and setup instructions, please refer to the [official LocalStack installation guide](https://docs.localstack.cloud/aws/getting-started/installation/). +- Create LocalStack-configured AWS clients without manual endpoint code. +- Register clients through dependency injection with APIs that mirror `AWSSDK.Extensions.NETCore.Setup`. +- Switch client creation between LocalStack and AWS with `LocalStack:UseLocalStack`. +- Use Native AOT and trimming on `net10.0` and `net11.0` without changing consumer code. +- Run on .NET Framework 4.7.2 and later, and on other `netstandard2.0` runtimes. -## Getting Started +## Packages -LocalStack.NET is available through multiple package sources to support different development workflows. +| Package | Use it when | NuGet link | +| --- | --- | --- | +| `LocalStack.Client` (Core) | You create clients directly through a session. | [Core](https://www.nuget.org/packages/LocalStack.Client/) | +| `LocalStack.Client.Extensions` (Extensions) | You use .NET configuration and dependency injection. | [Extensions](https://www.nuget.org/packages/LocalStack.Client.Extensions/) | -### 📦 Package Installation - -To install the latest version of LocalStack.NET with AWS SDK v4 support, use the following command: +Install one package, plus the AWS SDK v4 service packages your app uses (for example, `AWSSDK.S3`). Extensions already depends on Core. ```bash -# 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 +dotnet add package LocalStack.Client.Extensions # configuration and dependency injection +dotnet add package LocalStack.Client # Core only ``` -#### Development Builds (GitHub Packages) +### Prerelease builds -For testing latest features and bug fixes: +Development builds are published to GitHub Packages at the feed shown below. +Authentication requires a GitHub personal access token with `read:packages` permission. +Replace the username and token placeholders below with your GitHub credentials. ```bash -# 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 + --name github-localstack --username YOUR_GITHUB_USERNAME --password YOUR_GITHUB_TOKEN \ + --store-password-in-clear-text dotnet add package LocalStack.Client.Extensions --prerelease --source github-localstack ``` -> **🔑 GitHub Packages Authentication**: You'll need a GitHub account and [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `read:packages` permission. - -Refer to [documentation](https://github.com/localstack-dotnet/localstack-dotnet-client/wiki/Getting-Started#installation) for more information on how to install LocalStack.NET. - -`LocalStack.NET` is a library that provides a wrapper around the [aws-sdk-net](https://github.com/aws/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](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config-netcore.html) with a few differences. For more on how to use the AWS SDK for .NET, see [Getting Started with the AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-setup.html). +## Supported frameworks -### Setup +| TFM | Core | Extensions | Native AOT | +| --- | --- | --- | --- | +| `netstandard2.0` | Yes | Yes | No | +| `net472` | Yes (.NET Framework 4.7.2+) | Uses `netstandard2.0` | No | +| `net10.0` | Yes | Yes | Yes | +| `net11.0` (preview) | Yes | Yes | Yes | -Here's a basic example of how to setup `LocalStack.NET`: +.NET 11 is not generally available yet; the `net11.0` assets are built with a .NET 11 preview SDK. +.NET 8 and .NET 9 apps use both packages' `netstandard2.0` assets under JIT, without Native AOT; both runtimes reach [end of support](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core) on November 10, 2026. -```csharp -public void ConfigureServices(IServiceCollection services) -{ - // Add framework services. - services.AddMvc(); - - services.AddLocalStack(Configuration); - services.AddDefaultAWSOptions(Configuration.GetAWSOptions()); - services.AddAwsService(); - services.AddAwsService(); -} -``` +## Prerequisites -`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](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/architecture/client-runtime.md) for what the endpoint catalog does—and does not—promise. +Run LocalStack with Docker or docker-compose; follow the [installation guide](https://docs.localstack.cloud/aws/getting-started/installation/). -(Alternatively, `AddAWSServiceLocalStack` method can be used to prevent mix-up with `AddAWSService`.) +From 2026.03.0 on, every LocalStack for AWS image (including `localstack/localstack:latest`) needs `LOCALSTACK_AUTH_TOKEN`, even on the Hobby plan, which is free for non-commercial use. +The token belongs to the container: LocalStack.NET does not read it, and it is not an AWS credential. +`localstack/localstack:4.14.0` is the last image that starts without a token; it receives no further updates. +See the official [auth-token documentation](https://docs.localstack.cloud/aws/getting-started/auth-token/) and [CI guidance](https://docs.localstack.cloud/aws/ci-pipelines/). -`AddLocalStack` extension method is responsible for both configurations and adding of `LocalStack.Client` dependencies to service collection. +## Quick start -### Configuration +In a minimal-hosting `Program.cs`, register LocalStack and your AWS service interfaces: -To configure LocalStack.NET, you can use entries in the appsettings.json files. Here's a basic example for different environments: +```csharp +using Amazon.S3; +using LocalStack.Client.Extensions; +using Microsoft.AspNetCore.Builder; +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; + +var builder = WebApplication.CreateBuilder(args); +builder.Services.AddLocalStack(builder.Configuration); +builder.Services.AddDefaultAWSOptions(builder.Configuration.GetAWSOptions()); +builder.Services.AddAwsService(); + +var app = builder.Build(); +app.Run(); +``` -`appsettings.Development.json` +`appsettings.Development.json` selects LocalStack: ```json -"LocalStack": { +{ + "LocalStack": { "UseLocalStack": true, "Session": { - "RegionName": "eu-central-1" + "RegionName": "eu-central-1" }, "Config": { - "LocalStackHost": "localhost.localstack.cloud", // or "localhost", - "EdgePort": 4566 + "LocalStackHost": "localhost.localstack.cloud", + "EdgePort": 4566 } + } } ``` -`appsettings.Production.json` +`appsettings.Production.json` selects the ordinary AWS SDK factory: ```json -"LocalStack": { +{ + "LocalStack": { "UseLocalStack": false -}, -"AWS": { + }, + "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](https://github.com/localstack-dotnet/localstack-dotnet-client/wiki/Setup#configuration). - -## 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` 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: +## Configuration - ```xml - - ``` +| Key | Default | +| --- | --- | +| `LocalStack:UseLocalStack` | `false` | +| `LocalStack:Session:AwsAccessKeyId` | `accessKey` | +| `LocalStack:Session:AwsAccessKey` | `secretKey` | +| `LocalStack:Session:AwsSessionToken` | `token` | +| `LocalStack:Session:RegionName` | `us-east-1` | +| `LocalStack:Config:LocalStackHost` | `localhost.localstack.cloud` | +| `LocalStack:Config:UseSsl` | `false` | +| `LocalStack:Config:UseLegacyPorts` | `false` (only for LocalStack before 0.11.5) | +| `LocalStack:Config:EdgePort` | `4566` | - See [issue #52](https://github.com/localstack-dotnet/localstack-dotnet-client/issues/52) for the full analysis. +LocalStack does not validate the dummy session credentials. +When `UseLocalStack` is `false`, the ordinary `AWS` section and `AddDefaultAWSOptions(configuration.GetAWSOptions())` from `AWSSDK.Extensions.NETCore.Setup` apply. -- **SNS with LocalStack v3.7.2 through v3.8.1:** SNS operations failed on LocalStack v3.7.2 and v3.8.0 because of a request-forwarding bug ([issue #11652](https://github.com/localstack/localstack/issues/11652)). The fix ([PR #11653](https://github.com/localstack/localstack/pull/11653)) was merged after v3.8.1 shipped and first appears in **v4.0.0**; no 3.x release contains it. Use LocalStack v4.0.0 or later, or v3.7.1 if you must stay on the 3.x line. +## Registering clients -- **Endpoint environment variables:** [Issue #27](https://github.com/localstack-dotnet/localstack-dotnet-client/issues/27#issuecomment-4937111791) 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. +`AddAwsService`, `TryAddAwsService`, `AddAWSServiceLocalStack`, and `TryAddAWSServiceLocalStack` each have two overloads: -Older notes about LocalStack v1 and v2 releases and AWS SDK v3 packages remain in the [v1.x README](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/sdkv3-lts/README.md#known-issues). +- `(ServiceLifetime lifetime = ServiceLifetime.Singleton, bool useServiceUrl = false)` +- `(AWSOptions? options, ServiceLifetime lifetime = ServiceLifetime.Singleton, bool useServiceUrl = false)` -## Developing +The `Try*` methods register a client only if its service type is not registered yet. `AddAWSServiceLocalStack` is an alias of `AddAwsService` that avoids confusion with the AWS SDK's `AddAWSService`. +`AddDefaultAwsOptions(AWSOptions)` delegates to the SDK's `AddDefaultAWSOptions`. -We appreciate contributions in the form of feedback, bug reports, and pull requests. +Every LocalStack client gets the configured session credentials (dummy values by default), `ProxyHost`/`ProxyPort` pointing at LocalStack, HTTP unless `UseSsl` is `true`, and S3 path-style addressing. +With `useServiceUrl: false`, the client also gets `RegionEndpoint` from `RegionName`, which must be set; `useServiceUrl: true` sets `ServiceURL` to the service's LocalStack URL instead. +This option configures a LocalStack client; `LocalStack:UseLocalStack` selects LocalStack or AWS client creation. -### Building the Project +```csharp +builder.Services.TryAddAwsService( + lifetime: ServiceLifetime.Singleton, useServiceUrl: true); +``` -To build the project, use the following commands based on your operating system: +## Using LocalStack.Client without dependency injection -Windows +Create a session with `SessionStandalone` and choose an implementation-based or interface-based client: -```powershell -build.ps1 -``` +```csharp +using Amazon.S3; +using LocalStack.Client; +using LocalStack.Client.Options; -Linux +var session = SessionStandalone.Init() + .WithSessionOptions(new SessionOptions()) + .WithConfigurationOptions(new ConfigOptions()) + .Create(); -```bash -./build.sh +using var s3 = session.CreateClientByImplementation(); +using var s3ByInterface = session.CreateClientByInterface(); ``` -### Sandbox Applications - -The LocalStack .NET repository includes several sandbox console applications located in [tests/sandboxes](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/master/tests/sandboxes). These applications serve both as testing tools and as examples. Refer to [the documentation](https://github.com/localstack-dotnet/localstack-dotnet-client/wiki/Developing#sandbox-applications) for more information - -### Running Tests +The `Type`-based overloads are `CreateClientByImplementation(Type implType, bool useServiceUrl = false)` and `CreateClientByInterface(Type serviceInterfaceType, bool useServiceUrl = false)`. -To execute the tests, use the commands below: +## Native AOT and trimming -Windows +On `net10.0` and `net11.0`, both packages support Native AOT and trimming with no consumer code changes, zero trim/AOT warnings and no suppressions. They use no runtime reflection for AWS SDK service clients and configs, or for custom clients that follow the SDK's shape; other client types keep a reflection fallback that runs only under JIT. The `Type`-based APIs rely on a source generator that runs in C# projects, so F# and Visual Basic apps should use the generic APIs under Native AOT. These statements cover LocalStack.NET's own code; the AWS SDK and LocalStack's service coverage have their own status. See [platform and packaging](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/architecture/platform-and-packaging.md#native-aot-and-trimming) for the exact boundary. -```powershell -build.ps1 --target=tests -``` +## Versions and support -Linux +3.x (AWS SDK v4) is the supported line, developed on `master`; earlier versions are not supported. .NET 8 and .NET 9 apps use the `netstandard2.0` assets under JIT, without Native AOT. See the [changelog](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) for release details and the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md) for the patch policy. -```bash -./build.sh --target=tests -``` +## Known issues -## Community +- **SNS with LocalStack v3.7.2 through v3.8.1:** SNS operations failed on LocalStack v3.7.2 and v3.8.0 because of a request-forwarding bug ([issue #11652](https://github.com/localstack/localstack/issues/11652)). The fix ([PR #11653](https://github.com/localstack/localstack/pull/11653)) was merged after v3.8.1 shipped and first appears in **v4.0.0**; no 3.x release contains it. Use LocalStack v4.0.0 or later, or v3.7.1 if you must stay on the 3.x line. +- **Endpoint environment variables:** With `UseLocalStack: true`, the LocalStack proxy settings took precedence over `AWS_ENDPOINT_URL` in a reported SQS case; with `UseLocalStack: false`, `AWS_ENDPOINT_URL` applied. The library defines no general precedence rule for `AWS_ENDPOINT_URL` or `AWS_SERVICE_URL`, so check the actual SDK configuration before relying on either. See [#27](https://github.com/localstack-dotnet/localstack-dotnet-client/issues/27#issuecomment-4937111791). -Got questions or wild feature ideas? +## Contributing -👉 Join the conversation in [GitHub Discussions](https://github.com/localstack-dotnet/localstack-dotnet-client/discussions). +See the [contribution guide](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/CONTRIBUTING.md) for build, sandbox, and test instructions. Ask questions and share ideas in [Discussions](https://github.com/localstack-dotnet/localstack-dotnet-client/discussions). ## Changelog -Please refer to [`CHANGELOG.md`](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) to see the complete list of changes for each release. +Read the [changelog](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) for changes in each release. ## License -Licensed under MIT, see [LICENSE](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/LICENSE) for the full text. +LocalStack.NET uses the [MIT License](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/LICENSE). diff --git a/src/LocalStack.Client/README.md b/src/LocalStack.Client/README.md index c9520b1..a5be0c3 100644 --- a/src/LocalStack.Client/README.md +++ b/src/LocalStack.Client/README.md @@ -1,274 +1,195 @@ -# LocalStack .NET Client +# LocalStack.NET -[![Nuget](https://img.shields.io/nuget/dt/LocalStack.Client)](https://www.nuget.org/packages/LocalStack.Client/) [![NuGet v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2F%3Fpackage%3Dlocalstack.client%26source%3Dnuget%26track%3D2%26includeprerelease%3Dtrue%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client/) [![NuGet v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2F%3Fpackage%3Dlocalstack.client%26source%3Dnuget%26track%3D1%26includeprerelease%3Dtrue%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client/) [![CI/CD Pipeline](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml) [![Security](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql) [![Linux Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/linux?label=Tests)](https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/redirect/test-results/linux) - -> **🚀 Quick Start**: `dotnet add package LocalStack.Client --version 2.0.0` (AWS SDK v4) | [Package installation](#-package-installation) | [Migration context](https://github.com/orgs/localstack-dotnet/discussions/45) - ---- - -## 🎉 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](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/engineering/quality-gates.md) 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](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) before upgrading. - -**Version Strategy**: - -- v2.x (AWS SDK v4) active development on [master branch](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/master) -- v1.x (AWS SDK v3) remains available on the [sdkv3-lts branch](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/sdkv3-lts), but support ended in July 2026. Use v2.x for maintained releases; see the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md). +[![LocalStack.Client](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dnuget%26label%3DLocalStack.Client)](https://www.nuget.org/packages/LocalStack.Client/) [![LocalStack.Client.Extensions](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client.extensions%3Fsource%3Dnuget%26label%3DLocalStack.Client.Extensions)](https://www.nuget.org/packages/LocalStack.Client.Extensions/) [![Downloads](https://img.shields.io/nuget/dt/LocalStack.Client)](https://www.nuget.org/packages/LocalStack.Client/) [![CI/CD Pipeline](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml) [![Security](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql) [![Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/linux?label=Tests)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml) ![LocalStack](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/assets/localstack-dotnet.png?raw=true) -LocalStack.NET is a .NET client library for [LocalStack](https://github.com/localstack/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](https://dotnet.microsoft.com/download/dotnet/8.0) | [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) | [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) -- [.NET Standard 2.0](https://docs.microsoft.com/en-us/dotnet/standard/net-standard) -- [.NET Framework 4.7.2 and Above](https://dotnet.microsoft.com/download/dotnet-framework) - -## ⚡ Native AOT & Trimming Status - -- **Unreleased:** Native AOT support preserves existing C# calls such as `AddLocalStack(configuration)`, `AddAwsService()`, and Core `Session` calls. Source generation flows automatically through either package; no new registration or factory API is required. It roots existing reflection operations rather than removing reflection. -- Local-package consumers have been validated with Native AOT and its mandatory trimming on .NET 10 for `win-x64` and `linux-x64`, including S3 `ListBucketsAsync` and JIT parity for endpoint, region, credentials, and configured values. This does not establish support for every service, operation, or native target, or for separately trimmed JIT deployments. Do not suppress trim/AOT warnings. -- This implementation is **not part of the published Core 2.0.0 / Extensions 2.0.1 releases**. See the [platform boundary](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/architecture/platform-and-packaging.md#native-aot-and-trimming) for scope and the [Native AOT decision](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/adr/0004-native-aot-preserves-existing-consumer-code.md) for the unchanged-consumer contract. - -### Build & Test Matrix - -| Category | Platform/Type | Status | Description | -|----------|---------------|--------|-------------| -| **🔧 Build** | Cross-Platform | [![CI/CD Pipeline](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/ci-cd.yml) | Matrix testing: Windows, Linux, macOS | -| **🔒 Security** | Static Analysis | [![Security](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/localstack-dotnet/localstack-dotnet-client/actions/workflows/github-code-scanning/codeql) | CodeQL analysis & dependency review | -| **🧪 Tests** | Linux | [![Linux Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/linux?label=Tests)](https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/redirect/test-results/linux) | All framework targets | -| **🧪 Tests** | Windows | [![Windows Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/windows?label=Tests)](https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/redirect/test-results/windows) | All framework targets | -| **🧪 Tests** | macOS | [![macOS Tests](https://img.shields.io/endpoint?url=https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/badge/tests/macos?label=Tests)](https://yvfdbfas85.execute-api.eu-central-1.amazonaws.com/live/redirect/test-results/macos) | All framework targets | - -## Package Status - -| Package | NuGet.org | GitHub Packages (development builds) | -|---------|-----------|---------------------------| -| **LocalStack.Client v1.x** | [![NuGet v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dnuget%26track%3D1%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client/) | [![Github v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dgithub%26track%3D1%26includeprerelease%3Dtrue%26label%3Dgithub)](https://github.com/localstack-dotnet/localstack-dotnet-client/pkgs/nuget/LocalStack.Client) | -| **LocalStack.Client v2.x** | [![NuGet v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dnuget%26track%3D2%26includeprerelease%3Dtrue%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client/) | [![Github v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client%3Fsource%3Dgithub%26track%3D2%26includeprerelease%3Dtrue%26label%3Dgithub)](https://github.com/localstack-dotnet/localstack-dotnet-client/pkgs/nuget/LocalStack.Client) | -| **LocalStack.Client.Extensions v1.x** | [![NuGet v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client.extensions%3Fsource%3Dnuget%26track%3D1%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client.Extensions/) | [![Github v1.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client.extensions%3Fsource%3Dgithub%26track%3D1%26includeprerelease%3Dtrue%26label%3Dgithub)](https://github.com/localstack-dotnet/localstack-dotnet-client/pkgs/nuget/LocalStack.Client.Extensions) | -| **LocalStack.Client.Extensions v2.x** | [![NuGet v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2Fbadge%2Fpackages%2Flocalstack.client.extensions%3Fsource%3Dnuget%26track%3D2%26includeprerelease%3Dtrue%26label%3Dnuget)](https://www.nuget.org/packages/LocalStack.Client.Extensions/) | [![GitHub Packages v2.x](https://img.shields.io/endpoint?url=https%3A%2F%2Fyvfdbfas85.execute-api.eu-central-1.amazonaws.com%2Flive%2F%3Fpackage%3Dlocalstack.client.extensions%26source%3Dgithub%26track%3D2%26includeprerelease%3Dtrue%26label%3Dgithub)](https://github.com/localstack-dotnet/localstack-dotnet-client/pkgs/nuget/LocalStack.Client.Extensions) | - -## Table of Contents - -1. [Supported Platforms](#supported-platforms) -2. [Why LocalStack.NET Client?](#why-localstacknet-client) -3. [Prerequisites](#prerequisites) -4. [Getting Started](#getting-started) - - [Setup](#setup) - - [Configuration](#configuration) -5. [Known Issues](#known-issues) -6. [Developing](#developing) - - [Building the Project](#building-the-project) - - [Sandbox Applications](#sandbox-applications) - - [Running Tests](#running-tests) -7. [Changelog](#changelog) -8. [License](#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, .NET 10, and .NET Standard 2.0; Core also has an explicit .NET Framework 4.7.2 target. See [platform and packaging](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/architecture/platform-and-packaging.md) 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](https://docs.docker.com/get-docker/) or [docker-compose](https://docs.docker.com/compose/install/). - -**LocalStack needs an auth token.** From release 2026.03.0 on, every LocalStack for AWS image, including `localstack/localstack:latest`, requires a `LOCALSTACK_AUTH_TOKEN` to start ([announcement](https://blog.localstack.cloud/localstack-for-aws-release-2026-03-0/)). Without one, the container exits with a "License activation failed" error and LocalStack.NET has nothing to connect to. A free account is available: create it at [localstack.cloud](https://localstack.cloud/), copy your token from the LocalStack Web App, and pass it to the container: - -```bash -docker run --rm -it \ - -e LOCALSTACK_AUTH_TOKEN=$LOCALSTACK_AUTH_TOKEN \ - -p 4566:4566 \ - localstack/localstack -``` - -With docker-compose, add it under the LocalStack service: +[LocalStack](https://github.com/localstack/localstack) is a local AWS cloud emulator. LocalStack.NET wires AWS SDK for .NET v4 clients to LocalStack and lets you switch between LocalStack and real AWS with one configuration setting. LocalStack's [.NET guide](https://docs.localstack.cloud/aws/connecting/aws-sdks/dotnet/) lists LocalStack.NET as an alternative to configuring endpoints by hand. -```yaml -environment: - - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} -``` - -In CI, use a CI Auth Token stored in your CI provider's secret store; see the [Auth Token documentation](https://docs.localstack.cloud/aws/getting-started/auth-token/). - -The token is a LocalStack platform credential for the container. LocalStack.NET does not read it, and it does not replace the AWS credentials in the `LocalStack:Session` configuration. - -If you cannot use a token, `localstack/localstack:4.14.0` is the last release that starts without one. LocalStack keeps such earlier tags runnable without authentication but gives them no further service or security updates ([details](https://blog.localstack.cloud/the-road-ahead-for-localstack/)). +## Features -For detailed installation and setup instructions, please refer to the [official LocalStack installation guide](https://docs.localstack.cloud/aws/getting-started/installation/). +- Create LocalStack-configured AWS clients without manual endpoint code. +- Register clients through dependency injection with APIs that mirror `AWSSDK.Extensions.NETCore.Setup`. +- Switch client creation between LocalStack and AWS with `LocalStack:UseLocalStack`. +- Use Native AOT and trimming on `net10.0` and `net11.0` without changing consumer code. +- Run on .NET Framework 4.7.2 and later, and on other `netstandard2.0` runtimes. -## Getting Started +## Packages -LocalStack.NET is available through multiple package sources to support different development workflows. +| Package | Use it when | NuGet link | +| --- | --- | --- | +| `LocalStack.Client` (Core) | You create clients directly through a session. | [Core](https://www.nuget.org/packages/LocalStack.Client/) | +| `LocalStack.Client.Extensions` (Extensions) | You use .NET configuration and dependency injection. | [Extensions](https://www.nuget.org/packages/LocalStack.Client.Extensions/) | -### 📦 Package Installation - -To install the latest version of LocalStack.NET with AWS SDK v4 support, use the following command: +Install one package, plus the AWS SDK v4 service packages your app uses (for example, `AWSSDK.S3`). Extensions already depends on Core. ```bash -# 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 +dotnet add package LocalStack.Client.Extensions # configuration and dependency injection +dotnet add package LocalStack.Client # Core only ``` -#### Development Builds (GitHub Packages) +### Prerelease builds -For testing latest features and bug fixes: +Development builds are published to GitHub Packages at the feed shown below. +Authentication requires a GitHub personal access token with `read:packages` permission. +Replace the username and token placeholders below with your GitHub credentials. ```bash -# 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 + --name github-localstack --username YOUR_GITHUB_USERNAME --password YOUR_GITHUB_TOKEN \ + --store-password-in-clear-text dotnet add package LocalStack.Client.Extensions --prerelease --source github-localstack ``` -> **🔑 GitHub Packages Authentication**: You'll need a GitHub account and [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with `read:packages` permission. - -Refer to [documentation](https://github.com/localstack-dotnet/localstack-dotnet-client/wiki/Getting-Started#installation) for more information on how to install LocalStack.NET. - -`LocalStack.NET` is a library that provides a wrapper around the [aws-sdk-net](https://github.com/aws/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](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/net-dg-config-netcore.html) with a few differences. For more on how to use the AWS SDK for .NET, see [Getting Started with the AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/net-dg-setup.html). +## Supported frameworks -### Setup +| TFM | Core | Extensions | Native AOT | +| --- | --- | --- | --- | +| `netstandard2.0` | Yes | Yes | No | +| `net472` | Yes (.NET Framework 4.7.2+) | Uses `netstandard2.0` | No | +| `net10.0` | Yes | Yes | Yes | +| `net11.0` (preview) | Yes | Yes | Yes | -Here's a basic example of how to setup `LocalStack.NET`: +.NET 11 is not generally available yet; the `net11.0` assets are built with a .NET 11 preview SDK. +.NET 8 and .NET 9 apps use both packages' `netstandard2.0` assets under JIT, without Native AOT; both runtimes reach [end of support](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core) on November 10, 2026. -```csharp -public void ConfigureServices(IServiceCollection services) -{ - // Add framework services. - services.AddMvc(); - - services.AddLocalStack(Configuration); - services.AddDefaultAWSOptions(Configuration.GetAWSOptions()); - services.AddAwsService(); - services.AddAwsService(); -} -``` +## Prerequisites -`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](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/architecture/client-runtime.md) for what the endpoint catalog does—and does not—promise. +Run LocalStack with Docker or docker-compose; follow the [installation guide](https://docs.localstack.cloud/aws/getting-started/installation/). -(Alternatively, `AddAWSServiceLocalStack` method can be used to prevent mix-up with `AddAWSService`.) +From 2026.03.0 on, every LocalStack for AWS image (including `localstack/localstack:latest`) needs `LOCALSTACK_AUTH_TOKEN`, even on the Hobby plan, which is free for non-commercial use. +The token belongs to the container: LocalStack.NET does not read it, and it is not an AWS credential. +`localstack/localstack:4.14.0` is the last image that starts without a token; it receives no further updates. +See the official [auth-token documentation](https://docs.localstack.cloud/aws/getting-started/auth-token/) and [CI guidance](https://docs.localstack.cloud/aws/ci-pipelines/). -`AddLocalStack` extension method is responsible for both configurations and adding of `LocalStack.Client` dependencies to service collection. +## Quick start -### Configuration +In a minimal-hosting `Program.cs`, register LocalStack and your AWS service interfaces: -To configure LocalStack.NET, you can use entries in the appsettings.json files. Here's a basic example for different environments: +```csharp +using Amazon.S3; +using LocalStack.Client.Extensions; +using Microsoft.AspNetCore.Builder; +using Microsoft.Extensions.Configuration; +using Microsoft.Extensions.DependencyInjection; + +var builder = WebApplication.CreateBuilder(args); +builder.Services.AddLocalStack(builder.Configuration); +builder.Services.AddDefaultAWSOptions(builder.Configuration.GetAWSOptions()); +builder.Services.AddAwsService(); + +var app = builder.Build(); +app.Run(); +``` -`appsettings.Development.json` +`appsettings.Development.json` selects LocalStack: ```json -"LocalStack": { +{ + "LocalStack": { "UseLocalStack": true, "Session": { - "RegionName": "eu-central-1" + "RegionName": "eu-central-1" }, "Config": { - "LocalStackHost": "localhost.localstack.cloud", // or "localhost", - "EdgePort": 4566 + "LocalStackHost": "localhost.localstack.cloud", + "EdgePort": 4566 } + } } ``` -`appsettings.Production.json` +`appsettings.Production.json` selects the ordinary AWS SDK factory: ```json -"LocalStack": { +{ + "LocalStack": { "UseLocalStack": false -}, -"AWS": { + }, + "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](https://github.com/localstack-dotnet/localstack-dotnet-client/wiki/Setup#configuration). - -## 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` 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: +## Configuration - ```xml - - ``` +| Key | Default | +| --- | --- | +| `LocalStack:UseLocalStack` | `false` | +| `LocalStack:Session:AwsAccessKeyId` | `accessKey` | +| `LocalStack:Session:AwsAccessKey` | `secretKey` | +| `LocalStack:Session:AwsSessionToken` | `token` | +| `LocalStack:Session:RegionName` | `us-east-1` | +| `LocalStack:Config:LocalStackHost` | `localhost.localstack.cloud` | +| `LocalStack:Config:UseSsl` | `false` | +| `LocalStack:Config:UseLegacyPorts` | `false` (only for LocalStack before 0.11.5) | +| `LocalStack:Config:EdgePort` | `4566` | - See [issue #52](https://github.com/localstack-dotnet/localstack-dotnet-client/issues/52) for the full analysis. +LocalStack does not validate the dummy session credentials. +When `UseLocalStack` is `false`, the ordinary `AWS` section and `AddDefaultAWSOptions(configuration.GetAWSOptions())` from `AWSSDK.Extensions.NETCore.Setup` apply. -- **SNS with LocalStack v3.7.2 through v3.8.1:** SNS operations failed on LocalStack v3.7.2 and v3.8.0 because of a request-forwarding bug ([issue #11652](https://github.com/localstack/localstack/issues/11652)). The fix ([PR #11653](https://github.com/localstack/localstack/pull/11653)) was merged after v3.8.1 shipped and first appears in **v4.0.0**; no 3.x release contains it. Use LocalStack v4.0.0 or later, or v3.7.1 if you must stay on the 3.x line. +## Registering clients -- **Endpoint environment variables:** [Issue #27](https://github.com/localstack-dotnet/localstack-dotnet-client/issues/27#issuecomment-4937111791) 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. +`AddAwsService`, `TryAddAwsService`, `AddAWSServiceLocalStack`, and `TryAddAWSServiceLocalStack` each have two overloads: -Older notes about LocalStack v1 and v2 releases and AWS SDK v3 packages remain in the [v1.x README](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/sdkv3-lts/README.md#known-issues). +- `(ServiceLifetime lifetime = ServiceLifetime.Singleton, bool useServiceUrl = false)` +- `(AWSOptions? options, ServiceLifetime lifetime = ServiceLifetime.Singleton, bool useServiceUrl = false)` -## Developing +The `Try*` methods register a client only if its service type is not registered yet. `AddAWSServiceLocalStack` is an alias of `AddAwsService` that avoids confusion with the AWS SDK's `AddAWSService`. +`AddDefaultAwsOptions(AWSOptions)` delegates to the SDK's `AddDefaultAWSOptions`. -We appreciate contributions in the form of feedback, bug reports, and pull requests. +Every LocalStack client gets the configured session credentials (dummy values by default), `ProxyHost`/`ProxyPort` pointing at LocalStack, HTTP unless `UseSsl` is `true`, and S3 path-style addressing. +With `useServiceUrl: false`, the client also gets `RegionEndpoint` from `RegionName`, which must be set; `useServiceUrl: true` sets `ServiceURL` to the service's LocalStack URL instead. +This option configures a LocalStack client; `LocalStack:UseLocalStack` selects LocalStack or AWS client creation. -### Building the Project +```csharp +builder.Services.TryAddAwsService( + lifetime: ServiceLifetime.Singleton, useServiceUrl: true); +``` -To build the project, use the following commands based on your operating system: +## Using LocalStack.Client without dependency injection -Windows +Create a session with `SessionStandalone` and choose an implementation-based or interface-based client: -```powershell -build.ps1 -``` +```csharp +using Amazon.S3; +using LocalStack.Client; +using LocalStack.Client.Options; -Linux +var session = SessionStandalone.Init() + .WithSessionOptions(new SessionOptions()) + .WithConfigurationOptions(new ConfigOptions()) + .Create(); -```bash -./build.sh +using var s3 = session.CreateClientByImplementation(); +using var s3ByInterface = session.CreateClientByInterface(); ``` -### Sandbox Applications - -The LocalStack .NET repository includes several sandbox console applications located in [tests/sandboxes](https://github.com/localstack-dotnet/localstack-dotnet-client/tree/master/tests/sandboxes). These applications serve both as testing tools and as examples. Refer to [the documentation](https://github.com/localstack-dotnet/localstack-dotnet-client/wiki/Developing#sandbox-applications) for more information - -### Running Tests +The `Type`-based overloads are `CreateClientByImplementation(Type implType, bool useServiceUrl = false)` and `CreateClientByInterface(Type serviceInterfaceType, bool useServiceUrl = false)`. -To execute the tests, use the commands below: +## Native AOT and trimming -Windows +On `net10.0` and `net11.0`, both packages support Native AOT and trimming with no consumer code changes, zero trim/AOT warnings and no suppressions. They use no runtime reflection for AWS SDK service clients and configs, or for custom clients that follow the SDK's shape; other client types keep a reflection fallback that runs only under JIT. The `Type`-based APIs rely on a source generator that runs in C# projects, so F# and Visual Basic apps should use the generic APIs under Native AOT. These statements cover LocalStack.NET's own code; the AWS SDK and LocalStack's service coverage have their own status. See [platform and packaging](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/docs/architecture/platform-and-packaging.md#native-aot-and-trimming) for the exact boundary. -```powershell -build.ps1 --target=tests -``` +## Versions and support -Linux +3.x (AWS SDK v4) is the supported line, developed on `master`; earlier versions are not supported. .NET 8 and .NET 9 apps use the `netstandard2.0` assets under JIT, without Native AOT. See the [changelog](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) for release details and the [security policy](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/SECURITY.md) for the patch policy. -```bash -./build.sh --target=tests -``` +## Known issues -## Community +- **SNS with LocalStack v3.7.2 through v3.8.1:** SNS operations failed on LocalStack v3.7.2 and v3.8.0 because of a request-forwarding bug ([issue #11652](https://github.com/localstack/localstack/issues/11652)). The fix ([PR #11653](https://github.com/localstack/localstack/pull/11653)) was merged after v3.8.1 shipped and first appears in **v4.0.0**; no 3.x release contains it. Use LocalStack v4.0.0 or later, or v3.7.1 if you must stay on the 3.x line. +- **Endpoint environment variables:** With `UseLocalStack: true`, the LocalStack proxy settings took precedence over `AWS_ENDPOINT_URL` in a reported SQS case; with `UseLocalStack: false`, `AWS_ENDPOINT_URL` applied. The library defines no general precedence rule for `AWS_ENDPOINT_URL` or `AWS_SERVICE_URL`, so check the actual SDK configuration before relying on either. See [#27](https://github.com/localstack-dotnet/localstack-dotnet-client/issues/27#issuecomment-4937111791). -Got questions or wild feature ideas? +## Contributing -👉 Join the conversation in [GitHub Discussions](https://github.com/localstack-dotnet/localstack-dotnet-client/discussions). +See the [contribution guide](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/.github/CONTRIBUTING.md) for build, sandbox, and test instructions. Ask questions and share ideas in [Discussions](https://github.com/localstack-dotnet/localstack-dotnet-client/discussions). ## Changelog -Please refer to [`CHANGELOG.md`](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) to see the complete list of changes for each release. +Read the [changelog](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/CHANGELOG.md) for changes in each release. ## License -Licensed under MIT, see [LICENSE](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/LICENSE) for the full text. +LocalStack.NET uses the [MIT License](https://github.com/localstack-dotnet/localstack-dotnet-client/blob/master/LICENSE).