👁 Image
Aspire.Hosting.AWS 13.3.0

Aspire.Hosting.AWS library

Provides extension methods and resources definition for a .NET Aspire AppHost to configure the AWS SDK for .NET and AWS application resources.

Features

• Provisioning application resources with AWS CloudFormation
• Importing existing AWS resources
• Provisioning application resources with AWS CDK
• Integrating AWS Lambda Local Development
• Deployment to AWS (Preview)
• Integrating Amazon DynamoDB Local
• Local Development with AgentCore (Experimental)

Prerequisites

• Configure AWS credentials
• Node.js (AWS CDK only)

Install the package

In your AppHost project, install the Aspire.Hosting.AWS library with NuGet:

dotnet add package Aspire.Hosting.AWS

Configuring the AWS SDK for .NET

The AWS profile and region the SDK should use can be configured using the AddAWSSDKConfig method. The following example creates a config using the dev profile from the ~/.aws/credentials file and points the SDK to the us-west-2 region.

var awsConfig = builder.AddAWSSDKConfig()
 .WithProfile("dev")
 .WithRegion(RegionEndpoint.USWest2);

The configuration can be attached to projects using the WithReference method. This will set the AWS_PROFILE and AWS_REGION environment variables on the project to the profile and region configured by the AddAWSSDKConfig method. SDK service clients created in the project without explicitly setting the credentials and region will pick up these environment variables and use them to configure the service client.

builder.AddProject<Projects.Frontend>("Frontend")
 .WithReference(awsConfig)

If a project has a reference to an AWS resource like the AWS CloudFormation resources that have an AWS SDK configuration the project will infer the AWS SDK configuration from the AWS resource. For example if you call the WithReference passing in the CloudFormation resource then a second WithReference call passing in the AWS SDK configuration is not necessary.

Provisioning application resources with AWS CloudFormation

AWS application resources like Amazon DynamoDB tables or Amazon Simple Queue Service (SQS) queues can be provisioned during AppHost startup using a CloudFormation template.

In the AppHost project create either a JSON or YAML CloudFormation template. Here is an example template called app-resources.template that creates a queue and topic.

{
 "AWSTemplateFormatVersion" : "2010-09-09",
 "Parameters" : {
 "DefaultVisibilityTimeout" : {
 "Type" : "Number",
 "Description" : "The default visibility timeout for messages in SQS queue."
 }
 },
 "Resources" : {
 "ChatMessagesQueue" : {
 "Type" : "AWS::SQS::Queue",
 "Properties" : {
 "VisibilityTimeout" : { "Ref" : "DefaultVisibilityTimeout" }
 }
 },
 "ChatTopic" : {
 "Type" : "AWS::SNS::Topic",
 "Properties" : {
 "Subscription" : [
 { "Protocol" : "sqs", "Endpoint" : { "Fn::GetAtt" : [ "ChatMessagesQueue", "Arn" ] } }
 ]
 }
 }
 },
 "Outputs" : {
 "ChatMessagesQueueUrl" : {
 "Value" : { "Ref" : "ChatMessagesQueue" }
 },
 "ChatTopicArn" : {
 "Value" : { "Ref" : "ChatTopic" }
 }
 }
}

In the AppHost the AddAWSCloudFormationTemplate method is used to register the CloudFormation resource. The first parameter, which is the Aspire resource name, is used as the CloudFormation stack name when the stackName parameter is not set. If the template defines parameters the value can be provided using the WithParameter method. To configure what AWS account and region to deploy the CloudFormation stack, the WithReference method is used to associate a SDK configuration.

var awsResources = builder.AddAWSCloudFormationTemplate("AspireSampleDevResources", "app-resources.template")
 .WithParameter("DefaultVisibilityTimeout", "30")
 .WithReference(awsConfig);

You can also add custom tags to the CloudFormation stack using the WithTag method:

var awsResources = builder.AddAWSCloudFormationTemplate("AspireSampleDevResources", "app-resources.template")
 .WithParameter("DefaultVisibilityTimeout", "30")
 .WithReference(awsConfig)
 .WithTag("Environment", "Development")
 .WithTag("Project", "AspireSample")
 .WithTag("Owner", "DotNetTeam");

The outputs of a CloudFormation stack can be associated to a project using the WithReference method.

builder.AddProject<Projects.Frontend>("Frontend")
 .WithReference(awsResources);

