Skip to content

Commit 20b91f6

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

File tree

3 files changed

+207
-2
lines changed

3 files changed

+207
-2
lines changed

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

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
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+
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.
14+
15+
## Getting started
16+
17+
This guide demonstrates how to integrate LocalStack into Aspire projects for local AWS service emulation.
18+
19+
### Prerequisites
20+
21+
- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) or later
22+
- [Docker Desktop](https://docs.docker.com/get-docker/) or compatible container runtime
23+
- [Node.js](https://nodejs.org/) (for AWS CDK infrastructure provisioning)
24+
- Basic familiarity with [Aspire concepts](https://aspire.dev/get-started/welcome/)
25+
26+
### Installation
27+
28+
Add the LocalStack Aspire integration to your App Host project:
29+
30+
```bash
31+
dotnet add package LocalStack.Aspire.Hosting
32+
```
33+
34+
For projects that need to interact with AWS services, add the LocalStack.NET client:
35+
36+
```bash
37+
dotnet add package LocalStack.Client
38+
```
39+
40+
## Usage
41+
42+
Configure LocalStack integration in your Aspire AppHost project using auto-configuration:
43+
44+
```csharp
45+
var builder = DistributedApplication.CreateBuilder(args);
46+
47+
// 1. Set up AWS SDK configuration (optional)
48+
var awsConfig = builder.AddAWSSDKConfig()
49+
.WithProfile("default")
50+
.WithRegion(RegionEndpoint.USWest2);
51+
52+
// 2. Add LocalStack container
53+
var localstack = builder
54+
.AddLocalStack(awsConfig: awsConfig, configureContainer: container =>
55+
{
56+
container.Lifetime = ContainerLifetime.Session;
57+
container.DebugLevel = 1;
58+
container.LogLevel = LocalStackLogLevel.Debug;
59+
});
60+
61+
// 3. Add your AWS resources as usual
62+
var awsResources = builder.AddAWSCloudFormationTemplate("resources", "template.yaml")
63+
.WithReference(awsConfig);
64+
65+
var project = builder.AddProject<Projects.MyService>("api")
66+
.WithReference(awsResources);
67+
68+
// 4. Auto-configure LocalStack for all AWS resources
69+
builder.UseLocalStack(localstack);
70+
71+
builder.Build().Run();
72+
```
73+
74+
The `UseLocalStack()` method automatically:
75+
76+
- Detects all AWS resources (CloudFormation, CDK stacks)
77+
- Configures LocalStack endpoints for all AWS services and project resources
78+
- Sets up proper dependency ordering and CDK bootstrap if needed
79+
- Transfers LocalStack configuration to service projects via environment variables
80+
81+
## AWS SDK Configuration
82+
83+
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.
84+
85+
### Using LocalStack.NET
86+
87+
The [`LocalStack.Client`](https://github.com/localstack-dotnet/localstack-dotnet-client) library simplifies AWS SDK configuration:
88+
89+
```csharp
90+
services.AddLocalStack(configuration);
91+
services.AddDefaultAWSOptions(configuration.GetAWSOptions());
92+
services.AddAwsService<IAmazonS3>();
93+
services.AddAwsService<IAmazonDynamoDB>();
94+
```
95+
96+
This automatically configures AWS service clients to use the LocalStack endpoint when running locally.
97+
98+
## Infrastructure Provisioning
99+
100+
LocalStack integrates well with Infrastructure as Code tools within the Aspire orchestration model.
101+
102+
### AWS CDK Integration
103+
104+
You can provision AWS resources using AWS CDK during application startup:
105+
106+
```csharp
107+
var awsConfig = builder.AddAWSSDKConfig()
108+
.WithProfile("default")
109+
.WithRegion(RegionEndpoint.USWest2);
110+
111+
var localstack = builder.AddLocalStack("localstack");
112+
113+
var customStack = builder
114+
.AddAWSCDKStack("custom", scope => new CustomStack(scope, "Aspire-custom"))
115+
.WithReference(awsConfig);
116+
```
117+
118+
You can use AWS CDK Stack classes to define and deploy resources:
119+
120+
```csharp
121+
internal sealed class CustomStack : Stack
122+
{
123+
public IBucket Bucket { get; }
124+
125+
public ITopic ChatTopic { get; }
126+
127+
public IQueue ChatMessagesQueue { get; }
128+
129+
public ITable ChatMessagesTable { get; }
130+
131+
public CustomStack(Construct scope, string id)
132+
: base(scope, id)
133+
{
134+
// Keep bucket for potential future demonstration
135+
Bucket = new Bucket(this, "Bucket");
136+
137+
ChatTopic = new Topic(this, "ChatTopic");
138+
139+
ChatMessagesQueue = new Queue(this, "ChatMessagesQueue", new QueueProps
140+
{
141+
VisibilityTimeout = Duration.Seconds(30),
142+
});
143+
144+
ChatTopic.AddSubscription(new SqsSubscription(ChatMessagesQueue));
145+
146+
var chatMessagesTable = new Table(this, "ChatMessagesTable", new TableProps
147+
{
148+
TableName = "ChatMessages",
149+
PartitionKey = new Attribute { Name = "MessageId", Type = AttributeType.STRING },
150+
SortKey = new Attribute { Name = "Timestamp", Type = AttributeType.NUMBER },
151+
BillingMode = BillingMode.PAY_PER_REQUEST,
152+
});
153+
154+
chatMessagesTable.AddGlobalSecondaryIndex(new GlobalSecondaryIndexProps
155+
{
156+
IndexName = "TimestampIndex",
157+
PartitionKey = new Attribute { Name = "Timestamp", Type = AttributeType.NUMBER },
158+
ProjectionType = ProjectionType.ALL,
159+
});
160+
161+
ChatMessagesTable = chatMessagesTable;
162+
}
163+
}
164+
```
165+
166+
:::note
167+
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).
168+
:::
169+
170+
## Configuration Reference
171+
172+
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).
173+
174+
## Sample Projects
175+
176+
### Playground Examples
177+
178+
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.
179+
180+
### LocalStack Serverless .NET Demo
181+
182+
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)
183+
184+
### OpenTelemetry with Aspire and LocalStack
185+
186+
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)
187+
188+
## Resources
189+
190+
- [Aspire Documentation](https://aspire.dev/)
191+
- [LocalStack.Aspire.Hosting on GitHub](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack)
192+
- [LocalStack.Client on GitHub](https://github.com/localstack-dotnet/localstack-dotnet-client)
193+
- [AWS Aspire Integration](https://github.com/aws/integrations-on-dotnet-aspire-for-aws)
194+
- [AWS SDK for .NET Documentation](https://docs.aws.amazon.com/sdk-for-net/)
195+
- [LocalStack Serverless .NET Demo](https://github.com/localstack-dotnet/localstack-serverless-dotnet-demo)
196+
- [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: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,8 +128,16 @@ var amazonS3Client = session.CreateClientByImplementation<AmazonS3Client>();
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)