Skip to content

Setup

Jump to bottom
Deniz İrgin edited this page Sep 11, 2023 · 2 revisions

Welcome to the setup guide for LocalStack.NET. This page is dedicated to helping you understand setting up the library correctly and ensuring that you can make the most out of its features. Before diving into the setup, ensure you've installed the necessary packages. If you haven't, please refer to our Installation section.

Why Two Different Libraries?

You might have noticed that there are two primary libraries associated with LocalStack.NET: LocalStack.Client and LocalStack.Client.Extensions. But why two? The distinction is made to cater to different project requirements and .NET environments.

LocalStack.Client: This is the base library, suitable for specific scenarios like using the legacy .NET Framework, employing a different DI framework like Autofac, or using the library standalone without DI.

LocalStack.Client.Extensions: This library is an extension of the base client, designed to integrate seamlessly with .NET Core's configuration and dependency injection frameworks. It's especially recommended for projects using modern .NET environments, given its integration with AWSSDK.Extensions.NETCore.Setup, allowing for side-by-side usage of both LocalStack and AWS.

Depending on your project's requirements and the .NET environment you're working with, you might opt for one over the other.

Configuration

LocalStack.NET can be configured using entries in your application's appsettings.json files. Here's a basic example:

"LocalStack": {
    "UseLocalStack": true,
    "Session": {
        "AwsAccessKeyId": "your-access-key-id",
        "AwsAccessKey": "your-access-key",
        "AwsSessionToken": "your-session-token",
        "RegionName": "eu-central-1"
    },
    "Config": {
        "LocalStackHost": "localhost.localstack.cloud", // or "localhost",
        "UseSsl": false,
        "UseLegacyPorts": false,
        "EdgePort": 4566
    }
}

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

Session Configuration

  • AwsAccessKeyId/AwsAccessKey/AwsSessionToken: These are your AWS credentials. For LocalStack, the exact values don't matter, but they need to be provided.
  • RegionName: This is important as LocalStack creates resources based on the specified region.

LocalStack Configuration

  • LocalStackHost: The host where LocalStack is running. Typically, this is localhost.localstack.cloud or localhost.
  • UseSsl: Determines if SSL should be used. Default is false.
  • UseLegacyPorts: If you're using a version of LocalStack lower than v0.11.5, set this to true.
  • EdgePort: The port on which LocalStack's edge service is running. The default is 4566.

Advanced Scenarios

You might need different configurations for different environments. Here's an example of how you can set up configuration files for both development and production environments:

Development Configuration (appsettings.Development.json)

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

Production Configuration (appsettings.Production.json)

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

⚠️ Legacy Configuration Warning

Attention: When the library was first written, LocalStack was in the versions that are now referred to as "legacy" (v0.10...). As a result, many of the values in appsettings.json have become less relevant. These will be changed and simplified in the upcoming version. See issues/32

  • UseSsl has been deprecated. (Starting from version 0.11.3, each service endpoint began supporting multiplexing HTTP/HTTPS traffic over the same port).

  • UseLegacyPorts: While LocalStack.NET continues to support the legacy versions of LocalStack, they are now seldom used. The legacy versions start with 0.x.x and LocalStack now at version 2.2; support for these legacy versions will be removed in the next release of LocalStack.NET.

Setup Methods

Depending on your environment and use case, there are different initialization methods available:

LocalStack.Client.Extensions (Recommended): Ideal for projects using .NET Core, .NET 5, and above, especially given the popularity of AWSSDK.Extensions.NETCore.Setup. Standalone Initialization: For those who prefer not to use any DI library, this method allows for manual instantiation and setup.

LocalStack.Client.Extensions (Recommended)

LocalStack.Client.Extensions is an extension for the LocalStack.NET Client designed to integrate seamlessly with .NET Core's configuration and dependency injection frameworks. This extension also provides a wrapper around AWSSDK.Extensions.NETCore.Setup, allowing you to use both LocalStack and AWS side-by-side.

The usage of LocalStack.Client.Extensions is very similar to AWSSDK.Extensions.NETCore.Setup but with some differences. Here's a basic example:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddLocalStack(Configuration);
    services.AddDefaultAWSOptions(Configuration.GetAWSOptions());
    services.AddAwsService<IAmazonS3>();
    services.AddAwsService<IAmazonDynamoDB>();
}

The key difference is the use of AddAwsService instead of AddAWSService from AWSSDK.Extensions.NETCore.Setup. The AddLocalStack method integrates LocalStack.NET into your application, and the AddAwsService method specifies which AWS services you want to use with LocalStack.

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

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 Setup

If you do not want to use any DI library, you must 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>();
var amazonMediaStore = session.CreateClientByImplementation<AmazonMediaStoreDataClient>(true);

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

var amazonS3Client = session.CreateClientByInterface<IAmazonS3>();
Clone this wiki locally