The output parameters from the CloudFormation stack can be found in the IConfiguration under the AWS:Resources config section. The config section can be changed by setting the configSection parameter of the WithReference method associating the CloudFormation stack to the project.

var chatTopicArn = builder.Configuration["AWS:Resources:ChatTopicArn"];

Alternatively a single CloudFormation stack output parameter can be assigned to an environment variable using the GetOutput method.

builder.AddProject<Projects.Frontend>("Frontend")
 .WithEnvironment("ChatTopicArnEnv", awsResources.GetOutput("ChatTopicArn"))

Importing existing AWS resources

To import AWS resources that were created by a CloudFormation stack outside the AppHost the AddAWSCloudFormationStack method can be used. It will associate the outputs of the CloudFormation stack the same as the provisioning method AddAWSCloudFormationTemplate.

var awsResources = builder.AddAWSCloudFormationStack("ExistingStackName")
 .WithReference(awsConfig);

builder.AddProject<Projects.Frontend>("Frontend")
 .WithReference(awsResources);

Provisioning application resources with AWS CDK

Adding AWS CDK to the AppHost makes it possible to provision AWS resources using code. Under the hood AWS CDK is using CloudFormation to create the resources in AWS.

In the AppHost the AddAWSCDK methods is used to create a CDK Resources which will hold the constructs for describing the AWS resources.

A number of methods are available to add common resources to the AppHost like S3 Buckets, DynamoDB Tables, SQS Queues, SNS Topics, Kinesis Streams and Cognito User Pools. These resources can be added either the CDK resource or a dedicated stack that can be created.

var stack = builder.AddAWSCDKStack("Stack");
var bucket = stack.AddS3Bucket("Bucket");

builder.AddProject<Projects.Frontend>("Frontend")
 .WithReference(bucket);

Resources created with these methods can be directly referenced by project resources and common properties like resource names, ARNs or URLs will be made available as configuration environment variables. The default config section will be AWS:Resources

Alternative constructs can be created in free form using the AddConstruct methods. These constructs can be references with the WithReference method and need to be provided with a property selector and an output name. This will make this property available as configuration environment variable

var stack = builder.AddAWSCDKStack("Stack");
var constuct = stack.AddConstruct("Construct", scope => new CustomConstruct(scope, "Construct"));

builder.AddProject<Projects.Frontend>("Frontend")
 .WithReference(construct, c => c.Url, "Url");

Integrating AWS Lambda Local Development

You can develop and test AWS Lambda functions locally within your .NET Aspire application. This enables testing Lambda functions alongside other application resources during development.

Adding Lambda Functions

To add a Lambda function to your .NET Aspire AppHost, use the AddAWSLambdaFunction method. The method supports both executable Lambda functions and class library Lambda functions:

var awsConfig = builder.AddAWSSDKConfig()
 .WithProfile("default")
 .WithRegion(RegionEndpoint.USWest2);

// Add an executable Lambda function
builder.AddAWSLambdaFunction<Projects.ExecutableLambdaFunction>(
 "MyLambdaFunction", 
 lambdaHandler: "ExecutableLambdaFunction")
 .WithReference(awsConfig);

// Add a class library Lambda function
builder.AddAWSLambdaFunction<Projects.ClassLibraryLambdaFunction>(
 "MyLambdaFunction", 
 lambdaHandler: "ClassLibraryLambdaFunction::ClassLibraryLambdaFunction.Function::FunctionHandler")
 .WithReference(awsConfig);

The lambdaHandler parameter specifies the Lambda handler in different formats depending on the project type:

• For executable projects: specify the assembly name.
• For class library projects: use the format {assembly}::{type}::{method}.

Amazon Lambda Test Tool Automatic Installation

When adding Lambda functions to your .NET Aspire application, the integration automatically manages the installation and updates of the Amazon.Lambda.TestTool. This tool is needed for local Lambda function emulation.

You can customize the tool installation behavior by calling AddAWSLambdaServiceEmulator before any AddAWSLambdaFunction calls:

builder.AddAWSLambdaServiceEmulator(new LambdaEmulatorOptions
{
 DisableAutoInstall = false,
 OverrideMinimumInstallVersion = "0.1.0",
 AllowDowngrade = false
});

// Add Lambda functions after configuring the emulator
var function = builder.AddAWSLambdaFunction<Projects.MyFunction>("MyFunction", "MyFunction");

The LambdaEmulatorOptions provide the following customization:

