# Modernizing .NET with AWS Transform
The AWS Transform agent for .NET can help you modernize your .NET applications to be compatible with cross-platform .NET. This capability is called .NET modernization. After [AWS Transform environment](transform-environment.md) in AWS Transform, you can create a .NET modernization transformation job.
## Capabilities and key features
+ Analyze .NET Framework codebases from your source control systems, which includes private NuGet support, identifying cross repository dependencies, and providing an analysis report.
+ Automated transformation of legacy .NET Framework applications to cross-platform .NET, email notifications, and a transformation summary report.
+ Easy integration with the source control platforms (BitBucket, GitHub, and GitLab) to ingest existing code and commit transformed code to a new branch.
+ Validation of transformed code through unit tests.
## Supported versions and project types
AWS Transform supports transformation for these versions of .NET:
+ .NET Framework 3.5\$1
+ .NET Core 3.1
+ .NET 5.x\$1
+ .NET 8
AWS Transform can transform to these target .NET versions:
+ .NET 8
+ .NET 10
AWS Transform supports transformation of these types of projects (C\$1 only):
+ Class libraries
+ Console applications
+ ASP.NET:
+ Model View Controller (MVC), including front-end Razor Views
+ Single Page Application (SPA) back-ends (business logic layers)
+ Web API
+ Web Forms
+ Unit test projects (NUnit, xUnit, and MSTest)
+ Windows Communication Foundation (WCF) services
+ Projects with provided cross-platform versions for third-party or private NuGet packages. If a cross-platform equivalent is missing or unavailable, AWS Transform for .NET will attempt a best-effort conversion.
AWS Transform can also transform the following project types to modern .NET. This is a preview feature, available only in the US East (N. Virginia) Region.
+ WinForms desktop projects. This is a preview feature, available only in the US East (N. Virginia) Region.
+ WPF desktop projects. This is a preview feature, available only in the US East (N. Virginia) Region.
+ Xamarin mobile projects. This is a preview feature, available only in the US East (N. Virginia) Region.
+ Projects written in VB.NET. This is a preview feature, available only in the US East (N. Virginia) Region.
## Limitations
For more information on quotas and limitations for AWS Transform, see [Quotas for AWS Transform](transform-limits.md).
AWS Transform does not transform the following:
+ Blazor UI components
+ Win32 DLLs that don't have core compatible libraries
+ Repositories that do not contain any solutions.
AWS Transform will not modify the original repo branches, and can only write to a separate target branch specified in your transformation plan.
## Human intervention
During the porting of .NET Framework applications to cross-platform .NET, you may be requested to provide input or approvals in the following scenarios:
+ Set up a connector to your source code and permissions
+ Validate the proposed modernization plan
+ Upload missing package dependencies as NuGets
+ Review and accept the transformed code
## More information
You can modernize your .NET code by using either the AWS Transform web application or the AWS Toolkit for Visual Studio.
+ [Modernizing your .NET code by using the AWS Transform web application](dotnet-web-app.md)
+ [Modernizing .NET in the IDE](dotnet-ide.md)
# 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?
# Modernizing .NET in the IDE
AWS Transform for .NET is a new generative AI-powered agent designed to modernize legacy .NET applications. For more information, see Modernizing .NET with AWS Transform. You can modernize your legacy .NET code by using the AWS Transform web application or the Visual Studio AWS Toolkit extension. Use AWS Transform in integrated development environments (IDEs) to get assistance with your software development needs. In IDEs, AWS Transform includes capabilities to provide guidance and support across various aspects of .NET code modernization.
To transform a .NET solution or project, the AWS Transform agent analyzes your codebase, determines the necessary updates to port your application, and generates a transformation plan before the transformation begins. During this analysis, the AWS Transform agent divides your .NET solution or project into code groups that you can view in the transformation plan. A code group is a project and all its dependencies that together generate a buildable unit of code such as a dynamic link library (DLL) or an executable.
During the transformation, the AWS Transform agent provides step-by-step updates in the AWS **Transformation Hub** window where you can monitor progress. After transforming your application, AWS Transform generates a summary with the proposed changes in a diff view for you to optionally verify the changes before you accept them. When you accept the changes, AWS Transform makes in-place updates to your .NET solution or project.
AWS Transform performs four keys tasks to port .NET applications to Linux:
+ Upgrades language version – Replaces outdated C\$1 versions of code with Linux-compatible C\$1 versions.
+ Migrates from .NET Framework to cross-platform .NET – Migrates projects and packages from Windows dependent .NET Framework to cross-platform .NET compatible with Linux.
+ Rewrites code for Linux compatibility – Refactors and rewrites deprecated and inefficient code components.
+ Generates a Linux compatibility readiness report – For open-ended tasks where user intervention is needed to make the code build and run on Linux, AWS Transform provides a detailed report of actions needed to configure your application after transformation.
For more information about how AWS Transform performs .NET transformations, see [How AWS Transform modernizes .NET applications](dotnet-ide-how.md).
**Quotas**
For AWS Transform .NET transformation quotas in the IDE, see [Quotas for AWS Transform](transform-limits.md).
To modernize your .NET code using the AWS Transform, part of the Visual Studio AWS Toolkit extension, see the following:
+ [Modernizing .NET using AWS Transform in Visual Studio](dotnet-ide-vs.md)
+ [How AWS Transform modernizes .NET applications](dotnet-ide-how.md)
+ [Troubleshooting issues with .NET transformations in the IDE](dotnet-ide-troubleshoot.md)
# Modernizing .NET using AWS Transform in Visual Studio
Complete these steps to port a Windows-based .NET application to a Linux-compatible cross-platform .NET application with AWS Transform in Visual Studio 2026 or 2022.
## Step 1: Prerequisites
Before you continue, make sure you've downloaded and installed the [AWS Toolkit extension with Amazon Q](https://marketplace.visualstudio.com/items?itemName=AmazonWebServices.AWSToolkitforVisualStudio2022) from the Visual Studio Marketplace. Review the AWS Transform [capabilities](https://docs.aws.amazon.com/transform/latest/userguide/dotnet.html#capabilities) and [limitations](https://docs.aws.amazon.com/transform/latest/userguide/dotnet.html#limitations) for .NET modernization to confirm that your code can be transformed.
## Step 2: Authenticate in Visual Studio
To connect to your AWS accounts from the Toolkit for Visual Studio, open the Getting Started with the AWS Toolkit User Interface (connection UI):
1. From the Visual Studio main menu, navigate to **Extensions > AWS Toolkit > Getting Started** to open the **Getting Started: AWS Toolkit page**.
1. Select either **AWS Transform** or **Amazon Q Developer **authentication.
1. Choose an existing profile or create a new one. When creating a new profile, enter a name for the profile and your AWS Transform start URL, which was emailed to you after you were added to IAM Identity Center by your administrator.
1. Choose **Connect**. Follow the prompts to sign in and grant access permissions through your web browser. In Visual Studio, you should see **Connected with IAM Identity Center**.
## Step 3: Transform your application
To transform your .NET solution or project, complete the following procedure:
1. Open any C\$1 based solution or project in Visual Studio that you want to transform.
1. Open any C\$1 code file in the editor.
1. Choose **Solution Explorer**.
1. From the **Solution Explorer**, right click a solution or project you want to transform, and then choose to port or transform the solution or project with AWS Transform.
1. The AWS Transform window appears.
The solution or project you selected will be chosen in the **Choose a solution or project to transform** dropdown menu. You can expand the menu to choose a different solution or project to transform.
1. In the **Choose a workspace** dialog, create a workspace or select an existing one. Workspaces make your activity visible in the AWS Transform web application, where you can invite collaborators to view and chat about transformation jobs.
1. In the **Choose a .NET target** dropdown menu, choose the .NET version you want to upgrade to.
1. You can update the Default 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.
1. Choose **Start** to begin the transformation.
1. Wait while AWS Transform analyzes your code and generates an assessment report and a code transformation plan.
You will be prompted with **View Transformation Plan?** **Choose Edit Plan** to review or edit the transformation plan, or **Start transformation** to transform with the existing plan.
1. If you choose to edit the plan, a *transformation-plan.md* markdown file will open in the code editor. The transformation plan describes the objective and details of the transformation in a series of steps. Refer to the instruction comments at the end if the plan. You can modify this plan in the following ways:
+ **Transformation steps and substeps**: change, add, or remove steps and substeps to control structural transformation and package update details
+ **Preview Project Transformation**: Add experimental transformation of WinForms desktop projects, WPF projects, Xamarin projects, or projects written in VB.NET
**Note**
Other project transformations are a preview feature, available only in the US East (N. Virginia) Region.
+ **Customization section**: add customization instructions, such as dependency injection instructions or coding pattern examples.
**Note**
Coding pattern examples are a preview feature, available only in the US East (N. Virginia) Region.
After saving any plan changes, choose **Start Transformation** to start the transformation.
1. AWS Transform begins transforming your code.
An **AWS Transformation Hub** opens where you can monitor progress for the duration of the transformation. Here you can see estimated time remaining, a Job ID you can copy to the clipboard, and transformation steps. Choose a step to see the worklog for that step, which explains the current transformation activity.
Once AWS Transform has started the **Transforming code** step you can navigate away from the project or solution for the duration of the transformation.
1. After the transformation is complete, navigate to the **Transformation Hub** and choose **View diffs** to review the proposed changes in a diff view. To update your files in place, choose **Accept changes** from the Actions dropdown menu.
1. Choose **View code transformation summary** for a summary of the changes AWS Transform made. For details about transformation, including changes made, the reason for changes, and actionable error details, you can download a transformation detail report by choosing **Download transformation report**. Refer to [Transformation Reports](https://docs.aws.amazon.com/transform/latest/userguide/tdotnet-reports.html) for more information. The transformation detail report includes a Linux readiness report section that identifies compatibility issues in moving from Windows to Linux that require human attention.
If any of the items in the **Code groups** table require input under the Linux porting status, you must manually update some files to run your application on Linux. The transformation detail report includes a Linux readiness report section that identifies compatibility issues in moving from Windows to Linux that require human attention.
1. AWS Transform generates a *NextSteps.md *file, which describes any remaining porting work needed. To download the report, choose the **Download next steps** button at the top of the transformation detail report. You can use the NextSteps.md file to transform the project again with AWS Transform and a revised plan, or use it as input to an AI code companion.
1. To update your files in place, choose **Accept changes** from the **Actions** dropdown menu.
# How AWS Transform modernizes .NET applications
Review the following sections for details about how .NET transformation with AWS Transform works.
## Analyzing your application and generating a transformation plan
Before a transformation begins, AWS Transform builds your code locally to verify that it is buildable and configured correctly for transformation. If the code does not build, AWS Transform will prompt whether to continue with transformation. AWS Transform then uploads your code to a secure and encrypted build environment on AWS, analyzes your codebase, and determines the necessary updates to port your application
During this analysis, AWS Transform divides your .NET solution or project into code groups. A code group is a project and all its dependencies that together generate a buildable unit of code such as a dynamic link library (DLL) or an executable. Even if you didn't select all project dependencies to be transformed, AWS Transform determines the dependencies needed to build your selected projects and transforms them too, so that your transformed application will be buildable and ready for use.
After analyzing your code, AWS Transform generates a transformation plan that outlines the proposed changes that it will make, including a list of code groups and their dependencies that will be transformed.
## Transforming your application
To start the transformation, AWS Transform builds your code again in the secure build environment to verify if it is buildable remotely. AWS Transform then begins porting your application. It works from the bottom up, starting with the lowest level dependency. If AWS Transform runs into an issue with porting a dependency, it stops the transformation and provides information about what caused the error.
The transformation includes the following updates to your application:
+ Replacing outdated C\$1 versions of code with Linux-compatible C\$1 versions
+ Upgrading .NET Framework to cross-platform .NET, including:
+ Identifying and iteratively replacing packages, libraries, and APIs
+ Upgrading and replacing NuGet packages and APIs
+ Transitioning to cross-platform runtime
+ Setting up middleware and updating runtime configurations
+ Replacing private or third-party packages
+ Handling IIS and WCF components
+ Debugging build errors
+ Rewriting code for Linux compatibility, including refactoring and rewriting deprecated and inefficient code to port existing code
## Reviewing transformation report and accepting changes
After the transformation is complete, AWS Transform provides a transformation report with information about the proposed updates it made to your application, including the number of files changed, packages updated, and APIs changed. It flags any unsuccessful transformations, including affected files or portions of files and the errors encountered during an attempted build. You can also view a build summary with build logs to learn more about what changes were made.
The transformation report also provides a Linux porting status, which indicates whether or not additional user input is needed to make the application Linux compatible. If any of the items in a code group require input from you, you download a Linux readiness report that contains Windows-specific considerations that AWS Transform could not address at build time. If input is needed for any code groups or files, review the report for details about what type of change still needs to be made and, if applicable, for recommendations for how to update your code. These changes must be made manually before your application can be run on Linux.
You can review the proposed changes AWS Transform made in a diff view before accepting them as in-place updates to your files. After updating your files and addressing any items in the Linux readiness report, your application is ready to run on cross-platform .NET.
You can download a *Next Steps* markdown file with prompts for continued transformation with AWS Transform or an AI code companion. To download the file, choose the **Download Next Steps** button at the top right of the report.
# Troubleshooting issues with .NET transformations in the IDE
Use the following sections to troubleshoot common issues with .NET transformations in the IDE with AWS Transform.
## How do I know if a job is progressing?
If AWS Transform appears to be spending a long time on a step in the **AWS Transformation Hub**, you can check whether the job is still active in the output logs. If diagnostic messages are being generated, the job is still active.
To check the outputs, choose the **Output** tab in Visual Studio. In the **Show output from:** menu, choose **Amazon Q Language Client**.
The following screenshot shows an example of the outputs AWS Transform generates during a transformation.
![\[Screen shot of the AWS Transform Code Transformation Hub, showing the output from the Amazon Q Language Client.\]](http://docs.aws.amazon.com/transform/latest/userguide/images/code-transform-troubleshoot4.png)
## Why are some projects not selected for transformation?
AWS Transform can only transform supported .NET project types. For a list of supported project types and other prerequisites for transforming your .NET projects, see [Step 1: Prerequisites](dotnet-ide-vs.md#transform-dotnet-prerequisites).
## How can I get support if my project or solution isn't transforming?
If you aren't able to troubleshoot issues on your own, you can reach out to Support or your AWS account team to submit a support case.
To get support, provide the transformation job ID so AWS can investigate a failed job. To find a transformation job ID, choose the **Output** tab in Visual Studio. In the **Show output from:** menu, choose **Amazon Q Language Client**.
## How can I prevent my firewall from interfering with transformation jobs?
If your organization uses a firewall, it might interfere with transformations in Visual Studio. You can temporarily disable security checks in Node.js to troubleshoot or test what is preventing the transformation from running.
The environment variable `NODE_TLS_REJECT_UNAUTHORIZED` controls important security checks. Setting `NODE_TLS_REJECT_UNAUTHORIZED` to "0" disables Node.js's rejection of unauthorized TLS/SSL certificates. This means:
+ Self-signed certificates will be accepted
+ Expired certificates will be allowed
+ Certificates with mismatched hostnames will be permitted
+ Any other certificate validation errors will be ignored
If your proxy uses a self-certificate, you can set the following environment variables instead of disabling `NODE_TLS_REJECT_UNAUTHORIZED`:
```
NODE_OPTIONS = —use-openssl-ca
NODE_EXTRA_CA_CERTS = Path/To/Corporate/Certs
```
Otherwise, you must specify the CA certs used by the proxy to disable `NODE_TLS_REJECT_UNAUTHORIZED`.
**To disbale NODE\$1TLS\$1REJECT\$1UNAUTHORIZED on Windows:**
1. Open the Start menu and search for **Environment Variables**.
1. Choose **Edit the system environment variables**.
1. In the **System Properties** window, choose **Environment Variables**.
1. Under **System variables**, choose **New**.
1. Set **Variable name** to NODE\$1TLS\$1REJECT\$1UNAUTHORIZED and **Variable value** to 0.
1. Choose **OK** to save the changes.
1. Restart Visual Studio.
# Porting UI layer code
AWS Transform can port the UI layer of ASP.NET websites to UI frameworks compatible with ASP.NET Core, which can run on Linux. The following transformations are available:
+ MVC Razor UI porting
+ Web Forms to Blazor UI porting
## MVC Razor UI porting
ASP.NET MVC projects with Razor Views UI can be ported to MVC Razor Views on ASP.NET Core, remaining on the same UI framework. While Razor views are similar between ASP.NET and ASP.NET Core, there are differences that require porting code changes:
+ ASP.NET MVC Razor Views use the System.Web.Mvc namespace and are closely tied to the .NET Framework.
+ ASP.NET Core Razor Views are modular, built on Microsoft.AspNetCore.Mvc, with improved dependency injection.
+ ASP.NET Core has new features including Tag Helpers and View Components.
AWS Transform detects and ports common incompatible components and constructs in Razor Views.
## Web Forms to Blazor UI porting
ASP.NET Web Forms UI does not have a counterpart on ASP.NET Core. AWS Transform can port Web Forms UI layer code to Blazor Server on ASP.NET Core. UI layer code is rewritten for the target UI framework.
To enable or disable Web Forms to Blazor UI porting, check or clear the Transform UI ASP.NET Web Forms to Blazor job setting.
### Transformation details
Your Web Forms project is converted to a Blazor project with server-side hosting. The following project and file changes are made during transformation:
**File transformation mapping**
| From | To | Description |
| --- | --- | --- |
| \$1.aspx, \$1.ascx | \$1.razor | .aspx pages and .ascx custom controls become .razor files |
| Web.config | appsettings.json | Web.config settings become appsettings.json settings |
| Global.asax | Program.cs | Global.asax code becomes Program.cs code |
| \$1.master | \$1layout.razor | Master files become layout.razor files |
### Post-transformation project structure
After transformation, the transformed files reside in the following project locations:
+ Components folder: All razor components (\$1.razor) are placed in a Components folder created at the same level as the project's .csproj file.
+ Pages mapping: Web Forms pages (\$1.aspx) are converted to Components/Pages folder structure.
+ Controls mapping: Web Forms controls (\$1.ascx) are placed directly under the Components folder.
### Limitations and unsupported features
Projects with up to 1000 pages (.aspx \$1 .ascx files) can be transformed.
The following features are not supported at present. If your workloads use these features, that code will need to be ported manually or with an AI code companion post-transformation.
+ .asmx files (XML web service)
+ .svc files (service files)
+ .ashx files (generic handler files)
+ Service references & web references (reference.map, reference.cs, .wsdl files)
+ Mixtures of .aspx (Web Forms) files and .cshtml (Razor) files in the same project
+ Dependencies on project types not yet supported by AWS Transform for .NET
+ Third-party vendor UI libraries/controls
+ Web Site projects
Only Web Application projects (containing a .csproj file) are supported. To convert a Web Site project to a Web Application project, see Microsoft guidance [Converting a Web Site Project to a Web Application Project](https://devblogs.microsoft.com/dotnet/converting-a-web-site-project-to-a-web-application-project/).
# Transformation Reports
After your .NET transformation job completes these transformation reports are available:
+ [Transformation Summary Report](#transformation-summary-report)
+ [Transformation Detail Report](#transformation-detail-report)
## Transformation Summary Report
After a transformation job completes, a transformation summary report is available in the web console. Download the transformation summary report from the **Dashboard** tab. Select **Download Transformation Summary Report**, and choose **Download as HTML** or **Download as JSON**.
The Transformation Summary Report provides an overview of the transformation and information specific to each repository that was transformed, including:
+ Job Details
+ Transformation job overview
+ Transformation results overview
+ Files overview
+ Repositories list, and for each repository:
+ Repository Name Overview
+ Solution Transformation Summary
+ Project Details, including Status, Type, .NET Version, Total Lines of Code, Transformed Lines of Code, and Files Changed
## Transformation Detail Report
After a transformation job finishes, transformation detail reports are available for both web console and IDE users.
+ Web console users: a detail report is available for each transformed repository. On the **Dashboard** tab, use the **Download detailed report** links in the repository list to download a detail report.
+ IDE users: a detail report is available for the transformed solution or project. On the **Transformation summary pane**, use the **Download report button** to download a detail report.
The transformation detail report is an interactive HTML report. It contains in-depth information about the transformation, including the reasons for file changes and actionable error details. The information is arranged in the following hierarchy:
+ Job Information
+ For each solution:
+ Solution Transformation Summary
+ Transformation Overview
+ Projects
+ For each project:
+ Project Summary
+ Build Errors Summary
+ NuGet package changes
+ File Changes
+ Build Errors
+ Unit Test Results
+ Linux Readiness Report
For a walk-through of the transformation detail report sections with examples, refer to the blog post [Announcing AWS Transform for .NET detailed transformation reports](https://aws.amazon.com/blogs/dotnet/announcing-aws-transform-for-net-detailed-transformation-reports/).