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
AWS.Deploy.slnin Visual Studio.
- Ensure that
src/AWS.Deloy.CLIis set as the start up project.
- Go to
AWS.Deploy.CLI debug propertiesby clicking the following drop down
- Add a new launch profile called
- 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
- Select the
AWS.Deploy.CLIlaunch 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.
The .NET deployment tool comprises of various top level components.
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.
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
Exceptions - Declares all exceptions that are thrown by the AWS.Deploy.CLI component
AWS.Deploy.CLI.UnitTests - Contains unit tests for this component
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
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.
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 publishis 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.
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.
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
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
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.
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
DeployToolExceptionabstract 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.
This component contains all the logic for dealing with Docker. Some of its responsibilities are outlined below:
Generating a Dockerfile if the user’s project does not contain one. Note - a Dockerfile is only generated when deploying via a container-based recommendation such as ASP.NETAppAppRunner.recipe or ASP.NETAppECSFargate.recipe
Determining the Docker execution directory. It serves as the working directory for the
docker buildcommand and all relative paths in the Dockerfile are resolved from this directory.
This component serves as the main workhorse for the deployment tooling and it contains the most number of logical pieces.
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> --silentwhich 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.
Exceptions.cs - Declares all exceptions that are thrown by the AWS.Deploy.Orchestration component
AWS.Deploy.Orchestration.UnitTests - Contains unit tests for this component
This is a shared project and contains various constants used throughout the codebase
This contains the integration test suite
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
- Install the AWS Toolkit for Visual Studio
- Open the following file in a text editor -
- Under the
DeployServerparent, add a new property
AlternateCliPaththat points to the
AWS.Deploy.CLIexecutable. This instruct the Toolkit to launch the deploy tool from a custom location.
Follow these steps to attach a debugger:
- Launch a new Visual Studio window, and begin deploying a test project to AWS.
- In another Visual Studio window with Deploy Tool solution open, select Debug > Attach to Process then choose the
AWS.Deploy.CLI.exeprocess that was started by the previous step.
AWS.Deploy.CLI.ServerMode - It contains various Swagger based API controllers and POCO models that govern the REST API behaviour
AWS.Deploy.ServerMode.ClientGenerator - This ingests the API specification file (
swagger.json) to generate the REST API client.
AWS.Deploy.ServerMode.Client - This is the actual REST API client used by the frontend (VS Toolkit) to interact with the deployment tool CLI.
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:
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.