• DisableAutoInstall: When set to true, it prevents the automatic installation or update of the Lambda Test Tool.
• OverrideMinimumInstallVersion: Allows you to specify a minimum version of the Lambda Test Tool to be installed. If a newer version is already installed, it will be used unless AllowDowngrade is set to true.
• AllowDowngrade: If set to true, it permits downgrading to an older version of the Lambda Test Tool when the specified version is older than the currently installed version.

API Gateway Local Emulation

To add an API Gateaway emulator to your .NET Aspire AppHost, use the AddAWSAPIGatewayEmulator method.

// Add Lambda functions
var rootWebFunction = builder.AddAWSLambdaFunction<Projects.WebApiLambdaFunction>(
 "RootLambdaFunction", 
 lambdaHandler: "WebApiLambdaFunction");

var addFunction = builder.AddAWSLambdaFunction<Projects.WebAddLambdaFunction>(
 "AddLambdaFunction", 
 lambdaHandler: "WebAddLambdaFunction");

// Configure API Gateway emulator
builder.AddAWSAPIGatewayEmulator("APIGatewayEmulator", APIGatewayType.HttpV2)
 .WithReference(rootWebFunction, Method.Get, "/")
 .WithReference(addFunction, Method.Get, "/add/{x}/{y}");

The AddAWSAPIGatewayEmulator method requires:

• A name for the emulator resource
• The API Gateway type (Rest, HttpV1, or HttpV2 )

Use the WithReference method to connect Lambda functions to HTTP routes, specifying:

• The Lambda function resource
• The HTTP method
• The route pattern

Wildcard Paths

The API Gateway emulator supports the use of wildcard path. To define a wildcard path, you can use the {proxy+} syntax in the route pattern.

Here's an example of how to set up an API Gateway emulator with a wildcard path:

// Add an ASP.NET Core Lambda function
var aspNetCoreLambdaFunction = builder.AddAWSLambdaFunction<Projects.AWSServerless>("Resource", "AWSServerless");

// Configure the API Gateway emulator
builder.AddAWSAPIGatewayEmulator("APIGatewayEmulator", APIGatewayType.Rest)
 .WithReference(aspNetCoreLambdaFunction, Method.Any, "/")
 .WithReference(aspNetCoreLambdaFunction, Method.Any, "/{proxy+}");

In this example, the first WithReference call maps the root path (/) to the ASP.NET Core Lambda function. The second WithReference call maps the wildcard path (/{proxy+}) to the same Lambda function.

The {proxy+} syntax captures the entire remaining part of the URL path and passes it as a parameter to the Lambda function.

By combining the ASP.NET Core bridge library and the API Gateway emulator with wildcard paths, you can easily develop and test your serverless ASP.NET Core applications locally, providing a seamless experience between local development and deployment to AWS Lambda.

Deployment to AWS (Preview)

Note: This feature is currently in preview and subject to change based on feedback. We encourage you to try it out and share your feedback!

The AWS deployment feature for .NET Aspire enables you to deploy your Aspire applications directly to AWS. The deployment system transforms your Aspire AppHost resources into AWS CDK constructs, which are then synthesized into CloudFormation templates and deployed to your AWS account. This provides a seamless path from local development to cloud deployment.

For comprehensive documentation including advanced scenarios, implementation details, and architectural guidance, see the .

Prerequisites

Before deploying to AWS, ensure you have:

• Node.js 22.x - Required for AWS CDK, which the deployment system uses to generate CloudFormation templates
• AWS CDK installed globally: npm install -g aws-cdk
• AWS CDK Bootstrap - Must be run on your target AWS account and region before first deployment: cdk bootstrap aws://ACCOUNT-NUMBER/REGION

The deployment system leverages AWS CDK to transform your Aspire resources into cloud infrastructure, which requires Node.js and the CDK CLI to be available in your environment.

Getting Started

Add an AWS CDK environment to your AppHost to enable deployment:

// Add to opt-in to using the preview publish/deployment APIs.
#pragma warning disable ASPIREAWSPUBLISHERS001

var builder = DistributedApplication.CreateBuilder(args);

// Add AWS CDK environment
builder.AddAWSCDKEnvironment(
 name: "MyApp",
 cdkDefaultsProviderFactory: CDKDefaultsProviderFactory.Preview_V1
);

// Add your resources
var webApp = builder.AddProject<Projects.WebApp>("webapp");

builder.Build().Run();

