In this blog post, the first in a series of posts about using .NET with Amazon CodeCatalyst, we will guide you through building and deploying a .NET 6.0 ASP.NET Core web API to Amazon Elastic Container Service (Amazon ECS) using the ASP.NET Core web API project blueprint included with CodeCatalyst and the AWS .NET deployment tool.

What is Amazon CodeCatalyst? It is a new cloud-based, unified collaboration service for software development teams. It provides a full set of continuous integration and continuous delivery (CI/CD) tools that help development teams plan their work, collaborate on the code, and build, test, and deploy applications. CodeCatalyst does this by providing a rich set of features that boost developer productivity and help teams accomplish more with less.

About CodeCatalyst build options

Before exploring the overall CodeCatalyst experience for building and deploying ASP.NET 6.0 based web APIs, we will review the supported build options for .NET applications provided by CodeCatalyst. CodeCatalyst provides two compute types for running your workflows:

1. On-demand fleets provide fully-managed, Linux-based compute using Amazon Elastic Compute Cloud (Amazon EC2) or AWS Lambda, which are provisioned when a build action starts and deprovisioned when it finishes.
2. Provisioned fleets provide Linux- or Windows-based Amazon EC2 instances managed by CodeCatalyst that are ready to process actions immediately. To use provisioned fleets, you need to be in the Standard pricing tier.

To build .NET applications, you can choose any fleet type and operating system. For this blog post, we will build a .NET Web API using on-demand fleets. In a future blog post, we will show you how to build a .NET Framework application using Windows-based provisioned fleets.

Prerequisites

Review the following list of prerequisites to ensure you can follow all the steps described in the following sections in your own environment. You will need:

1. An AWS Builder ID. You can learn how to create one in the product documentation.
2. Access to a CodeCatalyst space. You can learn how to create one of your own or how to accept an invitation in the product documentation.
3. An AWS account added to the CodeCatalyst space, because the target deployment infrastructure is in AWS. You can read more about how to accomplish this in the product documentation.
4. An AWS Identity and Access Management (IAM) role in the AWS account you will add to the space, allowing CodeCatalyst to deploy into that account. For this walkthrough, you can create and attach the CodeCatalystPreviewDevelopmentAdministrator IAM role to your CodeCatalyst space by following the instructions in the documentation. As a best practice, you should always assign these roles the least amount of permissions necessary for your teams to operate.

Creating the CodeCatalyst project

Once you have met the prerequisites, you can create a project in CodeCatalyst. Log into your CodeCatalyst account and navigate to the CodeCatalyst space. Choose Create project and select the Start with a blueprint option (Figure 1).

A blueprint is a project synthesizer that generates and extends application support files and dependencies for you.

Figure 1: CodeCatalyst .NET blueprints screen

Enter “.NET” in the Choose a blueprint search box. You will see the list of available blueprints for .NET applications. At the time of writing this blog post, there are two available blueprints:

1. ASP.NET Core web API: Creates an ASP.NET Core 6.0 web API project alongside a CI/CD workflow to build and deploy the application to the AWS service you choose.
2. .NET serverless application: Creates a .NET 6.0 AWS serverless application project alongside a CI/CD workflow that builds and deploys the application to AWS Lambda.

When you select a blueprint, a side panel will appear on the right with its full description, architecture overview, connections and permissions, and the project resources it creates (Figure 2).

Figure 2: ASP.NET Core Web API blueprint description screen

This blog shows the use of the ASP.NET Core web API blueprint. Select that option and choose Next to continue the configuration of the project.

In the following screen (Figure 3), you will provide configuration options for CodeCatalyst to create the project for you. For this blueprint, you need to provide the following information:

Figure 3: ASP.NET Core Web API blueprint configuration screen

