Skip to content

Commit 9ac1365

Browse files
Blind-StrikerBlind-Striker
committed
docs: add Aspire framework integration guide
1 parent 81a5ce5 commit 9ac1365

File tree

3 files changed

+190
-7
lines changed

3 files changed

+190
-7
lines changed

‎src/content/docs/aws/integrations/app-frameworks/aspire.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
---
2+
title: Aspire
3+
description: Use the Aspire framework with LocalStack
4+
template: doc
5+
sidebar:
6+
order: 5
7+
---
8+
9+
## Introduction
10+
11+
[Aspire](https://aspire.dev/) is an opinionated, cloud-ready stack for building observable, production-ready distributed applications. It provides a consistent approach to service discovery, configuration, telemetry, and health checks across cloud-native applications.
12+
13+
With Aspire, developers can orchestrate cloud-native applications locally using the same AWS resources they deploy in production. By combining Aspire with LocalStack, teams can emulate their full cloud environment—including Lambda, SQS, S3, and DynamoDB—with minimal configuration and no AWS costs.
14+
15+
LocalStack integrates with Aspire through the [`LocalStack.Aspire.Hosting`](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack) package, enabling seamless local development and testing of AWS-powered applications within the Aspire orchestration framework. This package extends the official [AWS integrations for .NET Aspire](https://github.com/aws/integrations-on-dotnet-aspire-for-aws) to provide LocalStack-specific functionality.
16+
17+
## Getting started
18+
19+
This guide demonstrates how to integrate LocalStack into Aspire projects for local AWS service emulation.
20+
21+
### Prerequisites
22+
23+
- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) or later
24+
- [Docker Desktop](https://docs.docker.com/get-docker/) or compatible container runtime
25+
- [Node.js](https://nodejs.org/) (for AWS CDK infrastructure provisioning)
26+
- Basic familiarity with [Aspire concepts](https://aspire.dev/get-started/welcome/)
27+
28+
### Installation
29+
30+
Add the LocalStack Aspire integration to your App Host project:
31+
32+
```bash
33+
dotnet add package LocalStack.Aspire.Hosting
34+
```
35+
36+
For projects that need to interact with AWS services, add the LocalStack.NET client:
37+
38+
```bash
39+
dotnet add package LocalStack.Client
40+
```
41+
42+
## Usage
43+
44+
Configure LocalStack integration in your Aspire AppHost project using auto-configuration:
45+
46+
```csharp
47+
var builder = DistributedApplication.CreateBuilder(args);
48+
49+
// 1. Set up AWS SDK configuration (optional)
50+
var awsConfig = builder.AddAWSSDKConfig()
51+
.WithProfile("default")
52+
.WithRegion(RegionEndpoint.USWest2);
53+
54+
// 2. Add LocalStack container
55+
var localstack = builder
56+
.AddLocalStack(awsConfig: awsConfig, configureContainer: container =>
57+
{
58+
container.Lifetime = ContainerLifetime.Session;
59+
container.DebugLevel = 1;
60+
container.LogLevel = LocalStackLogLevel.Debug;
61+
});
62+
63+
// 3. Add your AWS resources as usual
64+
var awsResources = builder.AddAWSCloudFormationTemplate("resources", "template.yaml")
65+
.WithReference(awsConfig);
66+
67+
var project = builder.AddProject<Projects.MyService>("api")
68+
.WithReference(awsResources);
69+
70+
// 4. Auto-configure LocalStack for all AWS resources
71+
builder.UseLocalStack(localstack);
72+
73+
builder.Build().Run();
74+
```
75+
76+
The `UseLocalStack()` method automatically:
77+
78+
- Detects all AWS resources (CloudFormation, CDK stacks)
79+
- Configures LocalStack endpoints for all AWS services and project resources
80+
- Sets up proper dependency ordering and CDK bootstrap if needed
81+
- Transfers LocalStack configuration to service projects via environment variables
82+
83+
## AWS SDK Configuration
84+
85+
When using the AWS SDK for .NET with LocalStack in an Aspire context, the SDK clients need to be configured to point to the LocalStack endpoint.
86+
87+
### Using LocalStack.NET
88+
89+
The [`LocalStack.Client`](https://github.com/localstack-dotnet/localstack-dotnet-client) library simplifies AWS SDK configuration:
90+
91+
```csharp
92+
services.AddLocalStack(configuration);
93+
services.AddDefaultAWSOptions(configuration.GetAWSOptions());
94+
services.AddAwsService<IAmazonS3>();
95+
services.AddAwsService<IAmazonDynamoDB>();
96+
```
97+
98+
This automatically configures AWS service clients to use the LocalStack endpoint when running locally. See the [.NET](/aws/integrations/aws-sdks/net/) guide for more information.
99+
100+
## Infrastructure Provisioning
101+
102+
LocalStack integrates well with Infrastructure as Code tools within the Aspire orchestration model.
103+
104+
### AWS CDK Integration
105+
106+
You can provision AWS resources using AWS CDK during application startup:
107+
108+
```csharp
109+
var awsConfig = builder.AddAWSSDKConfig()
110+
.WithProfile("default")
111+
.WithRegion(RegionEndpoint.USWest2);
112+
113+
var localstack = builder.AddLocalStack("localstack");
114+
115+
var customStack = builder
116+
.AddAWSCDKStack("custom", scope => new CustomStack(scope, "Aspire-custom"))
117+
.WithReference(awsConfig);
118+
```
119+
120+
You can use AWS CDK Stack classes to define and deploy resources:
121+
122+
```csharp
123+
// An excerpt of a CDK Stack class
124+
internal sealed class CustomStack : Stack
125+
{
126+
public CustomStack(Construct scope, string id) : base(scope, id)
127+
{
128+
// Example resources
129+
var bucket = new Bucket(this, "Bucket");
130+
var topic = new Topic(this, "ChatTopic");
131+
132+
var queue = new Queue(this, "ChatMessagesQueue", new QueueProps
133+
{
134+
VisibilityTimeout = Duration.Seconds(30),
135+
});
136+
137+
topic.AddSubscription(new SqsSubscription(queue));
138+
139+
// ... (rest of the stack)
140+
}
141+
}
142+
```
143+
144+
:::note
145+
For detailed AWS CDK integration patterns with LocalStack and Aspire, refer to the [provisioning playground example](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack/tree/master/playground/provisioning).
146+
:::
147+
148+
## Configuration Reference
149+
150+
For comprehensive configuration options, including environment variables, container settings, and advanced scenarios, refer to the [Configuration Guide](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack/blob/master/docs/CONFIGURATION.md).
151+
152+
## Sample Projects
153+
154+
### Playground Examples
155+
156+
The [playground examples](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack/tree/master/playground) include Lambda development patterns and infrastructure provisioning with AWS CDK.
157+
158+
### LocalStack Serverless .NET Demo
159+
160+
A reference implementation demonstrating serverless applications with Lambda functions, S3, DynamoDB, SQS, and CDK provisioning: [localstack-serverless-dotnet-demo](https://github.com/localstack-dotnet/localstack-serverless-dotnet-demo)
161+
162+
### OpenTelemetry with Aspire and LocalStack
163+
164+
An event registration system showcasing distributed tracing and observability patterns with Lambda and SQS: [dotnet-otel-aspire-localstack-demo](https://github.com/Blind-Striker/dotnet-otel-aspire-localstack-demo)
165+
166+
## Resources
167+
168+
- [Aspire Documentation](https://aspire.dev/)
169+
- [LocalStack.Aspire.Hosting on GitHub](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack)
170+
- [LocalStack.Client on GitHub](https://github.com/localstack-dotnet/localstack-dotnet-client)
171+
- [AWS Aspire Integration](https://github.com/aws/integrations-on-dotnet-aspire-for-aws)
172+
- [AWS SDK for .NET Documentation](https://docs.aws.amazon.com/sdk-for-net/)
173+
- [LocalStack Serverless .NET Demo](https://github.com/localstack-dotnet/localstack-serverless-dotnet-demo)
174+
- [OpenTelemetry with Aspire and LocalStack Demo](https://github.com/Blind-Striker/dotnet-otel-aspire-localstack-demo)

‎src/content/docs/aws/integrations/app-frameworks/index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,5 +14,6 @@ This section covers how to use LocalStack with:
1414
- Architect (ARC)
1515
- Quarkus
1616
- Spring Cloud Function
17+
- Aspire
1718

18-
Each guide shows how to configure the framework to work seamlessly with LocalStack for local development and testing.
19+
Each guide shows how to configure the framework to work seamlessly with LocalStack for local development and testing.

‎src/content/docs/aws/integrations/aws-sdks/net.md‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -67,13 +67,13 @@ var s3client = new AmazonS3Client(config);
6767

6868
## Alternative: Using LocalStack.NET
6969

70-
If you're working with .NET and LocalStack, you have a few options.
71-
In addition to the AWS SDK for .NET, there's an alternative client library, `LocalStack.NET`, which facilitates integration with LocalStack.
70+
As an alternative to manual endpoint configuration, you can use LocalStack.NET, an easy-to-use .NET client for LocalStack.
7271

7372
### Overview
7473

75-
`LocalStack.NET` is a .NET client library developed to simplify the connection between .NET applications and LocalStack.
76-
It wraps around the AWS SDK for .NET and offers an alternative setup for creating LocalStack clients.
74+
`LocalStack.NET` provides a thin wrapper around the official [aws-sdk-net](https://github.com/aws/aws-sdk-net) (AWS SDK for .NET). It automatically configures the target endpoints to use LocalStack for your local cloud application development.
75+
76+
When LocalStack is disabled in configuration, LocalStack.NET automatically uses the official AWS SDK clients, allowing your application to target your real AWS account with no code changes.
7777

7878
**LocalStack.NET Documentation:** Comprehensive guide and examples [here](https://github.com/localstack-dotnet/localstack-dotnet-client).
7979
@@ -120,16 +120,24 @@ var amazonS3Client = session.CreateClientByImplementation<AmazonS3Client>();
120120
- **Consistent Client Configuration:** `LocalStack.NET` provides a standardized approach to initialize clients, eliminating the need for manual endpoint configurations.
121121
- **Tailored for .NET Developers:** The library offers functionalities specifically developed to streamline integration of LocalStack with .NET applications.
122122
- **Adaptable Environment Transition:** Switching between LocalStack and actual AWS services can be achieved with minimal configuration changes when leveraging `LocalStack.NET`.
123-
- **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.
123+
- **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 10.
124124

125125
### Considerations
126126

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

131+
## Aspire Integration
132+
133+
If you are building cloud-native applications with [Aspire](https://aspire.dev/), LocalStack provides first-class integration through the Aspire orchestration framework.
134+
The [`LocalStack.Aspire.Hosting`](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack) package enables seamless local development with automatic container lifecycle management, service discovery, and observability integration.
135+
136+
For detailed guidance on using LocalStack with Aspire, including configuration options and example projects, see the [Aspire integration guide](/aws/integrations/app-frameworks/aspire).
137+
131138
## Resources
132139

133140
- [AWS SDK for .NET](https://aws.amazon.com/sdk-for-net/)
134141
- [Official repository of the AWS SDK for .NET](https://github.com/aws/aws-sdk-net)
135-
- [LocalStack.NET Documentation](https://github.com/localstack-dotnet/localstack-dotnet-client)
142+
- [LocalStack.NET Documentation](https://github.com/localstack-dotnet/localstack-dotnet-client)
143+
- [LocalStack.Aspire.Hosting Documentation](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack)

0 commit comments

Comments
 (0)