Getting Started

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.

Installation

Recommended: LocalStack.Client.Extensions

LocalStack.Client.Extensions is the recommended package for most modern .NET environments. It integrates with .NET configuration and dependency injection frameworks and provides a wrapper around AWSSDK.Extensions.NETCore.Setup. This allows you to use both LocalStack and AWS side-by-side seamlessly.

This approach is especially recommended for projects using .NET Core, .NET 6, or .NET 7 etc., given the popularity and best practices associated with AWSSDK.Extensions.NETCore.Setup.

To install, use nuget:

Install-Package LocalStack.Client.Extensions

Or use dotnet cli

dotnet add package LocalStack.Client.Extensions

Note: Installing LocalStack.Client.Extensions will also install the base LocalStack.Client library.

Base Library: LocalStack.Client

For specific scenarios, such as using the legacy .NET Framework, or employing a different DI framework like Autofac, or using the library standalone without DI, you might opt for the base LocalStack.Client library.

To install, use nuget:

Install-Package LocalStack.Client

Or use dotnet cli

dotnet add package LocalStack.Client

Usage

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.

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 the configuration documentation for more information

Integrating with Dependency Injection

Here's a basic example of how to integrate LocalStack.NET with the .NET dependency injection:

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.

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

For services where the RegionEndpoint is not applicable, such as AWS MediaStore or IoT, you can use the useServiceUrl parameter:

services.AddAwsService<IAmazonMediaStoreData>(useServiceUrl: true);
services.AddAwsService<IAmazonIoTJobsDataPlane>(useServiceUrl: true);

Refer to the setup documentation for more information