Extensions for the LocalStack.NET Client to integrate with .NET Core configuration and dependency injection frameworks. The extensions also provides wrapper around AWSSDK.Extensions.NETCore.Setup to use both LocalStack and AWS side-by-side
Localstack.NET is an easy-to-use .NET client for LocalStack, a fully functional local AWS cloud stack. The client library provides a thin wrapper around aws-sdk-net which automatically configures the target endpoints to use LocalStack for your local cloud application development.
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: Supports a broad spectrum of .NET versions, from .NET 9.0 and .NET Standard 2.0 to .NET Framework 4.6.2 and above.
Reduced Learning Curve: Offers a familiar interface tailored for LocalStack, ideal for developers acquainted with the AWS SDK for .NET.
Enhanced Development Speed: Reduces boilerplate and manual configurations, speeding up the development process.
Prerequisites
To utilize this library, you need to have LocalStack running. While LocalStack can be installed directly on your machine and accessed via the localstack cli, the recommended approach is to run LocalStack using Docker or docker-compose.
LocalStack.NET is installed from NuGet. To work with LocalStack in your .NET applications, you'll need the main library and its extensions. Here's how you can install them:
The AddLocalStack method integrates LocalStack.NET into your application, and the AddAwsService method allows you to specify which AWS services you want to use with LocalStack.
(Alternatively, AddAWSServiceLocalStack method can be used to prevent mix-up with AddAWSService.)
AddLocalStack extension method is responsible for both configurations and adding of LocalStack.Client dependencies to service collection.
Configuration
To configure LocalStack.NET, you can use entries in the appsettings.json files. Here's a basic example for different environments:
The RegionName is important as LocalStack creates resources based on the specified region. For more advanced configurations and understanding how LocalStack.NET operates with LocalStack, refer to documentation.
Known Issues
SNS with LocalStack v3.7.2 and v3.8.0: During development on the new version, it was discovered that SNS functional tests are not working in LocalStack versions v3.7.2 and v3.8.0. This issue was reported in LocalStack issue #11652. The LocalStack team identified a bug related to handling SNS URIs and resolved it in PR #11653. The fix will be included in an upcoming release of LocalStack. In the meantime, if you're using SNS, it is recommended to stick to version v3.7.1 of LocalStack until the fix is available.
LocalStack Versions v2.0.1 - v2.2: In versions v2.0.1 through v2.2 of LocalStack, the URL routing logic was changed, causing issues with SQS and S3 operations. Two issues were opened in LocalStack regarding this: issue #8928 and issue #8924. LocalStack addressed this problem with PR #8962. Therefore, when using LocalStack.NET, either use version v2.0 of LocalStack (there are no issues with the v1 series as well) or the upcoming v2.3 version, or use the latest v3 series container from Docker Hub.
AWS_SERVICE_URL Environment Variable: Unexpected behaviors might occur in LocalStack.NET when the AWS_SERVICE_URL environment variable is set. This environment variable is typically set by LocalStack in the container when using AWS Lambda, and AWS also uses this environment variable in the live environment. Soon, just like in LocalStack's official Python library, this environment variable will be prioritized by LocalStack.NET when configuring the LocalStack host, and there will be a general simplification in the configuration. You can follow this in the issues issue #27 and issue #32. You set the AWS_SERVICE_URL to empty string until this issue is resolved.
IAmazonLambda Operations: There's a general issue with IAmazonLambda operations. This matter is currently under investigation.
AWSSDK.SQS Compatibility: Starting from version 3.7.300.* of AWSSDK.SQS, there are compatibility issues with LocalStack v1 and v2 series versions. The v3 series of LocalStack does not have these issues. Therefore, it is recommended to either update your LocalStack container to the v3 series or downgrade your AWSSDK.SQS to version 3.7.200.* if you are using LocalStack v1 or v2 series containers. It is important to note that this is not a problem related to LocalStack.NET, but rather an issue with the LocalStack container and the AWS SDK for .NET.
Developing
We appreciate contributions in the form of feedback, bug reports, and pull requests.
Building the Project
To build the project, use the following commands based on your operating system:
Windows
build.ps1
Linux
./build.sh
Sandbox Applications
The LocalStack .NET repository includes several sandbox console applications located in tests/sandboxes. These applications serve both as testing tools and as examples. Refer to the documentation for more information
Running Tests
To execute the tests, use the commands below:
Windows
build.ps1 --target=tests
Linux
./build.sh --target=tests
Changelog
Please refer to CHANGELOG.md to see the complete list of changes for each release.
License
Licensed under MIT, see LICENSE for the full text.