The name parameter identifies your application stack in AWS, and the cdkDefaultsProviderFactory parameter specifies which version of default behaviors to use (currently Preview_V1 for the preview release).

Deploying Your Application:

To deploy your application to AWS, use the Aspire CLI:

• aspire publish - Transforms your Aspire resources into AWS CDK constructs and synthesizes them into a cdk.out directory containing CloudFormation templates
• aspire deploy - Runs the publish step and then uses the AWS CDK CLI to deploy the cdk.out directory to your AWS account

The deployment process will prompt you for AWS credentials and region if not already configured.

Basic Workflows

Automatic Resource Mapping

By default, Aspire resources are automatically mapped to appropriate AWS services based on their type:

// Add to opt-in to using the preview publish/deployment APIs.
#pragma warning disable ASPIREAWSPUBLISHERS001

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAWSCDKEnvironment(
 name: "MyApp",
 cdkDefaultsProviderFactory: CDKDefaultsProviderFactory.Preview_V1
);

// Web projects automatically deploy to ECS Fargate Express
var webApp = builder.AddProject<Projects.WebApp>("webapp");

// Lambda functions automatically deploy to AWS Lambda
var function = builder.AddAWSLambdaFunction<Projects.MyFunction>("function", "<lambda-function-handler>");

// Redis automatically deploys to ElastiCache
var cache = builder.AddRedis("cache");

builder.Build().Run();

The deployment system analyzes each resource and selects the most appropriate AWS service automatically. You don't need to specify deployment targets unless you want to customize the defaults.

Customizing Deployment Targets

You can override the default deployment target for any resource using Publish extension methods:

// Add to opt-in to using the preview publish/deployment APIs.
#pragma warning disable ASPIREAWSPUBLISHERS001

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAWSCDKEnvironment(
 name: "MyApp",
 cdkDefaultsProviderFactory: CDKDefaultsProviderFactory.Preview_V1
);

// Deploy web app with Application Load Balancer instead of default Express service
var webApp = builder.AddProject<Projects.WebApp>("webapp")
 .PublishAsECSFargateServiceWithALB();

builder.Build().Run();

Each Publish method allows you to customize the AWS service configuration through callbacks that modify CDK construct properties. See the for details on available Publish methods and customization options.

Connecting Resources

Use WithReference() to connect resources - the deployment system automatically configures all necessary connectivity:

var builder = DistributedApplication.CreateBuilder(args);

builder.AddAWSCDKEnvironment(
 name: "MyApp",
 cdkDefaultsProviderFactory: CDKDefaultsProviderFactory.Preview_V1
);

var cache = builder.AddRedis("cache");

// Connect the web app to the cache
var webApp = builder.AddProject<Projects.WebApp>("webapp")
 .WithReference(cache);

builder.Build().Run();

When resources are connected with WithReference(), the system automatically:

• Configures environment variables with connection strings and endpoints
• Attaches resources to the same VPC when required (e.g., for ElastiCache)
• Sets up security groups to allow network access between resources

Your application code can access the referenced resource using the standard .NET Aspire configuration patterns - no AWS-specific code required.

Advanced Scenarios

For advanced deployment scenarios and comprehensive implementation details, see the . The design document covers:

• : Define your own infrastructure alongside Aspire resources, override default constructs (VPC, ECS Cluster, etc.), and integrate with existing AWS infrastructure
• : Customize CDK construct properties and behavior through configuration callbacks
• : Control default values and behaviors with versioned providers, allowing you to opt-in to breaking changes when ready
• : Extend the deployment system to support additional AWS services or alternative deployment options

The design document provides detailed examples and implementation guidance for these advanced use cases, enabling you to customize deployments for production workloads.

Integrating Amazon DynamoDB Local

Amazon DynamoDB provides a local version of DynamoDB for development and testing that is distributed as a container. With version 9.1.0 of the Aspire.Hosting.AWS package, you can easily integrate the DynamoDB local container with your .NET Aspire project. This enables seamless transition between DynamoDB Local for development and the production DynamoDB service in AWS, without requiring any code changes in your application.

To get started in the .NET Aspire AppHost, call the AddAWSDynamoDBLocal method to add DynamoDB local as a resource to the .NET Aspire application.

var builder = DistributedApplication.CreateBuilder(args);

// Add a DynamoDB Local instance
var localDynamoDB = builder.AddAWSDynamoDBLocal("DynamoDBLocal");