• Name your project (required): CodeCatalyst will use it to name the project and the default source code repository.
• Environment (required values)
  • AWS account connection & Deployment role: The AWS account you are deploying to and the role that CodeCatalyst will use when deploying your application. If you select No AWS account, you can add one later, but the workflow will not run successfully until you do.
  • Language: The .NET programming language in which you want the source code to be created. You can select C# or F#.
  • AWS deployment service: The supported AWS service you want to deploy the application to. If you select “None,” the workflow files will not contain any actions to deploy your application to AWS.
• Code (optional values)
  • Code Repository name: Name of the source code repository.
  • .NET Project name: Name of the project and namespace to create.
  • Production Deployment: Selecting this will use a configuration that includes both load balancing and larger allocated resources for AWS services.
  • AWS Region: The region where to deploy the application.

On the right side of the screen (Figure 4), you will find the information about the blueprint, including the same description as on the previous screen. You will also find two additional buttons: View code and View workflow.

Figure 4: ASP.NET Core Web API blueprint information screen

Choosing View code will display a panel where you can explore the code files to be generated by the blueprint template based on your project configuration (Figure 5). If you change the configuration, the generated files will automatically update.

Figure 5: ASP.NET Core Web API blueprint code preview screen

If you choose View workflow, the workflow editor will appear (Figure 6). It displays, either visually or as YAML, the workflow that CodeCatalyst will create for you based on the project configuration. Changing your project configuration will update the workflow, the same as with the generated code view.

Figure 6: ASP.NET Core Web API blueprint workflow preview screen

For this example, select C# as the language and Amazon Elastic Container Service for deployment service. Choose Create project to start the creation of the project (Figure 7). This should complete in a few seconds.

Figure 7: Creating project screen

Exploring the generated files

Once the project creation has completed, you will be redirected to the project overview screen. You can view information, such as repositories, workflows, and pull requests that make up your project. On the Overview screen of the project, choose the View repository button to navigate to the default source code repository (Figure 8).

Figure 8: Project repository screen

On the project’s repository page, you will find that the source code generated by the blueprint has the following structure, as shown in Figure 9.

Figure 9: ASP.NET Core Web API blueprint generated code structure

Note the following folders:

• .cloud9: Contains AWS Cloud9 runners used to configure AWS Cloud9 when used as a development environment.
• .codecatalyst
  • deployment-settings: Contains different deployment settings files that are used with the .NET deployment when deploying to AWS Elastic Beanstalk (Windows & Linux), AWS AppRunner and AWS Fargate on Amazon ECS. There are two variants for each file: production and non-production.
  • workflows: Contains the YAML code for the CodeCatalyst workflow to build and deploy the application.
• .vscode: Contains default configurations for Visual Studio Code when used as a development environment.
• src: Contains the source code for the project.
• tests: Contains the unit tests for the project.

A file named “devfile.yaml” is also created. It is used to configure CodeCatalyst Dev Environments.

Before continuing, you are encouraged to review the file structure in more detail to understand what has been created and will be deployed with the CI/CD workflow.

Exploring the default CI/CD workflow

In CodeCatalyst, a workflow is an automated procedure that describes how to build, test, and deploy your code as part of a CI/CD system. It defines a series of steps, or actions, to take during a workflow run, and also defines the events, or triggers, that cause the workflow to start.

Next, explore the workflow generated by the ASP.NET Core web API blueprint. On the navigation menu, expand the CI/CD menu, and then choose Workflows (Figure 10).

Figure 10: CodeCatalyst Workflows menu item

Note that there are two workflows already created: pull-request and main. The workflow pull-request will be run in response to pull requests, while the main workflow will run when new commits are pushed to the main branch of the repository. The main workflow has the same steps as the pull-request workflow, plus a deployment step. Choose the main workflow to explore its structure (Figure 11).

Figure 11: ASP.NET Core Web API blueprint generated workflows

On the next screen, choose the Definition tab to display the YAML definition of the workflow side-by-side with its visual representation (Figure 12).

Figure 12: ASP.NET Core Web API blueprint main workflow YAML

