Skip to content

Contributing to the project

The AWS Deploy Tool for .NET is an open source project hosted on GitHub and we openly welcome community contributions.

Click here to submit a pull request.

Using the Deployment Tool from Source

  • Ensure that all the pre-requisties (including Docker) are installed and your default AWS profile has admin access
  • Clone the repository using git clone https://github.com/aws/aws-dotnet-deploy.git
  • Open AWS.Deploy.sln in Visual Studio.
  • Ensure that src/AWS.Deloy.CLI is set as the start up project.
  • Go to AWS.Deploy.CLI debug properties by clicking the following drop down
  • Add a new launch profile called AWS.Deploy.CLI
  • In the Command line arguments text box add the following (leave other text boxes blank):

deploy —project-path path/to/aws-dotnet-deploy/testapps/WebAppWithDockerFile

The above command assumes you have a [default] profile configured in your AWS credentials file. If you want to use a different profile, use the --profile switch. You can also specify a different region via the --region switch.

  • Select the AWS.Deploy.CLI launch profile and run the tool
  • Follow the prompts on the screen and perform a deployment using any compatible recommendation.
  • A successful deployment indicates that your environment is set up correctly and you can proceed to debugging the source code.

Repository Overview

The .NET deployment tool comprises of various top level components.

AWS.Deploy.CLI

This component controls the UI elements for the .NET deployment tool and serves as the first entry point when running the tool. This is the layer that end users directly interact with and it uses the System.CommandLine package for the CLI UX.

Key Components

  • Program.cs - Serves as the entry point to the CLI application.

  • CustomServiceCollectionExtension - This serves as the dependency injection container and registers all the dependencies required by the deployment tool.

  • CommandFactory - This instantiates and executes the top-level dotnet aws command and other sub-commands like deploy, list-deployments and delete-deployment. It also holds all the CLI switches that are applicable to the any command. All new commands/switches will be declared and instantiated via this class.

  • CommandHandlerInput - This contains the POCO objects that hold the values for all CLI switches of the associated command. These objects are provided as input while creating the command handlers. See here for an example.

  • TypeHintCommandFactory - Some of the option settings require special logic on how to prompt the user for a value and how to parse the user input. This class stores the mapping between the option settings and their corresponding typehints. TypeHints can be found here. TypeHintResponses can be found here

  • ConsoleUtilities - Contains utility methods to drive the CLI UX

  • CommandLineWrapper - Contains utility methods to invoke command line processes like docker build or cdk deploy

  • Exceptions - Declares all exceptions that are thrown by the AWS.Deploy.CLI component

  • AWS.Deploy.CLI.UnitTests - Contains unit tests for this component

AWS.Deploy.Recipes

This component contains the recipes that serve as the backbone of each deployment recommendation. It also contains the CDK templates that is used to deploy the customer’s .NET application as a CloudFormation stack

Key Components

  • RecipeDefinitions - It contains the deployment recipes that target different AWS services. Each recipe file contains a list of option settings which is a collection of AWS resources that users can customize as per their needs.

    • See here to learn more about the recipe file schema.
    • See here to look at the support matrix between recipes and different .NET application types.

  • DeploymentBundleDefinitions - It contains the common option settings that users can customize for container based and non-container based recipes. All recipes have a DeploymentBundle property that specifies how to package the user’s .NET project for deployment.

    • Container - Indicates that Docker is used to build the Docker image and pushed to Amazon Elastic Container Registry.
    • DotnetPublishZipFile - Indicates that the dotnet publish is used to prepare the user’s .NET project for deployment.

  • CdkTemplates - It contains the CDK templates for recipe files found here. All recipes with the DeploymentType set to “CdkProject” have their own specific CDK template identified by the CdkProjectTemplate property.

AWS.Deploy.CDK.Common

This component contains the common utility classes and methods that are used by the CDK templates found here.

Note - The AWS.Deploy.CDK.Common.csproj is never referenced directly because it contains the Amazon.CDK.Lib package which is close to 70 MB is size. Instead, if we need functionality from this project then we directly link the appropriate .cs files. See here for an example.

AWS.Deploy.Common

This component contains POCO objects and common logic that is used by other components in the deployment tool

Note - This project does not reference any other project except for ../src/AWS.Deploy.Constants/AWS.Deploy.Constants.projitems

Key Components

  • ProjectDefinitionParser - This class contains the logic to validate whether a .NET project exists at the path specified via dotnet aws deploy —project-path <PROJECT-PATH>. It also parses the user’s csproj/fsproj file and returns a ProjectDefinition

  • RecipeDefinition - This is a POCO class that serves as the deserialized model for all recipe files found here

  • Recommendation - This is a POCO class that stores different metadata such as the RecipeDefinition and ProjectDefinition. There is 1:1 mapping between each recipe file and a recommendation object. Each recommendation object has a computed priority which determines its precedence.

  • DeploymentBundleDefinition - This is a POCO class that serves as the deserialized model for all DeploymentBundleDefinitions

  • OptionSettingItem - This is a POCO class that serves as the deserialized model for option settings found inside deployment recipes. These settings can be tweaked by the user to customize their deployment. This is defined as a partial class and the rest of its functionality is specified inside OptionSettingItem.ValueOverride

  • ValidatorFactory - The deployment tool performs input validation to guard against invalid input. These validators are specified inside the recipe files and can either be a recipe-level validator or an optionSetting-level validator. The ValidatorFactory is responsible for invoking the correct validator depending on the option setting being configured.

  • Exceptions - Declares all exceptions that are thrown by the AWS.Deploy.Common component. It also specifies the error codes that are associated with all exceptions thrown by the deployment tool (Note - The error codes are only bundled with exceptions that implement DeployToolException abstract class. These exceptions are caused by a user error and can be remedied by the user based on the error message thrown.)

  • AWS.Deploy.CLI.Common.UnitTests - Contains unit tests for this component.

