LocalStack.Client.Extensions 1.2.2

dotnet add package LocalStack.Client.Extensions --version 1.2.2
NuGet\Install-Package LocalStack.Client.Extensions -Version 1.2.2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="LocalStack.Client.Extensions" Version="1.2.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add LocalStack.Client.Extensions --version 1.2.2
#r "nuget: LocalStack.Client.Extensions, 1.2.2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install LocalStack.Client.Extensions as a Cake Addin
#addin nuget:?package=LocalStack.Client.Extensions&version=1.2.2

// Install LocalStack.Client.Extensions as a Cake Tool
#tool nuget:?package=LocalStack.Client.Extensions&version=1.2.2

LocalStack .NET Client Nuget NuGet Space Metric

LocalStack

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.

Package Stable Nightly
LocalStack.Client NuGet MyGet
LocalStack.Client.Extensions NuGet MyGet

Continuous Integration

Build server Platform Build status
Github Actions Ubuntu build-ubuntu
Github Actions Windows build-windows
Github Actions macOS build-macos

Table of Contents

  1. Supported Platforms
  2. Why LocalStack.NET Client?
  3. Prerequisites
  4. Getting Started
  5. Known Issues
  6. Developing
  7. Changelog
  8. License

Supported Platforms

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: Supports a broad spectrum of .NET versions, from .NET 7.0 and .NET Standard 2.0 to .NET Framework 4.6.1 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.

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

Getting Started

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:

dotnet add package LocalStack.Client
dotnet add package LocalStack.Client.Extensions

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

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

Setup

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

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

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

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.

<e><b>(Alternatively, AddAWSServiceLocalStack method can be used to prevent mix-up with AddAWSService.)</b></e>

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

Configuration

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

appsettings.Development.json

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

appsettings.Production.json

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

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

Known Issues

  • 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 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.

Environment.SetEnvironmentVariable("AWS_SERVICE_URL", string.Empty);
  • IAmazonLambda Operations: There's a general issue with IAmazonLambda operations. This matter is currently under investigation.

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.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on LocalStack.Client.Extensions:

Package Downloads
Olive.Entities.Data.DynamoDB

Olive Framework

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.2.2 86,786 9/22/2023
1.2.1 3,205 9/10/2023
1.2.0 130,519 2/1/2023
1.1.3 228,395 4/20/2022
1.1.2 107,923 11/28/2021
1.1.1 1,117 11/18/2021
1.1.0 70,343 5/24/2021
1.0.0 66,917 2/8/2021