AWS .NET Modernization Tools Porting Assistant (PA) for .NET, AWS App2Container (A2C), AWS Toolkit for .NET Refactoring (TR), and AWS Microservice Extractor (ME) for .NET is no longer open to new customers. If you would like to use the service, sign up prior to November 7, 2025. Alternatively use [AWS Transform](https://aws.amazon.com/transform/), which is an agentic AI service developed to accelerate enterprise modernization of .NET. # Setting up for testing on AWS The sections below contain detailed descriptions of the configuration, roles, and permissions that are required to run a test deployment on AWS with Toolkit for .NET Refactoring. **Topics** + [Prerequisites for testing on AWS](test-prerequisites.md) + [AWS roles and managed policies for Toolkit for .NET Refactoring test deployment](roles-and-policies.md) + [Active Directory setup](ad-setup.md) # Prerequisites for testing on AWS Verify the prerequisites below before you test your application on AWS. **Topics** + [S3 bucket](#s3-prerequisite) + [VPC requirements](#vpc-prerequisites) + [Application listener ports](#port-prerequisite) + [HTTPS requirements](#https-prerequisites) + [Linux compatibility requirements](#linux-compatibility) + [AWS Identity and Access Management (IAM) overview](#dotnet-refactoring-iam-overview) ## S3 bucket You must have an S3 bucket in the AWS Region where you want to run the test deployment. You can create a S3 bucket using Amazon Simple Storage Service (Amazon S3). Toolkit for .NET Refactoring supports the following Regions: + US East (Ohio) – `us-east-2` + Europe (London) – `eu-west-2` Toolkit for .NET Refactoring uses the S3 bucket to do the following: + Prepare the data for the container image build. + Transfer the application files to the Amazon ECS task. ## VPC requirements When you create a test deployment, the default setting is to create a new virtual private cloud (VPC) in your AWS account. For more information, see [Virtual private clouds (VPC)](https://docs.aws.amazon.com/vpc/latest/userguide/configure-your-vpc.html) in the *Amazon Virtual Private Cloud User Guide*. Alternatively, you can choose to use an existing VPC. If you use an existing VPC, it must satisfy the following requirements: + It must have two public subnets in different Availability Zones. For information about Availability Zones, see [Regions and Zones](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-availability-zones) in the *Amazon Elastic Compute Cloud User Guide.* + It must have an internet gateway. For information about internet gateways, see [Connect to the internet using an internet gateway](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Internet_Gateway.html) in the *Amazon VPC User Guide*. It must have a routing table that connects the internet gateway to the subnets. This means that the subnet is public. For information about subnets, see [VPC with public and private subnets (NAT)](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Scenario2.html) in the *Amazon VPC User Guide*. ## Application listener ports The application that you want to test on AWS must listen on the following port: ``` 0.0.0.0:port ``` Note that the application should not listen on `localhost:port` or `127.0.0.1:port`. This is because when your application is deployed to the cloud, you will connect to the application using a public IP address. **Kestrel server** When your application is ported from .NET to .NET Core, the Kestrel server, which is part of the .NET Core framework, is used as a default web server. The default endpoints (`http://localhost:5000` and `https://localhost:5001`) will not work for the AWS connection. You must explicitly set the Kestrel endpoints. For information about how to set the Kestrel endpoints, see the Microsoft [Configure endpoints for the ASP.NET Core Kestrel web server](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel/endpoints?view=aspnetcore-6.0) documentation. Note that the documentation uses `http://localhost:5000` as an example but you must use `http://0.0.0.0:5000` or `https://0.0.0.0:5001`. ## HTTPS requirements If the application supports HTTPS, the certificate and private key are required and must be included in the application artifacts. ## Linux compatibility requirements The application that you port to .NET Core will run on a Linux OS, which can cause errors if you are porting your application from a Windows OS and you are unaware of the differences between the operating systems. In particular, the Linux file system is case-sensitive and the Windows file system is not. Therefore, the paths and names of the files that your application uses must be consistent. For example, if you have a file named `Dinosaur.cfg` and you refer to it as `dinosaur.cfg` in your code, you will receive an error. You must refer to the file as `Dinosaur.cfg` in your code. ## AWS Identity and Access Management (IAM) overview If you are using a license included Visual Studio Amazon Machine Images (AMIs) on Amazon EC2, you can use the caller role (`refactoringtoolkit-RefactoringToolkitCallerRole`) without providing user credentials or editing configuration files. In this case, you do not need to follow the steps in the [AWS Identity and Access Management](dotnet-refactoring-iam.md) section of this guide. For more information, see [Install Toolkit for .NET Refactoring](dotnet-refactoring-installation.md) in this guide. If you are not using a license included Visual Studio AMI on Amazon EC2 or you prefer to create a user and assign roles to the user, see [AWS Identity and Access Management](dotnet-refactoring-iam.md) in the *Security* section of this guide to view the IAM prerequisites. Follow the steps to create the user, create the access keys, and configure your AWS profile. # AWS roles and managed policies for Toolkit for .NET Refactoring test deployment To test your application on AWS using Toolkit for .NET Refactoring, you must have the required permissions. Permissions are required for the following tasks: + Containerization of your .NET Core application. + Deployment of the ported application to AWS Fargate. The [AWS managed policies](security-iam-awsmanpol.md) page contains detailed information about the managed policies that you can use with Toolkit for .NET Refactoring. **Topics** + [Manually create roles and policies](#dotnet-refactoring-roles-policies-manual) + [Create roles and policies with CloudFormation](#cloudformation-create-roles-policies) + [AWS KMS key policy](#dotnet-refactoring-roles-policies-manual-kms) ## Manually create roles and policies You can manually create the roles and policies required for Toolkit for .NET Refactoring. ### Roles and policies for Toolkit for .NET Refactoring Use the AWS Management Console to create roles and policies to use Toolkit for .NET Refactoring. 1. Navigate to the [AWS Management Console](https://console.aws.amazon.com/console) and search for **IAM**. 1. From the IAM dashboard, create a policy named `refactoringtoolkit-EnablePassRoleAccess` and include the following JSON statement: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "iam:PassRole" ], "Resource": [ "arn:aws:iam::048661490019:role/refactoringtoolkit-CodeBuildServiceRole", "arn:aws:iam::048661490019:role/refactoringtoolkit-ECSTaskExecutionRole", "arn:aws:iam::048661490019:role/refactoringtoolkit-ECSTaskRole" ], "Effect": "Allow" } ] } ``` ------ 1. Create a policy named `refactoringtoolkit-EnableTelemetryAccess` and include the following JSON statement: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "execute-api:invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:492443789615:3dmmp07yx6/*", "arn:aws:execute-api:us-east-1:547614552430:8q2itpfg51/*", "arn:aws:execute-api:us-east-1:226975336241:m43z210z43/*", "arn:aws:execute-api:us-east-1:651331843990:lqi4wznpac/*", "arn:aws:execute-api:us-west-2:930729463547:ml5fgmwiy3/*" ], "Effect": "Allow", "Sid": "EnCorePermission" } ] } ``` ------ 1. Create a role named `refactoringtoolkit-CodeBuildServiceRole` and add an inline policy called `CodeBuildServiceRolePolicy` that includes the following JSON statement: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:PutLogEvents" ], "Resource": "*", "Effect": "Allow", "Sid": "CloudWatchLogsPolicy" }, { "Action": [ "s3:GetObject", "s3:GetObjectVersion", "s3:ListBucket" ], "Resource": "*", "Effect": "Allow", "Sid": "S3GetObjectPolicy" }, { "Action": [ "s3:GetBucketAcl", "s3:GetBucketLocation" ], "Resource": "*", "Effect": "Allow", "Sid": "S3BucketIdentity" }, { "Action": [ "ecr:InitiateLayerUpload", "ecr:PutImage", "ecr:UploadLayerPart", "ecr:CompleteLayerUpload", "ecr:BatchCheckLayerAvailability", "ecr:GetDownloadUrlForLayer" ], "Resource": "*", "Effect": "Allow", "Sid": "ECRPushPolicy" }, { "Action": [ "ecr:GetAuthorizationToken" ], "Resource": "*", "Effect": "Allow", "Sid": "ECRAuthPolicy" } ] } ``` ------ 1. Create a role named `refactoringtoolkit-ECSTaskRole` and add the `AWSRefactoringToolkitSidecarPolicy` policy. 1. Create a role named `refactoringtoolkit-ECSTaskExecutionRole` and add the `AmazonECSTaskExecutionRolePolicy` policy. 1. Create a role named `refactoringtoolkit-RefactoringToolkitCallerRole` and add the `refactoringtoolkit-EnablePassRoleAccess`, `refactoringtoolkit-EnableTelemetryAccess`, and `AWSRefactoringToolkitFullAccess` policies. ## Create roles and policies with CloudFormation Use the CloudFormation template to create roles and policies that you will use for Toolkit for .NET Refactoring. 1. Use the following command to download the CloudFormation template. ``` aws s3 cp s3://aws.portingassistant.dotnet.download/ide.extension.role.creation/aws-refactoringtoolkit-iam-roles.yaml . ``` 1. Create the required IAM roles in your account. This step uses the `aws-refactoringtoolkit-iam-roles.yaml` file that you downloaded in the previous step. The user that executes the command to create the roles must have the following permissions: + `iam:CreateRole` + `iam:CreatePolicy` + `iam:AttachRolePolicy` To create the roles, run the following AWS CLI command: ``` aws cloudformation deploy --stack-name refactoringtoolkit --template-file aws-refactoringtoolkit-iam-roles.yaml --capabilities CAPABILITY_NAMED_IAM ``` The following sections provide detailed information about the roles that are created by the CloudFormation template. **Topics** + [Role and policy for the user calling the API](#user-permissions) + [Assign a user to the role created by the CloudFormation template](#attach-policies) + [Attach the policies to the user](#attach-policies-to-user) + [Toolkit for .Net Refactoring caller role](#caller-role) + [AWS CodeBuild role](#code-build) + [Amazon ECS task execution role](#ecs-task-execution) + [Amazon ECS task role](#ecs-task-role) ### Role and policy for the user calling the API The CloudFormation template creates the following policy and role: + Policy – `refactoringtoolkit-EnablePassRoleAccess` + Policy – `refactoringtoolkit-EnableTelemetryAccess` + Role – `refactoringtoolkit-RefactoringToolkitCallerRole` ### Assign a user to the role created by the CloudFormation template The role that was created by the CloudFormation template contains the policies required to use Toolkit for .NET Refactoring. You can assign a user to this role. To enable a user to assume the role, you need the Amazon Resource Name (ARN) of the user. For more information, see [Amazon Resource Names (ARNs)](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html) in the *AWS General Reference*. To allow the user to be assigned a role, you must edit the trust relationship for the `refactoringtoolkit-RefactoringToolkitCallerRole` role. For more information, see [Granting a user permissions to switch roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_permissions-to-switch.html) in the *AWS Identity and Access Management User Guide*. Edit the trust relationship to add the principal with the ARN of the user: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:user/John", "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } } ``` ------ **Note** By default, this role has a trust relationship that allows the Amazon EC2 instance to use the role. If you delete the `"Service": "ec2.amazonaws.com"` line, the instance profile will no longer work. #### Create a new named profile that uses a role **Important** The `~/.aws/config` file contains a section for your user profile. In this step, do not edit the section for your user profile. Instead, you will create a new role profile section. Add the text below to the `~/.aws/config` file to create the `refactoringtoolkit` profile. You can substitute any string for ``, such as `refactoringtoolkit_profile`. ``` [] role_arn = arn:aws:iam:::role/refactoringtoolkit-RefactoringToolkitCallerRole source_profile = ``` For information about how to add a role to a profile, see [Using an IAM role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html) in the *AWS CLI User Guide for Version 2*. For information about credentials, see [Shared config and credentials files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) in the *AWS SDKs and Tools Reference Guide*. ### Attach the policies to the user Alternatively, you can attach the policies to a user rather than a role. If you want to do this, you can attach the following policies directly to the user: + `AWSRefactoringToolkitFullAccess` + `refactoringtoolkit-EnableTelemetryAccess` + `refactoringtoolkit-EnablePassRoleAccess` To provide access, add permissions to your users, groups, or roles: + Users and groups in AWS IAM Identity Center: Create a permission set. Follow the instructions in [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) in the *AWS IAM Identity Center User Guide*. + Users managed in IAM through an identity provider: Create a role for identity federation. Follow the instructions in [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) in the *IAM User Guide*. + IAM users: + Create a role that your user can assume. Follow the instructions in [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) in the *IAM User Guide*. + (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in [Adding permissions to a user (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) in the *IAM User Guide*. ### Toolkit for .Net Refactoring caller role The CloudFormation template creates the following caller role: ``` refactoringtoolkit-RefactoringToolkitCallerRole ``` This role grants Toolkit for .NET Refactoring permissions to do the following: + Call the required APIs in AWS. + Upload application artifacts and download the resulting artifacts from S3. + Build the application into a container image using AWS CodeBuild and store and retrieve the images in Amazon Elastic Container Registry (Amazon ECR). + Deploy the application to container services on AWS, such as Amazon Elastic Container Service (Amazon ECS). + Optionally, create Amazon VPC resources. + Optionally, connect to existing infrastructure, such as Directory Service. The following policies are attached to the role: + `refactoringtoolkit-EnablePassRoleAccess` + `refactoringtoolkit-EnableTelemetryAccess` + `AWSRefactoringToolkitFullAccess` To use this role, you must do one of the following: + Add it to a named profile in the `~/.aws/config` file. For more information, see [Assign a user to the role created by the CloudFormation template](#attach-policies) in this guide. + Use it with an Amazon EC2 instance profile. For more information, see [Install Toolkit for .NET Refactoring](dotnet-refactoring-installation.md) in this guide. ### AWS CodeBuild role The CloudFormation template creates the following CodeBuild role: ``` refactoringtoolkit-CodeBuildServiceRole ``` AWS CodeBuild uses this role to download application artifacts from S3, build the application container, push to Amazon Elastic Container Registry (Amazon ECR), and create logs in Amazon CloudWatch. The following policy is attached to the role: ``` CodeBuildServiceRolePolicy ``` Toolkit for .NET Refactoring will automatically use a role with this name. ### Amazon ECS task execution role The CloudFormation template creates the following Amazon ECS task execution role: ``` refactoringtoolkit-ECSTaskExecutionRole ``` This role allows Amazon ECS to pull the application Docker image from Amazon ECR and upload logs. The following policies are attached to the role: + `AmazonECSTaskExecutionRolePolicy` + `ECSSecretsPolicy` Toolkit for .NET Refactoring will automatically use a role with this name. For more information, see [Amazon ECS task execution IAM role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_execution_IAM_role.html) in the *Amazon ECS User Guide*. ### Amazon ECS task role The CloudFormation template creates the following Amazon ECS task role: ``` refactoringtoolkit-ECSTaskRole ``` This role allows your application to authenticate with other AWS services. It is similar to the IAM roles that are used as instance profiles for Amazon EC2 instances. This role is required for test deployment to allow the sidecar to sync files from S3 and for Active Directory to retrieve credentials from AWS Secrets Manager. The following policy is attached to the role: ``` AWSRefactoringToolkitSidecarPolicy ``` Toolkit for .NET Refactoring will automatically use a role with this name. For more information, see [IAM roles for tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) in the *Amazon ECS User Guide*. ## AWS KMS key policy To use Toolkit for .NET Refactoring with an AWS KMS key to encrypt AWS resources, the KMS key policy must include the following statement: ``` { "Effect": "Allow", "Principal": { "Service": "application-transformation.amazonaws.com" }, "Action": [ "kms:Decrypt", "kms:DescribeKey", "kms:GenerateDataKey" ], "Resource": "kmsKeyArn" } ``` You can create a new KMS key with the previously mentioned policy, or add it to an existing KMS key. For more information, see [Creating a key policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-overview.html) and [Changing a key policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying.html) in the *AWS Key Management Service User Guide*. # Active Directory setup The application that you use for the test deployment can use Microsoft Active Directory authentication against its dependencies, such as a Microsoft SQL Server database that is joined into an Active Directory domain. Note that this allows authentication of the application in the test deployment. It does not provide single sign-on for the incoming on-premises user connections with Windows Authentication tokens in HTTP headers. For more information, see [Join an Amazon EC2 instance to your AWS Managed Microsoft AD directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_join_instance.html) in the *AWS Directory Service Administration Guide*. **Topics** + [Create a directory](#ad-directory) + [Create a user](#ad-user) + [Create a secret](#ad-secret) + [Allow the task role to read the secret](#ad-task-role) ## Create a directory Create a directory in the Directory Service using the same VPC that you will use for test deployment. If you use Active Directory, you must use the **Select an Amazon VPC** option when you create the test deployment. For more information, see [Create your AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started.html) in the *AWS Directory Service Administration Guide*. Verify that the directory meets the following requirements: + The inbound rules of the security group used by your directory must allow incoming connections from the same VPC. For more information, see [Understand your directory’s AWS security group configuration](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_best_practices.html#understandsecuritygroup) in the *AWS Directory Service Administration Guide*. + The VPC must have a DHCP options set that lists both of the IP addresses of the directory as DNS servers. For more information, see [Create a DHCP options set](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_best_practices.html#bp_create_dhcp_options_set) in the *AWS Directory Service Administration Guide*. ## Create a user Create a user in the directory. Remember the sign-in credentials. ## Create a secret Create a secret to pass the username and password to your application. Create the secret with the user credentials in the AWS Secrets Manager before you run the test deployment on AWS. The user credentials must contain the following fields: + `Username` – The domain in the `Username` value must be uppercase: `user@AD_DOMAIN` + `Password` You can also use the AWS Secrets Manager in the AWS Management Console to create the secret. Create a secret and add values in the following way: ``` Key: Username, value: user@AD_DOMAIN, Key: Password, value: password ``` You can use the JSON format option in the secret as: ``` { "Username": "user@AD_DOMAIN", "Password": "password" } ``` You can also use the AWS CLI to create the secret. For more information, see [https://awscli.amazonaws.com/v2/documentation/api/2.0.33/reference/secretsmanager/create-secret.html](https://awscli.amazonaws.com/v2/documentation/api/2.0.33/reference/secretsmanager/create-secret.html) in the *AWS CLI Command Reference*. If you use AWS CLI, use the `--secret-string` parameter as follows: ``` ‘{"Username":"user@AD_DOMAIN.COM","Password":"password"}’ ``` The single quotes that enclose the JSON value allow you to pass the double quotes unchanged. Remember the ARN of the secret for later use. ## Allow the task role to read the secret In the AWS Secrets Manager in the AWS Management Console, open the secret that you created and select the **Resource permissions** tab in the information page of the secret. Add the policy below to the secret. The policy contains the following ARNs: + The ARN of the [Amazon ECS task role](roles-and-policies.md#ecs-task-role) that you created with the CloudFormation template. + The ARN of the secret that you just created. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement" : [ { "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::123456789012:role/my-ecs-task-role" }, "Action": "secretsmanager:GetSecretValue", "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret-XyZ9Qw" } ] } ``` ------