localstack-dotnet-client - LocalStack.Client 1.3.1

This is an easy-to-use .NET client for LocalStack. 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.

PM> Install-Package LocalStack.Client -Version 1.3.1 -Source https://www.myget.org/F/localstack-dotnet-client/api/v3/index.json

Copy to clipboard

> nuget.exe install LocalStack.Client -Version 1.3.1 -Source https://www.myget.org/F/localstack-dotnet-client/api/v3/index.json

Copy to clipboard

> dotnet add package LocalStack.Client --version 1.3.1 --source https://www.myget.org/F/localstack-dotnet-client/api/v3/index.json

Copy to clipboard
<PackageReference Include="LocalStack.Client" Version="1.3.1" />
Copy to clipboard
source https://www.myget.org/F/localstack-dotnet-client/api/v3/index.json

nuget LocalStack.Client  ~> 1.3.1
Copy to clipboard

> choco install LocalStack.Client --version 1.3.1 --source https://www.myget.org/F/localstack-dotnet-client/api/v2

Copy to clipboard
Import-Module PowerShellGet
Register-PSRepository -Name "localstack-dotnet-client" -SourceLocation "https://www.myget.org/F/localstack-dotnet-client/api/v2"
Install-Module -Name "LocalStack.Client" -RequiredVersion "1.3.1" -Repository "localstack-dotnet-client" 
Copy to clipboard

Nuget NuGet Testspace tests (compact)

LocalStack .Net Core and .Net Framework Client

LocalStack

This is an easy-to-use .NET client for LocalStack. 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.

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. Prerequisites
  3. Installation
  4. Usage
  5. Developing
  6. Changelog
  7. License

Supported Platforms

Prerequisites

To make use of this library, you need to have LocalStack installed on your local machine. In particular, the localstack command needs to be available.

Installation

The easiest way to install LocalStack .NET Client is via nuget:

Install-Package LocalStack.Client

Or use dotnet cli

dotnet add package LocalStack.Client
Package Stable Nightly
LocalStack.Client NuGet MyGet
LocalStack.Client.Extensions NuGet MyGet

Usage

This library provides a thin wrapper around aws-sdk-net. Therefore the usage of this library is same as using AWS SDK for .NET.

See Getting Started with the AWS SDK for .NET

This library can be used with any DI library, AWSSDK.Extensions.NETCore.Setup or it can be used as standalone.

LocalStack.Client.Extensions (Recommended)

LocalStack.Client.Extensions is 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.

This approach is recommended since AWSSDK.Extensions.NETCore.Setup is very popular and also it is best practice for using AWSSDK.NET with .NET Core, .NET 5 or .NET 6

Installation

The easiest way to install LocalStack .NET Client Extensions is via nuget:

Install-Package LocalStack.Client.Extensions

Or use dotnet cli

dotnet add package LocalStack.Client.Extensions  

Usage

The usage is very similar to AWSSDK.Extensions.NETCore.Setup with some differences.

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

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

The most important difference is that AddAwsService extensions method is used instead of AddAWSService used in AWSSDK.Extensions.NETCore.Setup. The reason for this will be explained later in this section.

In addition, the AddLocalStack extension method is also used.

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

You can configure LocalStack.Client by using entries in the appsettings.json files, as shown in the following example.

"LocalStack": {
    "UseLocalStack": true,
    "Session": {
        "AwsAccessKeyId": "my-AwsAccessKeyId",
        "AwsAccessKey": "my-AwsAccessKey",
        "AwsSessionToken": "my-AwsSessionToken",
        "RegionName": "eu-central-1"
    },
    "Config": {
        "LocalStackHost": "localhost",
        "UseSsl": false,
        "UseLegacyPorts": false,
        "EdgePort": 4566
    }
}

