# AWS integrations overview

<ThemeImage
  light={awsLight}
  dark={awsDark}
  alt="AWS logo"
  width={96}
  height={54}
  classOverride="float-inline-left borderless"
  zoomable={false}
/>

AWS maintains the [Aspire.Hosting.AWS](https://www.nuget.org/packages/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](/get-started/app-host/) 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](/get-started/prerequisites/) running, connect an existing `Api` project to DynamoDB Local:

```typescript title="apphost.mts" twoslash
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();
```

```csharp title="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](https://github.com/aws/integrations-on-dotnet-aspire-for-aws/blob/main/src/Aspire.Hosting.AWS/README.md#integrating-amazon-dynamodb-local) for SDK configuration and persistent data.
- Follow the [CloudFormation walkthrough](https://github.com/aws/integrations-on-dotnet-aspire-for-aws/blob/main/src/Aspire.Hosting.AWS/README.md#provisioning-application-resources-with-aws-cloudformation) 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](#credentials-and-configuration) |
| Create infrastructure or connect to an existing stack | [CloudFormation and AWS CDK](#cloudformation-and-aws-cdk) |
| Develop with DynamoDB without a cloud database | [DynamoDB Local](#dynamodb-local) |
| Run and debug Lambda functions alongside your services | [Lambda and API Gateway](#lambda-and-api-gateway) |
| Publish and deploy your application to AWS | [Deployment preview](#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](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) 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.

<LearnMore>
  For the AppHost setup, see [Configure the AWS SDK](https://github.com/aws/integrations-on-dotnet-aspire-for-aws/blob/main/src/Aspire.Hosting.AWS/README.md#configuring-the-aws-sdk-for-net).
</LearnMore>

## 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`.

:::caution[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.
:::

<LearnMore>
  Follow AWS's guides for [CloudFormation templates](https://github.com/aws/integrations-on-dotnet-aspire-for-aws/blob/main/src/Aspire.Hosting.AWS/README.md#provisioning-application-resources-with-aws-cloudformation), [existing stacks](https://github.com/aws/integrations-on-dotnet-aspire-for-aws/blob/main/src/Aspire.Hosting.AWS/README.md#importing-existing-aws-resources), or [CDK resources](https://github.com/aws/integrations-on-dotnet-aspire-for-aws/blob/main/src/Aspire.Hosting.AWS/README.md#provisioning-application-resources-with-aws-cdk).
</LearnMore>

## 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.

<LearnMore>
  See [DynamoDB Local setup and options](https://github.com/aws/integrations-on-dotnet-aspire-for-aws/blob/main/src/Aspire.Hosting.AWS/README.md#integrating-amazon-dynamodb-local).
</LearnMore>

### 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.

<LearnMore>
  See [Lambda local development](https://github.com/aws/integrations-on-dotnet-aspire-for-aws/blob/main/src/Aspire.Hosting.AWS/README.md#integrating-aws-lambda-local-development) for function registration and routing examples.
</LearnMore>

## 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.

<LearnMore>
  Check the provider's [supported features and method-name differences](https://github.com/aws/integrations-on-dotnet-aspire-for-aws/blob/main/src/Aspire.Hosting.AWS/README.md#supported-features-and-method-name-differences) before adapting an example between languages.
</LearnMore>

## 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.

<LearnMore>
  Review the provider's [deployment guide](https://github.com/aws/integrations-on-dotnet-aspire-for-aws/blob/main/src/Aspire.Hosting.AWS/README.md#deployment-to-aws-preview) for opt-in requirements, supported resource mappings, and customization.
</LearnMore>

## See also

- [AWS integration documentation](https://docs.aws.amazon.com/sdk-for-net/v4/developer-guide/aspire-integrations.html)
- [AWS integration source and examples](https://github.com/aws/integrations-on-dotnet-aspire-for-aws)
- [Aspire deployment environments](/deployment/environments/)