For each .NET project in the .NET Aspire application using DynamoDB, add a reference to the DynamoDB local resource.

// Reference DynamoDB local in project
builder.AddProject<Projects.Frontend>("Frontend")
 .WithReference(localDynamoDB);

In the .NET projects that use DynamoDB, you need to construct the DynamoDB service client from the SDK without explicitly setting the AWS Region or service endpoint. This means constructing the AmazonDynamoDBClient object without passing in the Region or an AmazonDynamoDBConfig with the RegionEndpoint property set. By not explicitly setting the Region, the SDK searches the environment for configuration that informs the SDK where to send the requests. The Region is set locally by the AWS_REGION environment variable or in your credentials profile by setting the region property. Once deployed to AWS, the compute environments set environment configuration such as the AWS_REGION environment variable so that the SDK knows what Region to use for the service client.

The AWS SDKs have a feature called Service-specific endpoints that allow setting an endpoint for a service via an environment variable. The WithReference call made on the .NET project sets the AWS_ENDPOINT_URL_DYNAMODB environment variable. It will be set to the DynamoDB local container that was started as part of the AddAWSDynamoDBLocal method.

The AWS_ENDPOINT_URL_DYNAMODB environment variable overrides other config settings like the AWS_REGION environment variable, ensuring your projects running locally use DynamoDB local. After the AmazonDynamoDBClient has been created pointing to DynamoDB local, all other service calls work the same as if you are going to the real DynamoDB service. No code changes are required.

Options for DynamoDB Local

When the AddAWSDynamoDBLocal method is called, any data and table definitions are stored in memory by default. This means that every time the .NET Aspire application is started, DynamoDB local is initiated with a fresh instance with no tables or data. The AddAWSDynamoDBLocal method takes in an optional DynamoDBLocalOptions object that exposes the options that are available for DynamoDB local.

If you want the tables and data to persist between .NET Aspire debug sessions, set the LocalStorageDirectory property on the DynamoDBLocalOptions object to a local folder where the data will be persisted. The AddAWSDynamoDBLocal method will take care of mounting the local directory to the container and configuring the DynamoDB local process to use the mount point.

Local Development with AgentCore (Experimental)

Note: This feature requires net10.0 and is behind the ASPIREAWSAGENTCORE001 experimental flag.

The AgentCore integration provides a local development experience for agents built with the AWS.AgentCore.Hosting package. All emulators run as embedded in-process Kestrel servers — no Docker or separate processes required.

Getting Started

Add the AWS.AgentCore.Hosting package to your agent project:

dotnet add package AWS.AgentCore.Hosting

Use the annotations or extension methods to define your agent. Then in your Aspire AppHost, add a reference to Aspire.Hosting.AWS and configure your agents:

#pragma warning disable ASPIREAWSAGENTCORE001

var builder = DistributedApplication.CreateBuilder(args);

// Register a non-streaming agent with short-term memory
var agent = builder.AddAgentCoreRuntime<Projects.MyAgent>("my-agent")
 .WithInMemory();

// Register a streaming agent
builder.AddAgentCoreRuntime<Projects.MyStreamingAgent>("my-streaming-agent")
 .WithStreaming()
 .WithInMemory();

// Wire a consumer project — AWS_ENDPOINT_URL_BEDROCK_AGENTCORE is injected automatically
builder.AddProject<Projects.MyChatUI>("ChatUI")
 .WithReference(agent);

builder.Build().Run();

Features

Options

builder.AddAgentCoreRuntime<Projects.MyAgent>("my-agent",
 new AgentCoreLocalOptions
 {
 IncludeEmulatorLogs = true, // Route emulator logs to the Aspire dashboard
 RuntimeEmulatorPort = 9000, // Pin the runtime emulator port (default: OS-assigned)
 ChatAppPort = 9001, // Pin the chat app port (default: OS-assigned)
 MemoryEmulatorPort = 9002 // Pin the memory emulator port (default: OS-assigned)
 });

How It Works

When the Aspire AppHost starts, each AddAgentCoreRuntime call:

1. Starts an embedded Runtime Emulator that proxies invocations to your agent
2. Starts an embedded Chat App for interactive testing from the Aspire dashboard
3. Optionally starts a Memory Emulator for short-term memory

The Aspire dashboard shows clickable URLs for each emulator alongside your agent resource.

Feedback & contributing

https://github.com/aws/integrations-on-dotnet-aspire-for-aws