# Modernizing your .NET code by using the AWS Transform web application
AWS Transform for .NET is a new generative AI-powered agent designed to modernize legacy .NET applications. You can modernize your legacy .NET code by using the AWS Transform web application or the Visual Studio AWS Toolkit extension.
To modernize your .NET code using the AWS Transform web application, navigate to the web application follow these detailed steps:
1. [Creating the AWS Transform .NET job plan](dotnet-creating-job-plan.md)
1. [Creating a source code repository connector](dotnet-creating-repo-connector.md)
1. [Confirming your repositories to prepare for transformation](dotnet-confirming-repos.md)
1. [Resolving package dependencies to prepare for transformation](dotnet-resolving-dependencies.md)
1. [Reviewing your plan to prepare for transformation](dotnet-reviewing-plan.md)
1. [Transforming your .NET code](dotnet-transforming-code.md)
# Creating the AWS Transform .NET job plan
After you create your workspace, on the **Jobs** tab, select **Create job**. Then follow the prompts from AWS Transform in the chat pane using natural language. These are the typical steps for creating a .NET modernization job.
1. AWS Transform will ask you which type of transformation job you would like to create. In the chat, enter *.NET modernization*.
1. AWS Transform will suggest a job name and ask you if you want to change the job name. If you would like to change the job name, tell AWS Transform in natural language, for example, *change the job name to ExampleCorpDotNet1*. Otherwise, in the chat, you can accept the suggested job name. After you accept the job name, AWS Transform notifies you in the chat window that it is creating the job.
1. AWS Transform creates the transformation job.
## Components of the AWS Transform .NET job plan
The AWS Transform .NET job display has 5 tabs which you select from the vertical icons on the far left: **Tasks**, **Dashboard**, **Approvals**, **Artifacts**, and **Worklog**. Each tab has a left pane and a center chat pane. A right collaboration pane may appear at times to show additional details and to request human input.
### Tasks (Job Plan)
This tab displays your job plan in the left pane. A .NET job has 5 steps:
1. *Get resources to be transformed*: In this phase, you create a connector to your code repository using AWS CodeConnections. Depending on your repository permissions, an admin of the code repository may need to approve the connector and give AWS Transform access to the repository.
1. *Discover resources for transformation*: In this phase, AWS Transform discovers repositories in source control, and you select some or all of them for assessment.
1. *Assess code for transformation*: Selected repositories are assessed, and you can view assessment reports.
1. *Prepare for transformation*: In this phase, AWS Transform notifies you if any dependencies are missing from your repositories. You can upload the missing dependencies or ignore them. If you are not an admin for the repo, an admin may need to approve the final transformation plan.
1. *Transform*: In this phase, AWS Transform transforms your repo and provides you the ongoing status during the transformation until it's completed. You can review transformation reports to understand what was changed and why.
You can see the status for each step:
+ Not started
+ Await user input
+ In Progress
+ Completed
### Dashboard
The **Dashboard** tab provides a high level summary of the transformation. It displays metrics for the number of jobs transformed, transformation applied, and estimated time to complete the transformation. Below the dashboard is a table of repositories and their status - In-progress, Failed, or Success.
### Approvals
Approval requests for the job are displayed and completed on this tab.
### Artifacts
Jjob-related artifacts are uploaded or downloaded from this tab.
### Worklog
AWS Transform logs its actions in the **Worklog** tab. The **Worklog** provides a detailed log of the actions AWS Transform takes, along with human input requests, and your responses to those requests.
# Creating a source code repository connector
After [Creating the AWS Transform .NET job plan](dotnet-creating-job-plan.md), on the **Tasks** tab, the left pane of the AWS Transform window lists the phases of the transformation job. The first phase is *Get resources to be transformed*. In this phase, you can *Invite collaborators* and *Connect a source code repository*. The right pane of the AWS Transform window is where you specify the details.
Each transformation job is required to have only one source code repository connector. The AWS Transform agent uses this connector to download your .NET codebase from GitHub, GitLab, or Bitbucket by using [AWS CodeConnections](https://docs.aws.amazon.com/dtconsole/latest/userguide/welcome-connections.html). You must set up AWS CodeConnections in the same Region as your AWS Transform job. Alternatively, you can [Connect to source code in Amazon S3](https://docs.aws.amazon.com/transform/latest/userguide/dotnet-connect-source-code-s3.html) instead of a source code repository.
**Note**
If you have an existing source code repository connector, AWS Transform will notify you. Select **Use existing connector** to use this connector. If you do not wish to use the existing connector, see [Deleting an existing connector](#deleting-existing-connector) before [Adding a new connector](#adding-new-connector). You can only have one source repository connector per job.
## Adding a new connector
To create a new source code repository connector:
1. Enter the AWS account number that you would like to use for the AWS CodeConnections connector.
1. If you have not set up AWS CodeConnections for the same AWS account, [Set up AWS CodeConnections](https://docs.aws.amazon.com/dtconsole/latest/userguide/setting-up-connections.html).
1. Use the [AWS Developer Tools Console](https://console.aws.amazon.com/codesuite/settings/connections) to create a connection to your [Bitbucket](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-bitbucket.html), [GitHub](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html), [GitHub Enterprise Server](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-gheserver.html), [GitLab](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-gitlab.html), or [AzureDevOps](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-azure.html) repository.
1. Copy the Amazon Resource Name (ARN) of the connection you created.
1. Return to AWS Transform, and paste the ARN of the connection you created.
1. Enter a name for the connector.
**Note**
Do not enter personal information as part of the connector name.
1. Select **Initiate connector creation.**
1. AWS Transform makes the request to create a connector for AWS account you entered, in the same Region as the current transformation job, and notifies you that an approval request is ready to be approved by your AWS administrator in the AWS Management Console. Select **Copy the verification link**.
1. If you are the AWS administrator, sign into the AWS account and go to the verification link to approve the connection request. If you are not the AWS administrator, provide the verification link to your AWS administrator.
1. After the AWS administrator approves the connector request, select **Finalize connector** to complete the connector creation process. Should you wish to use a different connector, select **Restart**, to restart the connector creation process.
The Collaboration tab also includes details about your connector, which include:
+ Status -- Approved or Pending approval
+ AWS account ID
+ AWS Region
+ Connection ARN
## Deleting an existing connector
**Note**
If you have an existing source code repository connector, AWS Transform will notify you. Select either **Use existing connector** or **Delete and create a new connector**.
If you choose to delete an existing source code repository connect, AWS Transform will warn you before actually deleting the connector.
1. You can delete an existing connector a couple of ways:
1. If AWS Transform prompts you to, you can select **Delete and create a new connector**.
1. You can also select **restart** in the prompt, **To modify this connector, you must restart**.
1. AWS Transform warns you that restarting will delete the connector. To delete the connector, select **Restart** again.
1. AWS Transform warns you again that deleting the connector will remove the connection to your third party repository, such as Bitbucket, GitHub, and GitLab. Also, any AWS Transform jobs that are using this connector will fail if the connector is deleted. To confirm deletion, type *delete* and select **Delete**.
1. To add a new source code repository connector, see [Adding a new connector](#adding-new-connector).
# Connect to source code in Amazon S3
You can connect AWS Transform to source code in Amazon S3 as an alternative to [connecting a source code repo](https://docs.aws.amazon.com/transform/latest/userguide/dotnet-creating-repo-connector.html).
## S3 bucket organization
Original source code and transformed code are stored in a common S3 bucket, organized as shown below. You must set up your S3 bucket in the same region as your AWS Transform job. Upload your source code to the bucket as a zip file at root level. The zip file must contain a top level folder for each repository.
During transformation, AWS Transform creates a transform-output folder, and stores the transformation results in that folder. Transformation creates a zip file named *transformed-code.zip* containing the transformed code. This includes a code differences report file name diff.txt that highlights file changes at a project level.
```
/
├── source-code.zip
├── repo 1
├── repo 2
├── ......
├── repo n
└── transform-output/
├── transformed-code.zip
```
## Adding a new S3 Connector
To create a new S3 source code repository connector:
1. In the AWS console, create an S3 bucket.
1. Upload your source code as a zip file to the S3 bucket.
1. In the AWS Transform web app, start a .NET transformation job. In the **Connect a source code repository** step, select **Connect your source code in S3 bucket** and choose **Save**.
1. On the next page, enter your S3 bucket details and choose **Submit**.
1. Connector name
1. AWS Account ID
1. S3 Bucket Arn
1. S3 Bucket Encryption Key (optional)
1. Approve the connector:
1. On the next page, copy the verification link.
1. Have an approver browse to the link to reach the AWS Transform connector creation request page.
1. Choose to create a new role or use an existing role.
1. After reviewing the request, choose **Save** and **Approve** to approve it.
1. Specify the S3 zip file location:
1. In the AWS Transform web app, wait for status to show **Approved**.
1. On the **Specify asset location** page, enter an S3 URL for the code zip file in the format `s3://bucket-name/zip-file-name` and choose **Send to AWS Transform**.
1. The job proceeds to the **Discovery** step to continue the transformation.
## Deleting an S3 Connector
To delete an existing S3 connector:
1. In the AWS Transform web app, select **Manage connectors** at the top right.
1. In the **Manage connectors** window, select the connector.
1. Choose **Delete**.
# Confirming your repositories to prepare for transformation
After [Creating a source code repository connector](dotnet-creating-repo-connector.md), confirm your repositories as the first step of preparing for transformation. You can:
+ Review and change [Default Settings](#default-settings) that affect the plan contents.
+ Review discovered repositories and select which ones to assess for transformation.
+ Review the [ repository assessment report](https://docs.aws.amazon.com/transform/latest/userguide/dotnet-confirming-repos.html#review-repository-summary) and chat with AWS Transform about its contents.
+ [Use the plan generated by AWS Transform](dotnet-web-app.md#use-generated-plan).
+ [Customize the transformation plan](dotnet-web-app.md#customize-plan) using the web app or by downloading a JSON file, modifying it, and uploading it to AWS Transform.
## Default Settings
In the **Job details** section of the **Collaboration** tab, you can set the following:
On the Tasks tab, in the Prepare for transformation - Confirm the repositories to transform step, you can set the following:
+ Set the target branch name where the transformed code is written to your repository.
+ Set the target .NET version:
+ **.NET 8**: transform all projects to .NET 8
+ **.NET 10**: transform all projects to .NET 10
+ You can update the default Job Settings, or leave them as-is. These include:
+ **Exclude .NET Standard projects from the transformation plan** This setting is selected by default. When selected, AWS Transform excludes any .NET Standard projects from the transformation plan. If you deselect this setting, .NET Standard projects will be transformed, which will make them no longer compatible with the .NET Framework.
+ **Check the NuGet sources and get .NET compatible package versions** Allow AWS Transform to search for and get .NET compatible package versions for the code that you would like to transform.
## Review the repository assessment report
The repository assessment report provides a tabular view of information about each repository detected by AWS Transform. This includes:
+ Repository Owner
+ Assessed Branch
+ No. of solutions
+ No. of projects
+ Total Lines of Code
+ Detected .NET Versions
+ Detected Project Types
+ No. of Private Nuget Dependencies
+ No. of Public Nuget Dependencies
+ Transformation Complexity
To download the file:
1. In your workspace, select the **Collaboration** tab.
1. In the **Choose repositories** pane, select **Download**, and choose **Download as HTML** or **Download as JSON**
### Chat about the repository summary report
Your repository summary may be very long. Use chat to better understand its contents. Your report is available for chat when you see this message on the **Worklog** tab: *Assessment report is now available in chat for queries*. To open the chat click the purple hexagonal icon in the lower right corner of the web console. Here are some example prompts:
+ List all repositories discovered or assessed.
+ How many .NET 6 projects were discovered in the assessment?
+ Which projects have the highest complexity?
## Use the plan generated by AWS Transform
You can choose to use the AWS Transform plan created from discovering repositories with a higher probability of transformation success, which includes the last modified, root, and cross-dependent repositories.
AWS Transform lists some high level details about the transformation plan, which include:
+ *Total number of repositories discovered* This number of legacy .NET repositories that AWS Transform discovered using your source code repository connector. AWS Transform can scan a maximum of 1,000 repositories in each job. If you have more repositories to scan or transform, you can create multiple transformation jobs.
+ *Selected repositories* The number of legacy .NET repositories that AWS Transform selected for transformation.
+ *Selected dependencies* The number of dependencies that the selected repositories require, which AWS Transform auto-detected and added to the transformation plan.
The *Selected repositories* table lists the selected repositories. You can search repositories by name, navigate to additional pages of repositories, and download a JSON formatted file that lists the selected repositories and their dependencies. You can make any changes in this view.
The *Selected repositories* table lists the following details about the repositories that AWS Transform selected for transformation:
+ Repository name
+ Source branch
+ Last modified date and time
+ Lines of code This allows you to see if you're approaching your quota limits. For more information, see [Quotas for AWS Transform](transform-limits.md).
+ Dependent repositories You can click on the number of dependent repositories to view more details about these dependencies.
If you are happy with the AWS Transform generated transformation plan, select **Confirm repositories**.
If you would like to make changes to the AWS Transform generated transformation plan, select [Customize the transformation plan](#customize-plan).
## Customize the transformation plan
If you choose not to [Use the plan generated by AWS Transform](#use-generated-plan), you can customize the list of repositories to transform using one of the following options:
1. Select repositories in the **Selected repositories** table.
1. When you add a repository to the plan, AWS Transform will select the repository's dependencies for you and automatically add them to the transformation plan.
1. You can also deselect repositories in the table.
1. Download the AWS Transform generated JSON list of repos and branches.
1. Select **Download** and then select **Download as JSON**.
1. Review and modify the JSON. You can remove repositories, or solutions within repositories, that you don't want to transform.
1. Upload the revised JSON by selecting **Upload customized plan**.
1. If the JSON uploads successfully, the **Selected repositories** table displays the selections you made.
1. You can select **Show dependent repos** to display the list of repositories that AWS Transform discovered are dependencies for the repositories you selected.
1. You can repeat these steps if needed. When you are satisfied with your customized plan, select **Confirm repositories**.
# Resolving package dependencies to prepare for transformation
After [Confirming your repositories to prepare for transformation](dotnet-confirming-repos.md), if AWS Transform finds missing package dependencies, you must complete this step. You can run a Windows PowerShell script to get the missing package dependencies from the same device as your Visual Studio development environment, or you can retrieve the missing packages manually. Then, upload the missing packages.
The Missing Package Dependencies can be updated in two ways:
+ **Resolve using Artifact Connector: ** Resolve by configuring an Artifact Repository (ADO NuGet Connector) through a dedicated Connect Artifact Repository HITL workflow, which is displayed when an Artifact Connector is not configured and packages are missing.
+ **Update missing package:** AWS Transform lists the missing packages in the Missing package dependencies table. You can search for a missing package by name in the search box. This table includes the following details about the missing packages:
+ Name
+ Associated repositories
+ Framework version status
+ Core version status
To resolve the missing package dependencies, [Upload the missing packages](#upload-missing-packages).
## Upload the missing packages
1. If you choose, you can download a Windows PowerShell helper script to retrieve the missing package dependencies from within your Visual Studio development environment. Or you can find the missing packages manually.
To use the Windows PowerShell script:
1. Select **Download Windows PowerShell script**.
1. Run the script locally with an active connection to the repositories that contain the missing package dependency files.
1. This script allows you to download the missing package dependencies to your local environment.
1. The script will create a single zip file for you to upload which includes all of the dependencies in one archive. You can also upload individual `.nupkg` or zip files for each dependency.
1. Select **Upload package files.**
1. In the **Upload dependency files** modal, select **Choose files** and browse to the location of the compressed missing package files on your device.
1. Select **Upload**.
1. AWS Transform validates the files you uploaded. During validation, you cannot make any updates. AWS Transform reports the validation status above the *Missing package dependencies* table.
1. AWS Transform also updates the status columns in the *Missing package dependencies* table from *Missing* to *Resolved*. If a package fails validation, its status becomes *Invalid*. For invalid files do the following:
1. In the *Missing package dependencies* table, select the invalid package using the check box.
1. Select **Remove uploaded file**.
1. This changes its status back to *Missing*.
1. After you have uploaded the missing packages and resolved the package dependencies, select **Proceed to review**.
If you select **Proceed to review** without resolving the missing package dependencies, AWS Transform asks if you would like to start the transformation job without the missing packages. If you select **Ignore the missing package dependencies**, AWS Transform will use assembly references to transform the code. Proceeding with this action can affect related resources.
## Folder Structure Requirements
For NuGet uploads AWS Transform requires either:
+ The `.nuspec` file to be placed at the root level for manually uploaded packages, or
+ Use of the provided PowerShell script to generate the correct structure
## Version matching requirements
+ Framework status: AWS Transform attempts to match the version of the dependency specified in the `.csproj` file (source code) with the version of the uploaded dependency. An exact match results in a **Success** status.
+ Core status: AWS Transform expects a core version specification in the dependencies section of the uploaded `.nuspec` file. If one is found then the core status is **Success**.
**Example format:**
```
```
Common versions include:
+ .NET 5.0 (net5.0)
+ .NET 6.0 (net6.0)
+ .NET 7.0 (net7.0)
+ .NET 8.0 (net8.0)
# Reviewing your plan to prepare for transformation
After [Confirming your repositories to prepare for transformation](dotnet-confirming-repos.md), and [Resolving package dependencies to prepare for transformation](dotnet-resolving-dependencies.md), the AWS account administrator must review the transformation plan and approve it in AWS Transform.
AWS Transform displays the job's list of repositories, dependent repositories, and dependent packages that were selected for transformation.
## Reviewing the transformation plan
AWS Transform displays the job's list of repositories, dependent repositories, and dependent packages that were selected for transformation.
**Note**
AWS Transform can transform a maximum of 100 dependencies and repositories per transformation plan.
1. If you are not the AWS account administrator, review the job plan, and if you accept it, select **Send for approval**.
1. If you are the AWS account administrator, you must review the plan, and when ready, approve the plan to start the transformation. After you review the job plan, select either:
1. *Reject* If the job was created by a user who is not the AWS account administrator, we suggest you notify the job creator to restart the job.
1. *Approve and start transformation*.
The job review includes the following details:
1. *Job summary* This includes:
1. The target branch where AWS Transform will place the transformed code.
1. The target .NET version, .NET 8.0 or .NET 10.
1. The job settings:
1. Exclude .NET standard projects
1. Number of repositories selected for transformation
1. Number of dependent repositories
1. Number of private NuGet packages
1. Total lines of code for the job
1. *Repositories selected* These are the repositories selected for transformation. They must be either MVC, Web, Windows Communication Foundation (WCF), Console, class library, UI framework - Razor pages, or unit test packages. This table includes the following information:
1. Name
1. Source branch
1. Supported projects
1. Lines of code
1. Projects detected
1. Projects skipped
1. Dependencies detected
1. *Dependent repositories added* These are the dependent repositories added for transformation. They must be either MVC, Web, Windows Communication Foundation (WCF), Console, class library, UI framework - Razor pages, or unit test packages. This table includes the following information:
1. Name
1. Needed by
1. Source branch
1. Supported projects
1. Lines of code
1. Projects detected
1. Projects skipped
1. *Dependent packages* These are the dependent packages added for transformation. They must be either MVC, Web, Windows Communication Foundation (WCF), Console, class library, UI framework - Razor pages, or unit test packages. This table includes the following information:
1. Name
1. Associated repositories
1. Framework version status
1. Core version status
# Transforming your .NET code
After the AWS account administrator finishes [Reviewing your plan to prepare for transformation](dotnet-reviewing-plan.md), you can view the transformation progress on the *Dashboard* tab of your transformation job.
**Note**
In addition to transforming repositories and dependencies, AWS Transform can execute fully transformed (zero build errors) unit test projects. AWS Transform doesn't have access to unit test results prior to the transformation and can only share post-transformation results. You can then compare your baseline data, prior to transformation, with the post-transformation results to understand any potential gaps.
In the top right corner, you can see the job status, which has one of the following values:
+ Awaiting user input
+ Time elapsed
+ Running
You can also see the following icons:
+ A stop transformation icon
+ A refresh icon
+ A settings icon
The *Dashboard* provides a high level summary of the transformation. It shows metrics for the number of jobs transformed and transformation applied, and the estimated time to complete the transformation.
The *Dashboard* includes:
1. The transformation *Job details* section, which lists the default settings and details of the transformation job, including:
1. *Target branch destination* To transform your code, AWS Transform creates a new branch for the transformed code in your code repo.
1. *Target .NET version*, .NET 8.0 or .NET 10
1. The AWS Transform *job ID.*
1. The job settings:
1. Exclude .NET standard projects
1. The *Transformation summary* section contains:
1. The number of repositories selected for transformation
1. The number of projects to be transformed
1. The total lines of codes in these repositories and projects
After the transformation starts, pie charts appear in the *Repository status*, *Package status*, and *Unit test status* sections displaying progress in real time. The *Unit test status* shows the status of unit tests located in your repositories that AWS Transforms runs after transformation to test the transformed code. AWS Transform shares the executed test results, along with individual test name for customers to review the list of unit tests passed and failed.
**Note**
The *Repositories* section lists the repositories that AWS Transform recommends or that you selected for transformation. Select **Download JSON** to download a list of repositories, dependencies, and packages in your transformation plan.
## Review the transformation reports
After a transformation job completes, you can download [Transformation Reports](https://docs.aws.amazon.com/transform/latest/userguide/tdotnet-reports.html):
+ [Transformation summary report](https://docs.aws.amazon.com/transform/latest/userguide/tdotnet-reports.html#transformation-summary-report): This report provides an overview of the transformation in HTML or JSON format. Download the transformation summary report from the **Dashboard tab**. Select **Download**, and choose **Download as HTML** or **Download as JSON**.
+ [Transformation detail report](https://docs.aws.amazon.com/transform/latest/userguide/tdotnet-reports.html#transformation-detail-report): This report provides in-depth information about a transformation in HTML format. Download transformation detail reports from the **Dashboard tab**. Select a **Download detailed report** link in the repository list to download a detail report.
### Chat with AWS Transform about the transformation report
You can chat with AWS Transform about the transformation report after a repository has been completely processed or after the transformation job is completed. The **Worklog** tab displays this message for each repository that is available for chat: *Repository `repository_name` transformation details are now available in chat for queries*. It displays this message when the transformation job is completed: *AWS Transform transformation job is completed*.
To open the chat click the purple hexagonal icon in the lower right corner of the web console.
Here are some example prompts:
+ Which projects were successfully transformed?
+ Which projects were partially ported?
+ What changes were made to the `repo_name` repository?
+ What packages were upgraded in the `project_name` project?