Provides extension methods and resources definition for a .NET Aspire AppHost to configure the AWS SDK for .NET and AWS application resources.
- Configure AWS credentials
- Node.js (AWS CDK only)
In your AppHost project, install the Aspire.Hosting.AWS library with NuGet:
dotnet add package Aspire.Hosting.AWS
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.
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);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"))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);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");