Using Amazon CodeCatalyst blueprints to build and deploy .NET serverless applications

In part 2 of this blog post series, we show how to set up a project in Amazon CodeCatalyst and collaborate on the coding, building, testing, and deployment of .NET serverless applications in your AWS environments.

Consider reviewing the first post, which introduced CodeCatalyst. It explains the compute fleet options that are available for your CI/CD workflows, and how to set up a CodeCatalyst project for containerized ASP.NET Web API deployments to Amazon Elastic Container Service (Amazon ECS).

Prerequisites

The following prerequisites are needed if you want to follow along and set up a CodeCatalyst project in your AWS account. If you have previously set up some of them by following other posts in this blog series, you can reuse them. However, some items may require modification, such as the IAM role,  which will require an update to provide the required permissions.

1. An understanding of the following CodeCatalyst concepts – Spaces, Projects, Repositories, Workflows, Deployment Environments, and Dev Environments.
2. A basic understanding of AWS Lambda and Amazon API Gateway.
3. An AWS account for billing purposes and an AWS account for deployment. They can be separate accounts, but in this blog post, we will use a single account for both. Although you are required to provide an AWS account for billing, the CodeCatalyst space you will create will use the free tier (default) for this walkthrough.
4. An AWS Builder ID that lets you create a personal identity (not related to your job, school, or other organizations) for you to access participating AWS tools and services. To create your Builder ID, follow the instructions on the AWS Sign-In guide or by choosing Sign up from the CodeCatalyst website.
5. A CodeCatalyst space with the space administrator role. You can follow the instructions from the user guide to create the space. You will be required to provide an AWS account (step 3) as the billing account during the space creation. If your deployment account (step 3) Is different from your billing account, follow steps 1-3 in the to add your deployment account to the same CodeCatalyst space.
6. An AWS Identity and Access Management (IAM) role in the AWS account (step 3) where you will deploy your application. This IAM role will have the permissions for deployment and a trust policy giving CodeCatalyst permissions to assume the role. 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 the minimal permissions to roles that are necessary for your team to operate.

Create a CodeCatalyst project for .NET serverless applications

Once you have met the prerequisites, log into your CodeCatalyst account and navigate to the space you want to use. Choose Create Project (Figure 1).

Figure 1: Create Project

On the next screen (Figure 2), populate the values in the project creation wizard.

• How would you like to Start? – Select Start with a blueprint.
• Choose a blueprint – Enter “.NET” in the search bar. As of the publishing of this post, there are two blueprints for .NET projects:
  • .NET serverless application – Creates a CodeCatalyst project with a sample .NET 6.0 serverless application and creates workflows to build, test, and deploy the application to AWS Lambda.
  • ASP.NET Core web API – Creates an ASP.NET Core 6.0 web API project and a CI/CD workflow to build and deploy the application to the AWS service you choose. Refer to the first blog post in this series where we explain this blueprint in detail.

Select the .NET serverless application blueprint. Once you select, a panel on the right side of the screen will appear, which provides details like architecture overview, the required IAM permissions, and the project resources that will be created.

• Choose Next to continue configuring your project.

Figure 2: Create project from the .NET serverless application blueprint

On the following screen (Figure 3), you will configure the blueprint for project creation.

• Name your project – [Required] Choose a name for your project. Note that project names can’t be changed after creation.

Figure 3: Configure the project name