All the entries above are has shown with default values (except UseLocalStack, it's false by default). So the above entries do not need to be specified.

What is entered for the aws credential values ​​in the Session section does not matter for LocalStack.

RegionName is important since LocalStack creates resources by spesified region.

Config section contains important entries for local development. Starting with LocalStack releases after v0.11.5, all services are now exposed via the edge service (port 4566) only! If you are using a version of LocalStack lower than v0.11.5, you should set UseLegacyPorts to true. Edge port can be set to any available port (see LocalStack configuration section). If you have made such a change in LocalStack's configuration, be sure to set the same port value to EdgePort in the Config section. For LocalStackHost and UseSsl entries, ​​corresponding to the LocalStack configuration should be used.

The following sample setting files can be used to use both LocalStack.Client andAWSSDK.Extensions.NETCore.Setup in different environments.

appsettings.Development.json

"LocalStack": {
    "UseLocalStack": true,
    "Session": {
        ...
    },
    "Config": {
        ...
    }
}

appsettings.Production.json

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

See project LocalStack.Client.Sandbox.WithGenericHost for a use case.

About AddAwsService

AddAwsService is equivalent of AddAWSService used in AWSSDK.Extensions.NETCore.Setup. It decides which factory to use when resolving any AWS Service. To decide this, it checks the UseLocalStack entry. If the UseLocalStack entry is true, it uses the Session class of LocalStack.Client to create AWS Service. If the UseLocalStack entry is false, it uses the ClientFactory class of AWSSDK.Extensions.NETCore.Setup which is also used by original AddAWSService.

It is named as AddAwsService to avoid name conflict with AddAWSService.

useServiceUrl Parameter

LocalStack.NET uses ClientConfig to configure AWS clients to connect LocalStack. ClientConfig has two properties called ServiceUrl and RegionEndpoint, these are mutually exclusive properties. Whichever property is set last will cause the other to automatically be reset to null. LocalStack.NET has given priority to the RegionEndpoint property and the us-east-1 region is used as the default value (Different regions can be set by using appsettings.json, see RegionName entry. Because of it sets the RegionEndpoint property after the ServiceUrl property, ServiceUrl will be set to null.

To override this behavior, the useServiceUrl optional parameter can be set to true as below.

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

    services.AddLocalStack(Configuration)
    services.AddDefaultAWSOptions(Configuration.GetAWSOptions());
    services.AddAwsService<IAmazonS3>();
    services.AddAwsService<IAmazonMediaStoreData>(useServiceUrl: true)
    services.AddAwsService<IAmazonIoTJobsDataPlane>(useServiceUrl: true)
}

The RegionEndpoint is not applicable for services such as AWS MediaStore, Iot. The optional parameter useServiceUrl can be useful for use in such scenarios.

Standalone Initialization

If you do not want to use any DI library, you have to instantiate SessionStandalone as follows.

/*
* ==== Default Values ====
* AwsAccessKeyId: accessKey (It doesn't matter to LocalStack)
* AwsAccessKey: secretKey (It doesn't matter to LocalStack)
* AwsSessionToken: token (It doesn't matter to LocalStack)
* RegionName: us-east-1
* ==== Custom Values ====
* var sessionOptions = new SessionOptions("someAwsAccessKeyId", "someAwsAccessKey", "someAwsSessionToken", "eu-central-");
*/
var sessionOptions = new SessionOptions();

/*
* ==== Default Values ====
* LocalStackHost: localhost
* UseSsl: false
* UseLegacyPorts: false (Set true if your LocalStack version is 0.11.5 or above)
* EdgePort: 4566 (It doesn't matter if use legacy ports)
* ==== Custom Values ====
* var configOptions = new ConfigOptions("mylocalhost", false, false, 4566);
*/
var configOptions = new ConfigOptions();

ISession session = SessionStandalone.Init()
                                .WithSessionOptions(sessionOptions)
                                .WithConfigurationOptions(configOptions).Create();

var amazonS3Client = session.CreateClientByImplementation<AmazonS3Client>();

CreateClientByInterface<TSerice> method can also be used to create AWS service, as follows

var amazonS3Client = session.CreateClientByInterface<IAmazonS3>();

useServiceUrl Parameter

LocalStack.NET uses ClientConfig to configure AWS clients to connect LocalStack. ClientConfig has two properties called ServiceUrl and RegionEndpoint, these are mutually exclusive properties. Whichever property is set last will cause the other to automatically be reset to null. LocalStack.NET has given priority to the RegionEndpoint property and the us-east-1 region is used as the default value (Different regions can be set by using appsettings.json, see RegionName entry. Because of it sets the RegionEndpoint property after the ServiceUrl property, ServiceUrl will be set to null.

To override this behavior, the useServiceUrl optional parameter can be set to true as below.

var sessionOptions = new SessionOptions();
var configOptions = new ConfigOptions();

ISession session = SessionStandalone.Init()
                                .WithSessionOptions(sessionOptions)
                                .WithConfigurationOptions(configOptions).Create();

var amazonS3Client = session.CreateClientByImplementation<AmazonMediaStoreDataClient>(true);
var amazonS3Client = session.CreateClientByImplementation<AmazonS3Client>();

The RegionEndpoint is not applicable for services such as AWS MediaStore, Iot. The optional parameter useServiceUrl can be useful for use in such scenarios.

CreateClientByInterface<TSerice> method can also be used to create AWS service, as follows

var amazonS3Client = session.CreateClientByInterface<IAmazonMediaStoreData>(true);

Microsoft.Extensions.DependencyInjection Initialization

First, you need to install Microsoft.Extensions.DependencyInjection nuget package as follows

dotnet add package Microsoft.Extensions.DependencyInjection

Register necessary dependencies to ServiceCollection as follows

var collection = new ServiceCollection();

/*
* ==== Default Values ====
* AwsAccessKeyId: accessKey (It doesn't matter to LocalStack)
* AwsAccessKey: secretKey (It doesn't matter to LocalStack)
* AwsSessionToken: token (It doesn't matter to LocalStack)
* RegionName: us-east-1
* ==== Custom Values ====
* var sessionOptions = new SessionOptions("someAwsAccessKeyId", "someAwsAccessKey", "someAwsSessionToken", "eu-central-");
*/
var sessionOptions = new SessionOptions();

/*
* ==== Default Values ====
* LocalStackHost: localhost
* UseSsl: false
* UseLegacyPorts: false (Set true if your LocalStack version is 0.11.4 or below)
* EdgePort: 4566 (It doesn't matter if use legacy ports)
* ==== Custom Values ====
* var configOptions = new ConfigOptions("mylocalhost", false, false, 4566);
*/
var configOptions = new ConfigOptions();

collection
    .AddScoped<ISessionOptions, SessionOptions>(provider => sessionOptions)
    .AddScoped<IConfigOptions, ConfigOptions>(provider => configOptions))
    .AddScoped<IConfig, Config>()
    .AddSingleton<ISessionReflection, SessionReflection>()
    .AddSingleton<ISession, Session>()
    .AddTransient<IAmazonS3>(provider =>
    {
        var session = provider.GetRequiredService<ISession>();

        return (IAmazonS3) session.CreateClientByInterface<IAmazonS3>();
    });

ServiceProvider serviceProvider = collection.BuildServiceProvider();

var amazonS3Client = serviceProvider.GetRequiredService<IAmazonS3>();

If you want to use it with ConfigurationBuilder, you can also choose a usage as below.

var collection = new ServiceCollection();
var builder = new ConfigurationBuilder();

builder.SetBasePath(Directory.GetCurrentDirectory());
builder.AddJsonFile("appsettings.json", true);
builder.AddJsonFile("appsettings.Development.json", true);
builder.AddEnvironmentVariables();
builder.AddCommandLine(args);

IConfiguration configuration = builder.Build();

collection.Configure<LocalStackOptions>(options => configuration.GetSection("LocalStack").Bind(options, c => c.BindNonPublicProperties = true));
/*
* ==== Default Values ====
* AwsAccessKeyId: accessKey (It doesn't matter to LocalStack)
* AwsAccessKey: secretKey (It doesn't matter to LocalStack)
* AwsSessionToken: token (It doesn't matter to LocalStack)
* RegionName: us-east-1
    */
collection.Configure<SessionOptions>(options => configuration.GetSection("LocalStack")
                                                                .GetSection(nameof(LocalStackOptions.Session))
                                                                .Bind(options, c => c.BindNonPublicProperties = true));
/*
    * ==== Default Values ====
    * LocalStackHost: localhost
    * UseSsl: false
    * UseLegacyPorts: false (Set true if your LocalStack version is 0.11.5 or above)
    * EdgePort: 4566 (It doesn't matter if use legacy ports)
    */
collection.Configure<ConfigOptions>(options => configuration.GetSection("LocalStack")
                                                            .GetSection(nameof(LocalStackOptions.Config))
                                                            .Bind(options, c => c.BindNonPublicProperties = true));


collection.AddTransient<IConfig, Config>(provider =>
{
    ConfigOptions options = provider.GetRequiredService<IOptions<ConfigOptions>>().Value;

    return new Config(options);
})
.AddSingleton<ISessionReflection, SessionReflection>()
.AddSingleton<ISession, Session>(provider =>
{
    SessionOptions sessionOptions = provider.GetRequiredService<IOptions<SessionOptions>>().Value;
    var config = provider.GetRequiredService<IConfig>();
    var sessionReflection = provider.GetRequiredService<ISessionReflection>();

    return new Session(sessionOptions, config, sessionReflection);
})
.AddTransient<IAmazonS3>(provider =>
{
    var session = provider.GetRequiredService<ISession>();

    return (IAmazonS3) session.CreateClientByInterface<IAmazonS3>();
});

ServiceProvider serviceProvider = collection.BuildServiceProvider();

var amazonS3Client = serviceProvider.GetRequiredService<IAmazonS3>();

See useServiceUrl parameter usage.

Developing

We welcome feedback, bug reports, and pull requests!

Use commands below to get you started and test your code:

Windows

build.ps1

Linux

./build.sh

About Sandbox Applications

In addition to Unit Tests and Functional Test, LocalStack .Net Repository has various sandbox console applications for both testing and example purposes under tests/sandboxes

Sandbox applications include various examples of initialization methods of LocalStack.Client (see Usage section) and common AWS applications. They provide a convenient and safe environment for those who want to make developments in the library.

To run sandbox applications with LocalStack container, console application called LocalStack.Container has been developed. It uses Dotnet Testcontainer to bootstrap LocalStack. Experiments can be made by running LocalStack.Container application first and then any sandbox application.

Running Tests

Use commands below to run tests

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.

  • .NETFramework 4.6.1
    • AWSSDK.Core (>= 3.7.9)
  • .NETFramework 5.0
    • AWSSDK.Core (>= 3.7.9)
  • .NETFramework 6.0
    • AWSSDK.Core (>= 3.7.9)
  • .NETStandard 2.0
    • AWSSDK.Core (>= 3.7.9)
  • .NETFramework 4.6.1: 4.6.1.0
  • .NETFramework 5.0: 5.0.0.0
  • .NETFramework 6.0: 6.0.0.0
  • .NETStandard 2.0: 2.0.0.0

Owners

Deniz İrgin

Authors

LocalStack.NET, Deniz İrgin

Project URL

https://github.com/localstack-dotnet/localstack-dotnet-client

License

Unknown

Tags

aws-sdk, localstack, client-library, dotnet, dotnet-core

Info

6 total downloads
0 downloads for version 1.3.1
Download (118.98 KB)
Found on the current feed only

Package history

Version Size Last updated Downloads Mirrored?
1.3.1 118.98 KB Wed, 20 Apr 2022 23:03:58 GMT 0
1.3.0 119.08 KB Sun, 28 Nov 2021 22:34:02 GMT 1
1.2.3.2 78.32 KB Fri, 19 Nov 2021 11:17:23 GMT 0
1.2.3.1 73.16 KB Thu, 18 Nov 2021 15:00:21 GMT 0
1.2.3 74.29 KB Thu, 18 Nov 2021 14:21:18 GMT 0
1.2.2 60.66 KB Sun, 22 Aug 2021 16:13:21 GMT 0
1.2.0.1 59.93 KB Mon, 24 May 2021 12:19:01 GMT 0
1.2.0 59.92 KB Mon, 24 May 2021 12:04:46 GMT 0
1.1.0.2 59.91 KB Mon, 24 May 2021 11:37:11 GMT 0
1.1.0.1 59.21 KB Sun, 07 Mar 2021 19:24:39 GMT 0
1.1.0 59.2 KB Mon, 08 Feb 2021 14:33:08 GMT 1
1.0.0.3 59.21 KB Mon, 08 Feb 2021 13:39:14 GMT 1
1.0.0.2 59.37 KB Mon, 08 Feb 2021 11:45:18 GMT 2
1.0.0.1 42.31 KB Thu, 25 Jun 2020 12:03:44 GMT 0
1.0.0 42.02 KB Fri, 17 Apr 2020 09:08:58 GMT 0
0.8.0.164 17.9 KB Mon, 20 May 2019 18:24:04 GMT 0
0.8.0.163 17.9 KB Mon, 20 May 2019 17:37:24 GMT 0
0.8.0.162 17.89 KB Mon, 20 May 2019 17:28:34 GMT 1