Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Integrate LocalStack.NET Guidance into .NET SDK Documentation #790

Merged
merged 3 commits into from
Sep 11, 2023
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 64 additions & 3 deletions content/en/user-guide/integrations/sdks/dotnet/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ var s3client = new AmazonS3Client(config);
```

{{< alert title="Note">}}
In case of issues resolving this DNS record, we can fallback to http://localhost:4566 in combination with the provider setting `ForcePathStyle = true`. The S3 service endpoint is slightly different from the other service endpoints, because AWS is deprecating path-style based access for hosting buckets.
In case of issues resolving this DNS record, we can fallback to <http://localhost:4566> in combination with the provider setting `ForcePathStyle = true`. The S3 service endpoint is slightly different from the other service endpoints, because AWS is deprecating path-style based access for hosting buckets.
{{< /alert >}}

```csharp
Expand All @@ -64,7 +64,68 @@ var config = new AmazonS3Config(
var s3client = new AmazonS3Client(config);
```

## Alternative: Using LocalStack.NET

If you're working with .NET and LocalStack, you have a few options. In addition to the AWS SDK for .NET, there's an alternative client library, `LocalStack.NET`, which facilitates integration with LocalStack.

### Overview

`LocalStack.NET` is a .NET client library developed to simplify the connection between .NET applications and LocalStack. It wraps around the AWS SDK for .NET and offers an alternative setup for creating LocalStack clients.

**LocalStack.NET Documentation:** Comprehensive guide and examples [here](https://github.com/localstack-dotnet/localstack-dotnet-client).

### How it Works

- Instead of manually setting the endpoint configurations when initializing a client, `LocalStack.NET` offers methods that handle these details.
- The library aims to reduce the boilerplate required to set up LocalStack clients in .NET.
Blind-Striker marked this conversation as resolved.
Show resolved Hide resolved

### Example Usage

#### Dependency Injection Approach

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

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

...

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

#### Standalone Approach

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

ISession session = SessionStandalone.Init()
.WithSessionOptions(sessionOptions)
.WithConfigurationOptions(configOptions).Create();
Blind-Striker marked this conversation as resolved.
Show resolved Hide resolved

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

### Benefits

- **Consistent Client Configuration:** `LocalStack.NET` provides a standardized approach to initialize clients, eliminating the need for manual endpoint configurations.
- **Tailored for .NET Developers:** The library offers functionalities specifically developed to streamline integration of LocalStack with .NET applications.
- **Adaptable Environment Transition:** Switching between LocalStack and actual AWS services can be achieved with minimal configuration changes when leveraging `LocalStack.NET`.
- **Versatile .NET Compatibility:** Supports a broad spectrum of .NET versions, from .NET Framework 4.6.1 and .NET Standard 2.0, up to recent .NET iterations such as .NET 7.0.

### Considerations:

- Both the standard AWS SDK method and `LocalStack.NET` provide ways to integrate with LocalStack using .NET. The choice depends on developer preferences and specific project needs.
- `LocalStack.NET` works alongside the AWS SDK, using it as a base and providing a more focused API for LocalStack interactions.

## Resources

* [AWS SDK for .NET](https://aws.amazon.com/sdk-for-net/)
* [Official repository of the AWS SDK for .NET](https://github.com/aws/aws-sdk-net)
- [AWS SDK for .NET](https://aws.amazon.com/sdk-for-net/)
- [Official repository of the AWS SDK for .NET](https://github.com/aws/aws-sdk-net)
- [LocalStack.NET Documentation](https://github.com/localstack-dotnet/localstack-dotnet-client)