AWS integrations overview

AWS maintains the Aspire.Hosting.AWS integration. Use it to connect your application to Amazon Web Services, provision infrastructure, and develop against local service emulators alongside your app.

Your AppHost describes the resources and their relationships. The AWS integration supplies the provider-specific configuration and tooling; your application uses the appropriate AWS SDK to work with those services.

Connect your app to DynamoDB Local

From your AppHost directory, run aspire add Aspire.Hosting.AWS. With a container runtime running, connect an existing Api project to DynamoDB Local:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const dynamodb = await builder.addAWSDynamoDBLocal('dynamodb');

const api = await builder.addProject('api', '../Api/Api.csproj');
await api.withDynamoDBLocalReference(dynamodb);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

var dynamodb = builder.AddAWSDynamoDBLocal("dynamodb");

builder.AddProject<Projects.Api>("api")
    .WithReference(dynamodb);

builder.Build().Run();

The reference supplies AWS_ENDPOINT_URL_DYNAMODB to your API, so a compatible AWS SDK client can discover the local endpoint without a hardcoded URL. For this resource, TypeScript uses withDynamoDBLocalReference where C# uses WithReference. This starts a local container, not a DynamoDB table in your AWS account.

• Follow DynamoDB Local setup and options for SDK configuration and persistent data.
• Follow the CloudFormation walkthrough to provision cloud resources and pass their outputs to your app.

Choose a starting point

Your goal	Start here
Share an AWS profile and region with your app	Credentials and configuration
Create infrastructure or connect to an existing stack	CloudFormation and AWS CDK
Develop with DynamoDB without a cloud database	DynamoDB Local
Run and debug Lambda functions alongside your services	Lambda and API Gateway
Publish and deploy your application to AWS	Deployment preview

Credentials and configuration

Configure an AWS credential profile and choose a region before accessing cloud resources. Use permissions appropriate to the services your app needs, and keep credentials out of your AppHost source. See AWS configuration and credential files for setup.

The integration can share an SDK configuration with consuming resources through the AWS_PROFILE and AWS_REGION environment variables. AWS SDK clients that use the standard credential and region resolution can pick up this configuration without hardcoded settings.

For the AppHost setup, see Configure the AWS SDK.

CloudFormation and AWS CDK

Use AWS CloudFormation when you already have a JSON or YAML infrastructure template. The integration can provision a stack during AppHost startup, pass template parameters, and expose stack outputs to your application. You can also reference an existing CloudFormation stack without defining a new template.

Use AWS Cloud Development Kit (CDK) when you want to describe infrastructure with constructs in code. The integration includes helpers for resources such as S3 buckets, DynamoDB tables, SQS queues, and SNS topics. CDK synthesizes CloudFormation templates and requires Node.js.

In both workflows, resource references make values such as names, URLs, and Amazon Resource Names (ARNs) available to consuming application resources. The default configuration section for these values is AWS:Resources.

Provisioning creates real AWS resources

CloudFormation and CDK workflows can create resources in your AWS account even when you start the AppHost locally. Review the target account, region, permissions, and potential charges before running them.

Follow AWS’s guides for CloudFormation templates, existing stacks, or CDK resources.

Develop locally

DynamoDB Local

Run DynamoDB Local as a container managed by your AppHost. Referencing it supplies the local service endpoint through AWS_ENDPOINT_URL_DYNAMODB, so compatible SDK clients can connect to the container instead of the cloud service.

Tables and data are stored in memory by default. Configure local storage when you need them to persist between runs.

See DynamoDB Local setup and options.

Lambda and API Gateway

Develop and debug .NET Lambda functions alongside the rest of your application. The integration manages the Lambda Test Tool for local invocation and supports both executable and class-library function projects.

Add the API Gateway emulator when you want to invoke those functions through local HTTP routes. This is a local development workflow, not a deployment of an API Gateway service in AWS.

See Lambda local development for function registration and routing examples.

AppHost language support

The integration supports TypeScript and C# AppHosts, but their available APIs are not identical. TypeScript exports include SDK configuration, DynamoDB Local, Lambda functions, and API Gateway emulation. Some AWS reference methods have different names in TypeScript.

The Lambda integration described here runs .NET functions regardless of the AppHost language.

Check the provider’s supported features and method-name differences before adapting an example between languages.

Deployment preview

AWS also provides a preview deployment integration. It converts supported Aspire resources into CDK constructs and CloudFormation templates. With an AWS deployment environment configured, aspire publish produces deployment artifacts and aspire deploy deploys them to your account.

This workflow requires the AWS CDK tooling and a bootstrapped target account and region. Do not assume every resource in your local app has an AWS deployment mapping.

Review the provider’s deployment guide for opt-in requirements, supported resource mappings, and customization.

See also

• AWS integration documentation
• AWS integration source and examples
• Aspire deployment environments