Note that the workflow is configured with three main elements:

1. Triggers: Makes the workflow start each time a commit is pushed into the main branch.
2. Build_And_Test: Build and test the code using the .NET 6 CLI running on the default build image. It then searches for test reports on the ./TestResults folder to display their results on the screen.
3. Deploy_To_AWS: Deploys the application to AWS using the AWS Deploy Tool for .NET. It installs the needed dependencies, like the zip yum package for Amazon Linux, and configures the AWS connection to use.
   You can easily change the target AWS service you are deploying to by changing the JSON file passed to the –apply argument.

Running the default CI/CD workflow

The main workflow will automatically run for the first time as soon as you create the CodeCatalyst project. This initial run will take between 15 and 30 minutes to complete. Once it has finished, you can explore the deployed application by navigating to the Amazon ECS service load balancer URL found in the Endpoint AWS resource near the end of the logs of the dotnet aws deploy command inside the Deploy_To_AWS action, as illustrated in Figure 13.

Figure 13: ASP.NET Core Web API blueprint successful run logs

Exploring the AWS .NET deployment tool settings

The AWS Deploy Tool for .NET is an interactive tool for both the .NET CLI and the AWS Toolkit for Visual Studio that allows you to deploy .NET applications with minimal AWS knowledge and with few clicks or commands. The AWS Deploy Tool for .NET command line tool is ideal for CI/CD because it gives you the ability to deploy your application with a single command. The AWS Deploy Tool for .NET supports multiple application types and AWS compute services via the concepts of deployment recipes and deployment settings.

You can explore the contents of the .codecatalyst/deployment/settings/non-prod/ecs-fargate-deployment-settings.json deployment settings. The file defines the recipe to use for deploying your .NET application (in this case, AspNetAppEcsFargate), and overrides some of the default values defined in the recipe. In the case of the AspNetAppEcsFargate recipe, it overrides options such as the name of the Amazon ECS cluster, the number of vCPUs, and amount of memory used by the Amazon ECS task definition. You can learn more about all the option settings for this and all other recipes in the official GitHub repo.

When you use the AspNetAppEcsFargate recipe to deploy your application, the .NET deployment tool will run the following tasks:

1. Search for a Dockerfile in the project and run docker build. In case the tool doesn’t find a Dockerfile, it will try to generate one.
2. Create an Amazon Elastic Container Registry (Amazon ECR) to push the container image.
3. Push the container image to the Amazon ECR repository.
4. Deploy the AWS Cloud Development Kit (AWS CDK) project associated with the recipe with the values you overwrote in the deployment settings file.
5. Output to the console AWS resource details like the load balancer endpoint and others.

If the resources that the recipe creates by default are not what you need for your application, you can create a custom deployment project, which creates an AWS CDK project you can customize to your needs.

Cleanup

To avoid incurring future charges, delete the resources created by the CodeCatalyst workflow. If you used the values provided in this blog post, the resources will be named:

• AWS CloudFormation stack: CompanyHelloWebAPI
• Amazon ECR repository: companyhellowebapi

Conclusion

In this blog post, you learned how to use the ASP.NET Core web API blueprint to deploy a .NET application to AWS Fargate on Amazon ECS. The blueprint created a project with a source code repository, sample source code, and CI/CD workflows, all ready to deploy to AWS.

This is just the starting point of your application’s journey. Next, you can push your own source code and modify the CI/CD workflows to fit the needs of your own applications.

If you have any ideas on how CodeCatalyst blueprints can help you get started quickly and be more productive developing .NET applications, please share them with us in the official .NET on AWS Twitter handle. Visit .NET on AWS for additional information and resources for running .NET applications on AWS.

AWS can help you assess how your company can get the most out of cloud. Join the millions of AWS customers that trust us to migrate and modernize their most important applications in the cloud. To learn more on modernizing Windows Server or SQL Server, visit Windows on AWS. Contact us to start your modernization journey today.