AWS.Deploy.DockerEngine

This component contains all the logic for dealing with Docker. Some of its responsibilities are outlined below:

AWS.Deploy.Orchestration

This component serves as the main workhorse for the deployment tooling and it contains the most number of logical pieces.

Key Components

  • Orchestrator - It holds various dependencies required by the deployment tool and its design is aligned with the composition over inheritance philosophy.

  • OrchestratorSession - This is a POCO class that holds the user’s AWS credentials, the deployment region, AWS account ID and metadata about the user’s .NET project.

  • DeploymentCommandFactory - The deployment tool supports different deployment types (CDK based, existing Beanstalk environment, Pushing to ECR). Each type has its own deployment command and this mapping is stored inside the DeploymentCommandFactory.

  • IOrchestratorInteractiveService - This interface defines the logging service for the deployment tool.

  • SystemCapabilityEvaluator - Verifies that pre-requisties such as Docker and Node.js (required for CDK) are installed on the user’s system

  • RecommendationEngine - This is responsible for parsing the recipe files into a Recommendation object. It also computes the priority by running the recommendation rules against the customer’s .NET project

  • RecipeHandler - It contains methods to parse recipe files, locate custom (user defined) recipes and run recipe level validators

  • OptionSettingHandler - It contains methods to interact with option settings. Some of its functionality includes modifying the value, retrieving the current value and running option setting validators.

  • DeploymentSettingsHandler - Users can create their own deployment settings file that specifies a list of option settings and their values (See here for an example). The user can invoke dotnet aws deploy --apply <SETTINGS-FILE-PATH> --silent which applies the option settings values, runs all validators and kicks off a deployment without any user prompts. DeploymentSettingsHandler is responsible for parsing the settings file and applying the option setting values.

  • AWSResourceQueryer - Contains methods to query resources from different AWS services.

  • DeploymentBundleHandler - All recipes have a DeploymentBundle property that specifies how to package the user’s .NET project for deployment. DeploymentBundleHandler is reponsible for creating the appropriate deployment bundle

  • DeployedApplicationQueryer - It contains the functionality to retrieve the list of previously deployed applications and can also determine if an existing cloud application can be redeployed using the current set of recommendations.

  • CdkProjectHandler - Contains all the logic to interact with CDK.

  • CdkAppSettingsSerializer - It writes all the deployment settings into the appsettings.json file. This file is then deserialized into IRecipeProps and passed to the CDK templates.

  • Exceptions.cs - Declares all exceptions that are thrown by the AWS.Deploy.Orchestration component

  • AWS.Deploy.Orchestration.UnitTests - Contains unit tests for this component

AWS.Deploy.Constants

This is a shared project and contains various constants used throughout the codebase

AWS.Deploy.CLI.IntegrationTests

This contains the integration test suite

Server Mode

To support IDEs using the AWS .NET Deploy tool the CLI can be launched in server mode. This will run the CLI as a server that exposes an API IDEs will be able to interact with to perform deployment activities. When the server mode is started the deploy tool will act as an ASP.NET Core application. Server mode will keep all of the deployment logic and rules inside the deploy tool CLI. IDEs are treated as frontends rendering the information that comes from the deploy tool and passing any of the information the user has specified into the deploy tool to validate and persist.

Debugging the .NET Deployment Tool via Server Mode

  1. Install the AWS Toolkit for Visual Studio
  2. Open the following file in a text editor - %localappdata%\AWSToolkit\PublishSettings.json
  3. Under the DeployServer parent, add a new property AlternateCliPath that points to the AWS.Deploy.CLI executable. This instruct the Toolkit to launch the deploy tool from a custom location.

Example

{
   "DeployServer":{
      "AlternateCliPath":"C:\\code\\aws-dotnet-deploy\\src\\AWS.Deploy.CLI\\bin\\Release\\net6.0\\AWS.Deploy.CLI.exe",
      "PortRange":{
         "Start":10000,
         "End":10100
      }
   }
}

Follow these steps to attach a debugger:

  1. Launch a new Visual Studio window, and begin deploying a test project to AWS.
  2. In another Visual Studio window with Deploy Tool solution open, select Debug > Attach to Process then choose the AWS.Deploy.CLI.exe process that was started by the previous step.

Key Components

Build and Test Documentation

Install Material for MkDocs

Material for MkDocs is a theme for MkDocs, a static site generator geared towards (technical) project documentation. If you're familiar with Python, you can install Material for MkDocs with pip, the Python package manager.

pip install mkdocs-material

For, other installation options see here

Deploying to a Local Server

MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it.

From the root of the project repository, run the following command:

mkdocs serve

Paste the link to the local server on a web browser to look at the documentation.

The dev-server also supports auto-reloading, and will rebuild your documentation whenever anything in the configuration file, documentation directory, or theme directory changes.