• Project resources.
  • Environment – The environment where the code will be deployed to. It will automatically select the default environment in the blueprint for production.
  • AWS account connection – Select the account connection to your target deployment account.
  • Deployment Role – The IAM role (CodeCatalystPreviewDevelopmentAdministrator-xxxxxx) you created as a prerequisite.
  • AWS Lambda Project Type – The blueprint creates one or more Lambda functions as part of the serverless application. With this option, you can select what kind of Lambda function(s) you want to create. You have several options here. For this walkthrough, we are going to select Annotations Framework (Preview) (C#).
    Note: If you are developing Lambda functions with C#, we highly recommend that you read about .NET Annotations for Lambda Framework. Select different options here and choose the View Code and View workflow buttons on the right (Figure 6) to preview the code (Figure 7) and workflows (Figure 8) that will be generated for you with different AWS Lambda Project Types.

Figure 4: Configure project resources

• Code section – [All fields are required] Choose the default values and customize as desired.
  • Code Repository name – Source control repository name that will be created as a part of this project.
  • .NET Project name – Name for the .NET project that will be included in the code repo with sample AWS serverless application code.
  • CloudFormation stack name – A name for the AWS CloudFormation stack that will be deployed. This blueprint uses CloudFormation to define and deploy the AWS infrastructure required for your application to run.
  • AWS Region – The AWS region to use for deployment.

Figure 5: Code configuration

Choose the View code and View workflow buttons in the Generate project preview section to preview the resources that will be created by the blueprint with the selected configuration.

Figure 6: Generate project preview resources

Figure 7: Code Preview with the selected blueprint configuration

Figure 8: Workflow preview with the selected blueprint configuration

After you review the project resources, choose Create project (Figure 5). It will take a few moments to create the project and its resources. Once the project is created, you will be redirected to the project overview screen (Figure 9), which displays information such as the repos, workflows, and open pull requests.

Figure 9: Project overview

Blueprint walkthrough

Now that you have created the .NET serverless project from the blueprints, you can review the resources that have been created.

On the project overview screen, choose View repository. It will take you to the main branch of the selected repository (ServerlessFunctions in this example) the blueprint created for you (Figure 10).

Figure 10: Files in the source code repository

Note that the following folders/files are created by the .NET serverless application blueprint (Figure 10).

• .cloud9 –  Contains custom runners that will install and update Amazon.Lambda.Tools .NET Core Global Tool to use with AWS Cloud9, a web-based integrated development environment (IDE), for coding.
• .codecatalyst – Contains two CodeCatalyst workflows, main.yaml and pull-request.yaml, that the blueprint created. We will explain these workflows in more detail later in this post.
• .vscode – This folder contains the configuration files for Visual Studio Code when used as an IDE.
• src – Source code for your .NET serverless application that uses the Lambda Annotation framework. The file aws-lambda-tools-defaults.json is used to preset values for all the command line switches used by the Amazon.Lambda.Tools global tool that deploys your serverless application. It also contains the serverless.template file used by AWS CloudFormation to provision resources for your application. If you observe the contents of serverless.template file, you will notice that it uses the AWS Serverless Application Model (AWS SAM) template specification. AWS SAM templates are an extension of AWS CloudFormation templates, with some additional components that make them easier to work with serverless applications.
• tests – Unit tests for your Lambda functions.
• devfile.yaml – devfile to use with the Dev Environments feature in CodeCatalyst.

Workflows

Workflows in CodeCatalyst are a series of step-by-step instructions, called actions, that describe how to build, test, and deploy your applications as part of a CI/CD pipeline. The workflows are configured using workflow definition YAML files. The .NET serverless application blueprint has created two workflows for us, pull-request.yaml and main.yaml.

Next, examine what these two workflows do. Choose Workflows from the CI/CD menu (Figure 11).

Figure 11: Workflows created by the blueprint

pull-request workflow

Select pull-request from the Workflows screen and navigate to the Definition tab of the workflow (Figure 12). The definition includes both a YAML file and a visual representation. There are two steps in the workflow.

1. The WorkflowSource step in the visual corresponds to the Triggers in the YAML file. This step defines how your workflow is triggered. If you don’t have a Triggers section defined, you have to manually start the workflow. In this example, the workflow will be triggered whenever a new pull request is created, or a new revision is made to an existing pull request on any branch in the source repo. Learn more about working with triggers in the user guide.
2. The second step is a CodeCatalyst build action named Build_And_Test. It builds the source code (WorkflowSource) and runs the unit tests using the commands in the Configuration code block below in the workflow YAML. This build action has enabled auto-discovery of test reports. When you enable auto-discovery, CodeCatalyst searches all inputs passed into the action, and all files generated by the action itself, looking for Test, Code Coverage, and Software Composition Analysis (SCA) reports. For each report that is found, CodeCatalyst transforms it into a report that can be viewed and manipulated through the CodeCatalyst console.

Configuration:
  Steps:
    - Run: dotnet build ServerlessApp.sln -c Release
    - Run: dotnet test ServerlessApp.sln -c Release --no-build --logger “trx”

Figure 12: pull-request workflow definition

main workflow

Navigate back to the workflows screen and choose the main workflow. On the Definition tab, you will find that there are three steps in this workflow (Figure 13).

1. The WorkflowSource step sets the workflow to be triggered on every PUSH to the main branch.
2. The Build_And_Test action remains the same as the one from pull-request workflow. It builds the code, runs the unit tests, and generates CodeCatalyst test reports.
3. The Deploy_To_AWS build action deploys the serverless application to your AWS environment. Following are some details of the action.

• There is an action dependency defined by the DependsOn element that is set to Build_And_Test. That means Deploy_To_AWS runs after Build_And_Test action runs successfully.
• The action installs Lambda.Tools .NET Core Global Tool on the CodeCatalyst compute and uses the dotnet lambda deploy-serverless command to deploy the application to the AWS environment defined in the Environment section. The next section will explain this global tool in more detail.

Figure 13: main workflow definition

Deployment using .NET Global Tool ‘Amazon.Lambda.Tools’

The workflow action uses .NET Global tool for Lambda commands to build and deploy the serverless application. If you are developing .NET applications on AWS, we provide a set of these global tools with the AWS Extensions for .NET CLI so you can automate your .NET application deployments to AWS.

- Run: dotnet tool install Amazon.Lambda.Tools --global --version 5.*

The above command installs the .NET CLI extension for Lambda as a global tool on the CodeCatalyst compute for our workflow.

- Run: dotnet lambda deploy-serverless  --region us-east-1 --resolve-s3 true --stack-name serverless-stack-XXXXX

Then we use the deploy-serverless command of the extension to deploy our serverless application. The command uses the AWS SAM template, serverless.template, from the src/ServerlessApp directory to deploy the Lambda functions along with other AWS resources defined in the file.

Running the main workflow

After your project creation, the main workflow will automatically run for the first time. Once the workflow finishes the run, you can review the deployment by navigating to the URL of the deployed serverless application (Figure 14).

1. Choose the Deploy_To_AWS action
2. Find the Output Name and Value that are toward the end of the logs that are displayed to get the URL to access the deployed API.

Navigate to that URL to test out the API.

Figure 14: URL to access the Deployed API

Cleanup

Delete the CloudFormation stack CodeCatalyst created for you. This will help you avoid recurring charges if you don’t need those AWS resources any more. The CloudFormation stack name is what you provided when configuring the blueprint for your project (Figure 4). If you chose the default value, it will be named serverless-stack-XXXXX.

Conclusion

In this blog post, you have learned how to set up CI/CD workflows for your .NET serverless applications using the Amazon CodeCatalyst .NET serverless application blueprint. Read through the CodeCatalyst User Guide to learn more about how to implement your own workflows to address your CI/CD needs.

To learn more about serverless computing options on AWS, visit the AWS serverless page. AWS SAM provides components that make it easy to define, debug, test, package, and deploy serverless applications to AWS. To learn more about how AWS SAM simplifies your serverless application development, read through the Developer Guide.

Now that you are familiar with CodeCatalyst, create your own CodeCatalyst account and give it a try. 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.