Aspire with LocalStack Demo

This repository is a small demo that shows how to use Aspire (Aspire AppHost) together with LocalStack to run an AWS-backed distributed application locally. It demonstrates an ASP.NET API service that enqueues and dequeues messages to an SQS FIFO queue, and a Blazor-like Web frontend that interacts with the API.

Why this demo

• Aspire AppHost: provides an opinionated application host for running multiple projects together (AppHost project in this solution orchestrates the ApiService and Web frontend, wires references, and can start LocalStack).
• LocalStack integration: runs a local, fully functional mock of AWS services (SQS in this demo) so you can develop and test integrations without real AWS credentials or costs.

What the projects show

• AspireWithLocalStackDemo.AppHost

  • The AppHost uses the Aspire SDK to define an application topology and starts a LocalStack container when enabled.
  • It creates an AWS CDK stack and provisions an SQS FIFO queue (CDK constructs are used only for local wiring within the demo).
  • It wires the ApiService and Web projects and ensures the web frontend waits for the API service to be available.
  • Notable packages (from the AppHost project file):
    • Aspire.AppHost.Sdk / Aspire.Hosting.AppHost (Aspire AppHost runtime)
    • LocalStack.Aspire.Hosting (LocalStack integration for Aspire)

• AspireWithLocalStackDemo.ApiService

  • Minimal ASP.NET Web API (using FastEndpoints) that exposes three endpoints:
    • POST /enqueue — sends a message to the SQS FIFO queue (uses AWSSDK.SQS)
    • POST /dequeue — receives (long-polls) a single message from the queue and returns its details
    • DELETE /receipt/{receiptHandle} — (referenced by the frontend client) deletes a message by receipt handle (implemented in the ApiService via configured SQS client)
  • Uses LocalStack.Client.Extensions and AWSSDK.SQS to make it easy to configure the SQS client against LocalStack during local runs.
  • Key NuGet packages (from AspireWithLocalStackDemo.ApiService.csproj):
    • AWSSDK.SQS (v4.x)
    • FastEndpoints (for minimal, strongly-typed endpoints)
    • LocalStack.Client.Extensions (for wiring AWS clients to LocalStack endpoints)

• AspireWithLocalStackDemo.Web

  • Razor components frontend that communicates with the API service via a typed QueueClient (an HttpClient wrapper).
  • QueueClient exposes methods to enqueue, dequeue, and delete messages by calling the API service endpoints.
  • In the demo, the frontend is configured to call the API via an http client whose base address is an Aspire-exposed HTTP name (apiservice). When run under the Aspire AppHost, the AppHost provides network wiring so projects can call one another by logical name.

Code highlights

• Enqueue endpoint (ApiService/Endpoints/Enqueue.cs):

  • Accepts MessageGroupId and MessageBody and calls IAmazonSQS.SendMessageAsync to enqueue into the FIFO queue.
  • Returns the SQS MessageId.

• Dequeue endpoint (ApiService/Endpoints/Dequeue.cs):

  • Long-polls the queue with ReceiveMessageAsync and requests message system attributes (including MessageGroupId).
  • Returns message id, group id, receipt handle and body (or no content if none available).

• QueueClient (Web/QueueClient.cs):

  • Provides async methods to call /enqueue, /dequeue, and DELETE /receipt/{receiptHandle}.
  • Handles NoContent responses when dequeue finds no messages.

Getting started (quick)

1. Prerequisites

• .NET SDK (matching the projects; recommended: latest .NET 8/9 based on project SDK, or the SDK listed in your dev environment).
• Docker (LocalStack runs in a container).
• Optional: an IDE (Rider, Visual Studio, VS Code).

2. Running the demo locally using the AppHost

The AspireWithLocalStackDemo.AppHost project is the recommended way to run everything together. It will:

• start LocalStack in a container
• create a local CDK stack with an SQS FIFO queue
• run the ApiService and Web frontend and wire them together so the frontend calls the API by logical name

From the solution root, run the AppHost project. Example (command-line):

# From the repository root
cd AspireWithLocalStackDemo.AppHost
dotnet run --project AspireWithLocalStackDemo.AppHost.csproj

When the AppHost starts it will show logs for LocalStack and each project. The web UI should be available on the address the AppHost reports (or check the AppHost output to see which ports are mapped).

3. Running the ApiService alone (useful for debugging)

You can run the ApiService project directly but make sure you have LocalStack available and that configuration points the AWSSDK client at LocalStack.

4. Where to look in code

• App orchestrator: AspireWithLocalStackDemo.AppHost/AppHost.cs
• API endpoints: AspireWithLocalStackDemo.ApiService/Endpoints/*.cs
• Web client wrapper: AspireWithLocalStackDemo.Web/QueueClient.cs
• App defaults & wiring: AspireWithLocalStackDemo.ServiceDefaults (contains helpers used by multiple projects).