diff --git a/.openpublishing.redirection.core.json b/.openpublishing.redirection.core.json index 8a5f108311fca..27ca47713c8ed 100644 --- a/.openpublishing.redirection.core.json +++ b/.openpublishing.redirection.core.json @@ -877,6 +877,14 @@ "source_path_from_root": "/docs/core/porting/upgrade-assistant-aspnetmvc.md", "redirect_url": "/aspnet/core/migration/mvc" }, + { + "source_path_from_root": "/docs/core/porting/upgrade-assistant-install-legacy.md", + "redirect_url": "/dotnet/core/porting/upgrade-assistant-wcf" + }, + { + "source_path_from_root": "/docs/core/porting/upgrade-assistant-uwp-framework.md", + "redirect_url": "/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/upgrade-assistant" + }, { "source_path_from_root": "/docs/core/porting/upgrade-assistant-winforms-framework.md", "redirect_url": "/dotnet/desktop/winforms/migration/" @@ -1325,10 +1333,6 @@ { "source_path_from_root": "/docs/fundamentals/networking/tcp/tcp-overview.md", "redirect_url": "/dotnet/fundamentals/networking/sockets/tcp-classes" - }, - { - "source_path_from_root": "/docs/core/porting/upgrade-assistant-uwp-framework.md", - "redirect_url": "/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/upgrade-assistant" } ] } diff --git a/docs/core/porting/media/upgrade-assistant-analyze-overview/aggregate-issues.png b/docs/core/porting/media/upgrade-assistant-analyze-overview/aggregate-issues.png new file mode 100644 index 0000000000000..51aac1bfbf1c6 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-analyze-overview/aggregate-issues.png differ diff --git a/docs/core/porting/media/upgrade-assistant-analyze-overview/dashboard.png b/docs/core/porting/media/upgrade-assistant-analyze-overview/dashboard.png new file mode 100644 index 0000000000000..72fa7530ef844 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-analyze-overview/dashboard.png differ diff --git a/docs/core/porting/media/upgrade-assistant-analyze-overview/projects.png b/docs/core/porting/media/upgrade-assistant-analyze-overview/projects.png new file mode 100644 index 0000000000000..cf042efa92068 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-analyze-overview/projects.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-analyze/cli-upgrade-end.png b/docs/core/porting/media/upgrade-assistant-how-to-analyze/cli-upgrade-end.png new file mode 100644 index 0000000000000..d6e49500eed4d Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-analyze/cli-upgrade-end.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-analyze/cli-upgrade-options-end.png b/docs/core/porting/media/upgrade-assistant-how-to-analyze/cli-upgrade-options-end.png new file mode 100644 index 0000000000000..3e1adc5c61a84 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-analyze/cli-upgrade-options-end.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-analyze/cli-upgrade-start.png b/docs/core/porting/media/upgrade-assistant-how-to-analyze/cli-upgrade-start.png new file mode 100644 index 0000000000000..7971ad43fc4c0 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-analyze/cli-upgrade-start.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-finished.png b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-finished.png new file mode 100644 index 0000000000000..a3e5deabd5404 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-finished.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-new-report.png b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-new-report.png new file mode 100644 index 0000000000000..ba7779a2b9de1 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-new-report.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-progress.png b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-progress.png new file mode 100644 index 0000000000000..8c2b326a4d1c9 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-progress.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-right-click.png b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-right-click.png new file mode 100644 index 0000000000000..9d89f344ff3ff Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-right-click.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-components.png b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-components.png new file mode 100644 index 0000000000000..8202bb2cd94e5 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-components.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-projs.png b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-projs.png new file mode 100644 index 0000000000000..12ed79a4f114c Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-projs.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-target-framework.png b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-target-framework.png new file mode 100644 index 0000000000000..b7accf550a86d Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-target-framework.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-upgrade/cli-upgrade-end.png b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/cli-upgrade-end.png new file mode 100644 index 0000000000000..b5a1eb7444b06 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/cli-upgrade-end.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-upgrade/cli-upgrade-options-end.png b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/cli-upgrade-options-end.png new file mode 100644 index 0000000000000..c940d2920f784 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/cli-upgrade-options-end.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-upgrade/cli-upgrade-start.png b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/cli-upgrade-start.png new file mode 100644 index 0000000000000..8ce22d38b4ebf Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/cli-upgrade-start.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-finished.png b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-finished.png new file mode 100644 index 0000000000000..15576a1fca259 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-finished.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-right-click.png b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-right-click.png new file mode 100644 index 0000000000000..46f0ea26039b4 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-right-click.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-select-components.png b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-select-components.png new file mode 100644 index 0000000000000..b8c961c5e32bc Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-select-components.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-target-framework.png b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-target-framework.png new file mode 100644 index 0000000000000..2bbe981cac277 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-target-framework.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-type.png b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-type.png new file mode 100644 index 0000000000000..29872d629910b Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-type.png differ diff --git a/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-welcome-framework.png b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-welcome-framework.png new file mode 100644 index 0000000000000..3ac2c1b164b56 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-welcome-framework.png differ diff --git a/docs/core/porting/media/upgrade-assistant-install/visual-studio-manage-extensions.png b/docs/core/porting/media/upgrade-assistant-install/visual-studio-manage-extensions.png index 49c01b3031589..8c76bd55c3b48 100644 Binary files a/docs/core/porting/media/upgrade-assistant-install/visual-studio-manage-extensions.png and b/docs/core/porting/media/upgrade-assistant-install/visual-studio-manage-extensions.png differ diff --git a/docs/core/porting/media/upgrade-assistant-overview/visual-studio-upgrade-results.png b/docs/core/porting/media/upgrade-assistant-overview/visual-studio-upgrade-results.png index 1e8c4096a7237..b52454383f3bb 100644 Binary files a/docs/core/porting/media/upgrade-assistant-overview/visual-studio-upgrade-results.png and b/docs/core/porting/media/upgrade-assistant-overview/visual-studio-upgrade-results.png differ diff --git a/docs/core/porting/third-party-deps.md b/docs/core/porting/third-party-deps.md index 87b3879fef89b..d3ed619fa8614 100644 --- a/docs/core/porting/third-party-deps.md +++ b/docs/core/porting/third-party-deps.md @@ -95,7 +95,7 @@ The .NET Team would like to know which libraries are the most important to suppo ## Analyze non-NuGet dependencies -You might have a dependency that isn't a NuGet package, such as a DLL in the file system. You can determine the portability of that dependency with the CLI version of the [.NET Upgrade Assistant](upgrade-assistant-overview.md#upgrade-with-the-cli-tool) tool. +You might have a dependency that isn't a NuGet package, such as a DLL in the file system. You can determine the portability of that dependency with the [.NET Upgrade Assistant](upgrade-assistant-overview.md) tool. ## Next steps diff --git a/docs/core/porting/upgrade-assistant-analyze-overview.md b/docs/core/porting/upgrade-assistant-analyze-overview.md new file mode 100644 index 0000000000000..5f2f863489dc2 --- /dev/null +++ b/docs/core/porting/upgrade-assistant-analyze-overview.md @@ -0,0 +1,115 @@ +--- +title: .NET Upgrade Assistant code analysis overview +description: "Describes how the code analysis function of .NET Upgrade Assistant works. The analysis generates a report that lists what aspects of your project will be upgraded, and if any manual work is involved." +author: adegeo +ms.author: adegeo +ms.topic: overview +ms.date: 10/08/2024 + +#customer intent: As a developer, I need to understand what the analyze function of .NET Upgrade Assistant does. + +--- + +# What is code analysis with .NET Upgrade Assistant? + +This article provides an overview of the code analysis function of .NET Upgrade Assistant. Code analysis generates a report based on your project configuration, dependencies, and code. The report contains information about potential issues and problems you might encounter during the upgrade, and what steps you could take to remediate those problems. + +## Types of analysis + +There are two types of analysis you can perform on your code: + +- Source code and settings + + Analyzes your source code, configuration, and settings. + +- Binary dependencies + + Analyzes the external binary dependencies (such as NuGet packages) for your projects. + + + +## Reports + +A dashboard report is generated after the analysis completes. This report breaks down the results by project, file, incident, and [story points](#incident-story-points). An aggregate view is also available, to group like-issues together regardless of what project they were detected in. + +> [!TIP] +> Story points are an Agile concept that helps estimate complexity and effort required to fix a problem. For more information, see the [Incident story points](#incident-story-points) section. + +Each issue in the report is categorized by [severity](#incident-severity) to assist you in prioritizing any fixes you need to make. Issues are either mandatory or optional. Mandatory issues block the upgrade. Optional issues provide an opportunity to upgrade to a newer feature, library, or code enhancement. + +The following sections describe areas of the report in detail. + +### Dashboard + +The **Dashboard** page provides a view of the incidents detected by the scan, grouped into panels: + +:::image type="content" source="./media/upgrade-assistant-analyze-overview/dashboard.png" alt-text="The .NET Upgrade Assistant Analyze results, showing the dashboard's starting page."::: + +- **Summary** + + - **Projects** + + This is the number of projects where an incident was detected. + + - **Issues** + + The number of unique rules that triggered during the scan. Each issue has its own severity and story point, along with each detected instance (incident). + + - **Incidents** + + An incident is an instance of a detected issue at a specific location, such as a piece of code or binary file. Each incident contains the contextual information that triggered the issue. + + - **Story Points** + + The total number of story points required to complete the upgrade. For more information about what a story point is, see the [Incident story points](#incident-story-points) section. + +- **Severity** and **Categories** + + These two panels show charts that group the incidents by severity and category. For more information about severity, see the [Incident severity](#incident-severity) section. + +### Projects + +The **Projects** page breaks down the issues, incidents, and story points, by project. Each project is a link that opens a drill-down report filtered to that project. + +:::image type="content" source="./media/upgrade-assistant-analyze-overview/projects.png" alt-text="The .NET Upgrade Assistant Analyze results, showing the dashboard's 'Projects' page."::: + +### Aggregate issues + +The **Aggregate issues** page details each issue that was triggered. Each issue can be expanded to list every incident of that issue. The **State** column helps you track which issues you've fixed or deemed not applicable. + +:::image type="content" source="./media/upgrade-assistant-analyze-overview/aggregate-issues.png" alt-text="The .NET Upgrade Assistant Analyze results, showing the dashboard's 'Aggregate issues' page."::: + +## Incident severity + +Each issue incident has an associated severity, which might block the upgrade. The severity helps you understand what must be updated for the upgrade to succeed. + +| Severity | Description | +| --- | --- | +| Mandatory | Must be addressed. The upgrade process might handle these issues for you, such as updating the target framework runtime (TFM). | +| Optional | These shouldn't pose a problem with upgrading, but you might want to consider addressing them before or after the upgrade. | +| Potential | Problems that might cause issue after upgrading, if you don't address them now. | +| Information | Extra information related to the upgrade. | + +## Incident story points + +Each issue incident has an associated story point. A story point is a unit of measure to gauge the complexity of an incident, which helps estimate the time involved to resolve that incident. .NET Upgrade Assistant defines story point values by the following table: + +| Story Points | Size | +|--------------|----------------| +| 1 | Trivial | +| 3 | Complex | +| 5 | Redesign | +| 7 | Rearchitecture | +| 13 | Unknown | + +## Related content + +- [Analyze projects with .NET Upgrade Assistant](upgrade-assistant-how-to-analyze.md) diff --git a/docs/core/porting/upgrade-assistant-how-to-analyze.md b/docs/core/porting/upgrade-assistant-how-to-analyze.md new file mode 100644 index 0000000000000..2a1fd456b75c3 --- /dev/null +++ b/docs/core/porting/upgrade-assistant-how-to-analyze.md @@ -0,0 +1,84 @@ +--- +title: How to analyze a project with .NET Upgrade Assistant +description: "Learn how to analyze one or more projects with .NET Upgrade Assistant. Before upgrading, it's a good idea to perform code analysis on your projects so that you understand if extra effort is required after upgrading." +author: adegeo +ms.author: adegeo +ms.topic: how-to +ms.date: 10/08/2024 + +#customer intent: As a developer, I want to analyze my project before upgrading to identify any issues before performing an upgrade. + +--- + +# Analyze projects with .NET Upgrade Assistant + +This article teaches you how to perform code analysis on your projects with .NET Upgrade Assistant, using Visual Studio or the terminal. The analysis generates a report that you can browse to get more information about the upgrade. + +## Prerequisites + +- For Visual Studio, see [Install .NET Upgrade Assistant - Visual Studio extension](upgrade-assistant-install.md#visual-studio-extension) +- For the .NET Global Tool, see [Install .NET Upgrade Assistant - .NET Global Tool](upgrade-assistant-install.md#net-global-tool) + +## Create a report in Visual Studio + +Follow these steps to analyze a project in Visual Studio. + +1. Open Visual Studio. +1. Open a project or solution. +1. In the **Solution Explorer** window, right-click on the **solution** > **Upgrade**. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-right-click.png" alt-text="The Solution Explorer window in Visual Studio, showing the right-click menu of the solution. The Upgrade menu item is highlighted."::: + +1. In the **Upgrade Assistant: Home** tab, select **New Report**. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-new-report.png" alt-text="The .NET Upgrade Assistant Analyze wizard's welcome page in Visual Studio. The 'New Report' link is highlighted."::: + +1. Select one or more projects to analyze, then select **Next**. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-projs.png" alt-text="The .NET Upgrade Assistant Analyze wizard's 'Select projects' page in Visual Studio. The list of projects is highlighted along with the 'Next' button."::: + +1. Select the target framework, for example .NET 8.0. Then, select **Next**. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-target-framework.png" alt-text="The .NET Upgrade Assistant Analyze wizard's 'Target framework' page in Visual Studio. The '.NET 8.0' item is highlighted along with the 'Next' button."::: + +1. Select the components to analyze and then select **Next**. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-components.png" alt-text="The .NET Upgrade Assistant Analyze wizard's 'Analysis settings' page in Visual Studio. The 'Source code and settings' option is selected. The 'Next' button is highlighted."::: + +1. A progress indicator is displayed for each project that's being analyzed. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-progress.png" alt-text="The .NET Upgrade Assistant Analyze wizard running the analysis."::: + +1. Once the analysis is complete, the report dashboard is shown. For more information about the dashboard, see [Reports](upgrade-assistant-analyze-overview.md#reports). + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-finished.png" alt-text="The .NET Upgrade Assistant Analyze wizard showing a report dashboard that contains the results from the analysis."::: + +## Create a report from the CLI + +Follow these steps to analyze a project using the terminal. The .NET Global Tool is an interactive tool that guides you through the analysis options. Use the Up arrow and Down arrow keys to change the highlighted option, and Enter to run the select the option. Each screen presents you options on how you want to configure the report. + +1. Open a terminal and navigate to the folder containing the solution or project you want to analyze. +1. To start the tool, run the `upgrade-assistant analyze` command. +1. You're asked about what you want to analyze. For this example, choose **Application sources** and press Enter. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/cli-upgrade-start.png" alt-text="A terminal showing the initial screen of options for .NET Upgrade Assistant Global Tool. The question 'What do you want to analyze' is being asked."::: + +1. Choose a target framework, such as **.NET 8.0**, and press Enter. +1. Select the types of items you want to scan. Use Spacebar to toggle the options, and then press Enter. +1. On the **Config file** screen, press n, unless you have a ruleset config file to apply. +1. Choose the format of the generated report. For the purposes of this example, select **Save as HTML**. +1. Enter the name **MyReport** and press Enter. +1. Select the appropriate privacy mode, such as **Restricted** and press Enter. +1. The final prompt is a confirmation, displaying all of the options you selected. Press Enter to run the analysis and generate the report. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/cli-upgrade-options-end.png" alt-text="A terminal showing the summary screen of options for .NET Upgrade Assistant Global Tool. The user is asked to continue."::: + +1. Once the report finishes, a summary of the report is displayed. The results of the report are saved to the folder of the project or solution that was analyzed. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/cli-upgrade-end.png" alt-text="A terminal showing the results of the analysis command when using the .NET Upgrade Assistant Global Tool."::: + +## Related content + +- [What is code analysis with .NET Upgrade Assistant?](upgrade-assistant-analyze-overview.md) +- [What is .NET Upgrade Assistant?](upgrade-assistant-overview.md) +- [Install .NET Upgrade Assistant](upgrade-assistant-install.md) diff --git a/docs/core/porting/upgrade-assistant-how-to-upgrade.md b/docs/core/porting/upgrade-assistant-how-to-upgrade.md new file mode 100644 index 0000000000000..1560f560b3f05 --- /dev/null +++ b/docs/core/porting/upgrade-assistant-how-to-upgrade.md @@ -0,0 +1,99 @@ +--- +title: How to upgrade a project with .NET Upgrade Assistant +description: "Learn how to upgrade one or more projects with .NET Upgrade Assistant using either Visual Studio or a terminal." +author: adegeo +ms.author: adegeo +ms.topic: how-to +ms.date: 10/08/2024 + +#customer intent: As a developer, I want to upgrade my project to take advantage of the latest version of .NET. + +--- + +# Upgrade projects with .NET Upgrade Assistant + +The focus of this article is to provide the basic steps to upgrade a project with .NET Upgrade Assistant. This involves initiating the upgrade and reviewing the results. Based on how complex your project is, you might be required to perform manual updates to your code. + +Some project types have specific guidance on upgrading. For more information, see [Supported project types](upgrade-assistant-overview.md#supported-project-types). + +## Prerequisites + +- For Visual Studio, see [Install .NET Upgrade Assistant - Visual Studio extension](upgrade-assistant-install.md#visual-studio-extension) +- For the .NET Global Tool, see [Install .NET Upgrade Assistant - .NET Global Tool](upgrade-assistant-install.md#net-global-tool) + +## Upgrade a project in Visual Studio + +Follow these steps to upgrade a project in Visual Studio. + +1. Back up your code. +1. Open Visual Studio. +1. Open a project or solution. +1. In the **Solution Explorer** window, right-click on the **project** > **Upgrade**. + + :::image type="content" source="./media/upgrade-assistant-how-to-upgrade/vs-upgrade-right-click.png" alt-text="The Solution Explorer window in Visual Studio, showing the right-click menu of a project. The Upgrade menu item is highlighted."::: + +1. In the **Upgrade** tab, select the appropriate upgrade options. + + Based on the type of project and the target framework version, different options are presented. The following image shows two options when upgrading a Windows Forms for .NET Framework project. These options aren't displayed when upgrading a .NET project: + + :::image type="content" source="./media/upgrade-assistant-how-to-upgrade/vs-upgrade-welcome-framework.png" alt-text="The .NET Upgrade Assistant welcome screen in Visual Studio."::: + + In this example, select **Upgrade project to a newer .NET version**. + +1. Select how you want to perform the upgrade. Select **In-place project upgrade**, then select **Next**. + + Some projects may only present you with a single option. For more information about these options, see [How the upgrade should be performed](upgrade-assistant-overview.md#how-the-upgrade-should-be-performed). + + :::image type="content" source="./media/upgrade-assistant-how-to-upgrade/vs-upgrade-type.png" alt-text="The .NET Upgrade Assistant wizard showing the 'What is your upgrade type' selection. 'In-place project upgrade' is highlighted, as is the 'Next' button."::: + +1. Select the target framework, for example **.NET 8.0**. Then, select **Next**. + + :::image type="content" source="./media/upgrade-assistant-how-to-upgrade/vs-upgrade-target-framework.png" alt-text="The .NET Upgrade Assistant wizard showing the 'What is your preferred target framework' selection. '.NET 8.0' is highlighted, as is the 'Next' button."::: + +1. Select the components to upgrade, then select **Upgrade selection**. + + :::image type="content" source="./media/upgrade-assistant-how-to-upgrade/vs-upgrade-select-components.png" alt-text="The .NET Upgrade Assistant wizard showing the 'Select components to upgrade' selection. The list of components is highlighted, as is the 'Upgrade selection' button."::: + +1. Once the upgrade is complete, a list of processed items is shown. + + :::image type="content" source="./media/upgrade-assistant-how-to-upgrade/vs-upgrade-finished.png" alt-text="The .NET Upgrade Assistant wizard showing the summary screen. Each artifact processed by the upgrade is listed, with a status icon."::: + +Each artifact processed by the upgrade is listed, along with its status. For more information, see [Upgrade results](upgrade-assistant-overview.md#upgrade-results). + +## Upgrade a project from the CLI + +Follow these steps to upgrade a project using the terminal. The .NET Global Tool is an interactive tool that guides you through the upgrade options. Use the Up arrow and Down arrow keys to change the highlighted option, and Enter to run the select the option. Each screen presents you options on how you want to configure the upgrade. + +1. Back up your code. +1. Open a terminal and navigate to the folder containing the solution or project you want to upgrade. +1. To start the tool, run the `upgrade-assistant upgrade` command. + + You're asked about what you want to upgrade. Depending on what is detected, some options might be automatically applied or missing entirely. + + :::image type="content" source="./media/upgrade-assistant-how-to-upgrade/cli-upgrade-start.png" alt-text="A terminal showing the initial screen of options for .NET Upgrade Assistant Global Tool. The question 'Which project do you want to upgrade' is being asked."::: + +1. If more than one project is found, choose one of the projects and press Enter. + + Upgrade projects in the order of their dependency. For example, the previous image showed two projects: `MatchingGame` and `MatchingGame.Logic`. `MatchingGame` is dependent on `MatchingGame.Logic`, so `MatchingGame.Logic` should be upgraded first. + +1. If you have an option to change the **Upgrade type**, choose one and press Enter. If only one option was available, it would have been automatically selected. + + For more information about these options, see [How the upgrade should be performed](upgrade-assistant-overview.md#how-the-upgrade-should-be-performed). + + > [!TIP] + > If you've backed up your code, it's safe to select **In-place project upgrade**. + +1. Choose a target framework, such as **.NET 8.0**, and press Enter. +1. The final prompt is a confirmation, displaying all of the options selected. Press Enter to start the upgrade. + + :::image type="content" source="./media/upgrade-assistant-how-to-upgrade/cli-upgrade-options-end.png" alt-text="A terminal showing the summary screen of options for .NET Upgrade Assistant Global Tool. The user is asked to continue."::: + +1. Once the upgrade finishes, a summary is shown. + + :::image type="content" source="./media/upgrade-assistant-how-to-upgrade/cli-upgrade-end.png" alt-text="A terminal showing the results of the upgrade command when using the .NET Upgrade Assistant Global Tool."::: + +## Related content + +- [What is .NET Upgrade Assistant?](upgrade-assistant-overview.md) +- [What is code analysis with .NET Upgrade Assistant?](upgrade-assistant-analyze-overview.md) +- [Analyze projects with .NET Upgrade Assistant](upgrade-assistant-how-to-analyze.md) diff --git a/docs/core/porting/upgrade-assistant-install-legacy.md b/docs/core/porting/upgrade-assistant-install-legacy.md deleted file mode 100644 index a07d80dbc4416..0000000000000 --- a/docs/core/porting/upgrade-assistant-install-legacy.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: How to use the legacy .NET Upgrade Assistant -description: This article describes how to install the old .NET Upgrade Assistant tool. -author: adegeo -topic: how-to -ms.date: 05/22/2023 ---- -# Use the legacy .NET Upgrade Assistant - -In this article you'll learn how to install and run the old version of the .NET Upgrade Assistant command-line interface (CLI) tool. Starting with version 0.5.2, the code base for the .NET Upgrade Assistant CLI tool was rebased on the Visual Studio extension. This means that there are effectively two different CLI tools, the version prior to 0.5.2 which is referred to as the legacy version, and the 0.5.2+ version which is the current version. - -The legacy version has some functionality that is not yet available in the new version such as analyze command or solution-level upgrades, but also lacks new improvements available in the new (0.5.2+) version. Therefore, you may want to use it until the current version increases in capability and scope. - -> [!TIP] -> The legacy version of the tool can upgrade solution files. - -## Install the legacy version - -The legacy version of the tool is installed the same way as the current version, except that you specify version `0.4.421302`: - -```dotnetcli -dotnet tool install upgrade-assistant -g --version 0.4.421302 -``` - -> [!IMPORTANT] -> Installing this tool may fail if you've configured additional NuGet feed sources. Use the `--ignore-failed-sources` parameter to treat those failures as warnings instead of errors: -> -> ```dotnetcli -> dotnet tool install upgrade-assistant -g --ignore-failed-sources --version 0.4.421302 -> ``` - -## Analyze your app - -The legacy version of the tool includes an analyze mode that performs a simplified dry run of upgrading your app. It may provide insights as to what changes may be required before the upgrade is started. Open a terminal and navigate to the folder where the target project or solution is located. Run the `upgrade-assistant analyze` command, passing in the name of the project or solution you're upgrading. - -For example, here's the output after running the analyze mode with the .NET Framework WPF app: - -```console -> upgrade-assistant analyze .\WebSiteRatings.sln - -[15:39:00 INF] Loaded 9 extensions -[15:39:02 INF] Using MSBuild from C:\Program Files\dotnet\sdk\7.0.201\ -[15:39:02 INF] Using Visual Studio install from C:\Program Files\Microsoft Visual Studio\2022\Preview [v17] -[15:39:05 INF] Writing output to C:\code\migration\AnalysisReport.sarif -[15:39:06 INF] Recommending Windows TFM net7.0-windows for project WebSiteRatings.csproj because the project either has Windows-specific dependencies or builds to a WinExe -[15:39:06 INF] Marking assembly reference System.Configuration for removal based on package mapping configuration System.Configuration -[15:39:06 INF] Adding package System.Configuration.ConfigurationManager based on package mapping configuration System.Configuration -[15:39:08 INF] Package EntityFramework, Version=6.2.0 does not support the target(s) net7.0-windows but a newer version (6.4.4) does. -[15:39:09 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.4.410601) needs to be added -[15:39:10 INF] Adding Microsoft.Windows.Compatibility 7.0.0 helps with speeding up the upgrade process for Windows-based APIs -[15:39:13 INF] Recommending Windows TFM net7.0-windows for project StarVoteControl.csproj because the project either has Windows-specific dependencies or builds to a WinExe -[15:39:13 INF] Reference to .NET Upgrade Assistant analyzer package (Microsoft.DotNet.UpgradeAssistant.Extensions.Default.Analyzers, version 0.4.410601) needs to be added -[15:39:13 INF] Adding Microsoft.Windows.Compatibility 7.0.0 helps with speeding up the upgrade process for Windows-based APIs -[15:39:13 INF] Running analyzers on WebSiteRatings -[15:39:14 INF] Identified 0 diagnostics in project WebSiteRatings -[15:39:14 INF] Running analyzers on StarVoteControl -[15:39:15 INF] Identified 0 diagnostics in project StarVoteControl -[15:39:15 INF] Analysis Complete, the report is available at C:\code\migration\AnalysisReport.sarif -``` - -There's quite a bit of internal diagnostic information in the output, but some information is helpful. Notice that the analyze mode indicates that during an upgrade the project's target framework moniker ([TFM](../../standard/frameworks.md)) is going to be set to `net7.0-windows` instead of `net7.0`. This recommendation is made because the projects referenced by the solution are WPF projects, a Windows-only technology. A console application would probably be upgraded directly to TFM `net7.0`, unless it used some Windows-specific library or code. - -## Run upgrade-assistant - -Open a terminal and navigate to the folder where the target project or solution is located. Run the `upgrade-assistant upgrade` command, passing in the name of the project or solution you're upgrading. - -When the tool runs, it displays a list of steps it performs to upgrade the project. As each step is completed, the tool provides a set of numbered commands allowing the user to apply or skip the next step. It may provide other options such as: - -- Get more information about the step. -- Change projects. -- Adjust logging settings. -- Stop the upgrade and quit. - -Pressing Enter without choosing a number selects the first item in the list. - -As each step initializes, the tool may provide information about what it thinks will happen if you apply the step. - -### Upgrade a solution - -When you upgrade a solution that contains multiple projects, you must select which project in the solution is the **entrypoint**. Based on the **entrypoint** project, a dependency graph is created to determine which projects to upgrade and in what order. If the solution contains projects that aren't a part of the dependency graph, they're ignored and you must upgrade these projects separately. Dependencies are upgraded first, then the **entrypoint** project. - -The next step is to choose which project to upgrade. You should see output similar to the following snippet: - -``` -Upgrade Steps - -1. [Next step] Select an entrypoint -2. Select project to upgrade - -Choose a command: - 1. Apply next step (Select an entrypoint) - 2. Skip next step (Select an entrypoint) - 3. See more step details - 4. Configure logging - 5. Exit -``` - -> [!TIP] -> Pay attention to the output of each step, as it may contain information about something the tool can't upgrade. Depending on the complexity of your app, you may have more upgrade work to do after the tool is finished. - -## Upgrade the project - -Once a project is selected, a list of upgrade steps is displayed. The first step is selected, which is to back up the project. The list of steps looks similar to the following snippet: - -``` -[15:50:50 INF] Initializing upgrade step Back up project - -Upgrade Steps - -Entrypoint: C:\code\migration\WebSiteRatings\WebSiteRatings.csproj -Current Project: C:\code\migration\WebSiteRatings\WebSiteRatings.csproj - -1. [Next step] Back up project -2. Convert project file to SDK style -3. Clean up NuGet package references - a. Duplicate reference analyzer - b. Package map reference analyzer - c. Target compatibility reference analyzer - d. Upgrade assistant reference analyzer - e. Windows Compatibility Pack Analyzer - f. MyDotAnalyzer reference analyzer - g. Newtonsoft.Json reference analyzer - h. Windows App SDK package analysis - i. Transitive reference analyzer -4. Update TFM -5. Update NuGet Packages - a. Duplicate reference analyzer - b. Package map reference analyzer - c. Target compatibility reference analyzer - d. Upgrade assistant reference analyzer - e. Windows Compatibility Pack Analyzer - f. MyDotAnalyzer reference analyzer - g. Newtonsoft.Json reference analyzer - h. Windows App SDK package analysis - i. Transitive reference analyzer -6. Add template files -7. Update WCF service to CoreWCF (Preview) -8. Upgrade app config files - a. Convert Application Settings - b. Convert Connection Strings - c. Disable unsupported configuration sections -9. Update source code - a. Apply fix for UA0002: Types should be upgraded - b. Apply fix for UA0012: 'UnsafeDeserialize()' does not exist -10. Move to next project - -Choose a command: - 1. Apply next step (Back up project) - 2. Skip next step (Back up project) - 3. See more step details - 4. Select different project - 5. Configure logging - 6. Exit -``` - -Each step first details what it's going to do, then prompts you to do it. Any step that doesn't apply, is skipped when the tool arrives to the step. For example, if the tool processes **7. Update WCF service to CoreWCF (Preview)**, but your app doesn't define a WCF service, it's skipped and step 8 is processed. In turn, if step 8 doesn't apply, it's skipped too. You may see many steps skipped as the tool tries to find the next step that applies. - -## Final steps - -After you upgrade your projects, you'll need to compile and test them. Most likely there's more work to do to finish the upgrade. It's possible that the .NET Framework version of your app contained library references that your project isn't actually using, and they were carried over. Analyze each reference and determine whether or not it's required. The tool may have also added or upgraded a NuGet package reference to wrong version. - -Finally, look for ways to modernize your app. For examples, see [Modernizations after upgrading to .NET from .NET Framework](modernize.md) diff --git a/docs/core/porting/upgrade-assistant-install.md b/docs/core/porting/upgrade-assistant-install.md index 0dc5b7f6b4a47..a4c04422e2e20 100644 --- a/docs/core/porting/upgrade-assistant-install.md +++ b/docs/core/porting/upgrade-assistant-install.md @@ -1,55 +1,93 @@ --- -title: How to install the .NET Upgrade Assistant -description: This article describes how to install the .NET Upgrade Assistant tool, which can be installed as a Visual Studio extension or a dotnet command-line tool. +title: Install .NET Upgrade Assistant +description: "Learn how to install .NET Upgrade Assistant as a Visual Studio extension or a .NET Global Tool. .NET Upgrade Assistant assists you when upgrading projects to the latest dependencies or when upgrading to a new .NET" author: adegeo -topic: how-to -ms.date: 05/22/2023 ---- -# Install the .NET Upgrade Assistant +ms.author: adegeo +ms.topic: install-set-up-deploy +ms.date: 10/08/2024 + +#customer intent: As a developer, I want to install .NET Upgrade Assistant so that I can upgrade my projects. + +--- + +# Install .NET Upgrade Assistant -The .NET Upgrade Assistant can be installed as a Visual Studio extension or as a .NET command-line tool. When installed as a Visual Studio extension, loaded projects can be upgraded through the context menu. The .NET command-line tool version of the tool provides an interactive step-by-step experience. For more information about the tool, see [Overview of the .NET Upgrade Assistant](upgrade-assistant-overview.md). +This article teaches you how to install .NET Upgrade Assistant using either the Visual Studio extension or the command-line interface (CLI) tool. -### Prerequisites +## Prerequisites - Windows Operating System -- [Visual Studio 2022 version 17.1 or later](https://visualstudio.microsoft.com/downloads/) -- [.NET SDK](https://dotnet.microsoft.com/download/dotnet/), for the command-line tool +- [Visual Studio 2022 version 17.1 or newer](https://visualstudio.microsoft.com/downloads/). +- [.NET SDK 8 or later](https://dotnet.microsoft.com/download/dotnet/). + +## Methods + +.NET Upgrade Assistant can be installed as a Visual Studio extension or as a .NET Global Tool. + +The Visual Studio extension runs inside Visual Studio, on the solution or project you have open. The .NET Global Tool is an interactive console application that runs on a solution or project file at or below the current directory. -## Install the Visual Studio extension +If you want the streamlined experience of opening a project in Visual Studio and upgrading it, install the extension. -The .NET Upgrade Assistant can be installed as a Visual Studio extension, which lets you upgrade an opened project. Use the following steps to install the .NET Upgrade Assistant from inside Visual Studio. Alternatively, you can download and install the extension from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.upgradeassistant). +## Visual Studio Extension -01. With Visual Studio opened, press the **Extensions** > **Manage Extensions** menu item, which opens the **Manage Extensions** window. -01. In the **Manage Extensions** window, enter *upgrade* into the search input box. -01. Select the **.NET Upgrade Assistant** item, and then select **Download**. +The following steps install the Visual Studio extension. + +> [!TIP] +> As an alternative to using the **Manage Extensions** feature of Visual Studio, you can download and run the extensions installer from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.upgradeassistant) + +01. Open Visual Studio. + + If the **Open Recent \ Get Started** window opens, select the **Continue without code** link. + +01. Select the **Extensions** > **Manage Extensions** menu to open the **Extension Manager** window. +01. Select the **Browse** tab. +01. Type **.NET upgrade assistant** into the search box. +01. Select the **.NET Upgrade Assistant** item, and then select **Install**. :::image type="content" source="media/upgrade-assistant-install/visual-studio-manage-extensions.png" alt-text="The manage extensions window in Visual Studio, showing the .NET Upgrade Assistant."::: -01. Once the extension has been downloaded, close Visual Studio. This starts the installation of the extension: +01. Once the extension finishes downloading, close Visual Studio to automatically start the installation. :::image type="content" source="media/upgrade-assistant-install/install-prompt.png" alt-text="A prompt to install the .NET Upgrade Assistant extension."::: -01. Select **Modify** and follow the directions to install the extension. +01. Select **Modify** and follow the instructions to install the extension. -## Install the .NET global tool +## .NET Global Tool -The .NET Upgrade Assistant is also available as a .NET global tool. You can install the tool with the following command: +The following steps install .NET Upgrade Assistant as a .NET Global Tool. .NET Upgrade Assistant is distributed in the [upgrade-assistant NuGet package](https://www.nuget.org/packages/upgrade-assistant). -```dotnetcli -dotnet tool install -g upgrade-assistant -``` +01. Open a command prompt that has the `dotnet` command in Path. +01. Run the following command to install the tool: -Similarly, because the .NET Upgrade Assistant is installed as a .NET tool, it can be easily updated by running: + ```dotnetcli + dotnet tool install -g upgrade-assistant + ``` -```dotnetcli -dotnet tool update -g upgrade-assistant -``` + > [!IMPORTANT] + > Installing this tool may fail if you've configured another NuGet feed source. Use the `--ignore-failed-sources` parameter to treat those failures as warnings instead of errors, bypassing those other NuGet feed sources: + > + > ```dotnetcli + > dotnet tool install -g --ignore-failed-sources upgrade-assistant + > ``` + +## Validation + +The following information helps you determine that .NET Upgrade Assistant is installed. + +- **Visual Studio Extension** + + There are two ways to determine if .NET Upgrade Assistant is installed as a Visual Studio extension. The quickest way is to right-click on any .NET or .NET Framework project in the **Solution Explorer** window and check for an **Upgrade** menu item. -> [!IMPORTANT] -> Installing this tool may fail if you've configured additional NuGet feed sources. Use the `--ignore-failed-sources` parameter to treat those failures as warnings instead of errors: -> -> ```dotnetcli -> dotnet tool install -g --ignore-failed-sources upgrade-assistant -> ``` + Another way is to select the **Extensions** > **Manage Extensions** menu to open the **Extension Manager** window. Then, select the **Installed** tab and find it in the list of installed extensions. -For upgrading projects with WCF components, use the older version of the CLI tool. For more information, see [Install (legacy version)](upgrade-assistant-install-legacy.md). +- **.NET Global Tool** + + Open a command prompt and run the `upgrade-assistant` command. If the command response indicates that the command is unknown, the tool didn't install correctly or isn't in PATH. + +## Troubleshoot - .NET Global Tool + +If you configured extra NuGet feed sources, the install might fail with an error indicating that the NuGet package isn't available in the feed. Use the `--ignore-failed-sources` parameter to treat those failures as warnings instead of errors, bypassing the other NuGet feed sources: + +```dotnetcli +dotnet tool install -g --ignore-failed-sources upgrade-assistant +``` diff --git a/docs/core/porting/upgrade-assistant-overview.md b/docs/core/porting/upgrade-assistant-overview.md index cb7aedd3a8b05..f24699fe5c78f 100644 --- a/docs/core/porting/upgrade-assistant-overview.md +++ b/docs/core/porting/upgrade-assistant-overview.md @@ -1,33 +1,44 @@ --- -title: Overview of the .NET Upgrade Assistant -description: Introducing the .NET Upgrade Assistant tool that helps upgrade .NET, .NET Core, or .NET Framework apps to the latest version of .NET. +title: .NET Upgrade Assistant Overview +description: "Learn more about .NET Upgrade Assistant for .NET-related projects. This tool helps you upgrade from older versions of .NET, including .NET Framework, to the latest version of .NET. Code incompatibilities can be fixed as part of the upgrade." author: adegeo -ms.date: 05/22/2023 -topic: overview -no-loc: ["appsettings.json", "App.config"] +ms.author: adegeo +ms.topic: overview +ms.date: 10/08/2024 + +#customer intent: As a developer, I want to upgrade my project so that I can take advantage of the latest features. + --- -# Overview of the .NET Upgrade Assistant -New versions of .NET are released throughout the year, with a major release once a year. The .NET Upgrade Assistant helps you upgrade apps from previous versions of .NET, .NET Core, and .NET Framework to the latest version. +# What is .NET Upgrade Assistant? + +.NET Upgrade Assistant helps upgrade projects to newer versions of .NET, and analyzes your code to spot and fix potential incompatibilities. One focus of the tool is to help migrate a project from .NET Framework, .NET Core, or .NET, to the latest version of .NET. You use the extension or tool to upgrade entire .NET projects, or some aspect of the project, such migrating a configuration file from an older type to a newer type. + +.NET Upgrade Assistant is distributed as a Visual Studio extension or a command-line interface (CLI) tool. + +## Analyze and upgrade + +.NET Upgrade Assistant includes an analysis engine that scans your projects and their dependencies. After the scan is complete, a report is generated with detailed information about performing an upgrade. You can use this information to upgrade either the entire project or specific parts of the project. -The .NET Upgrade Assistant is a Visual Studio extension and command-line tool that's designed to assist with upgrading apps to the latest version of .NET. + -The following types of projects are supported: +## Supported project types + +.NET Upgrade Assistant supports upgrading projects coded in either C# or Visual Basic. The following types of projects are supported: - ASP.NET - Azure Functions @@ -35,9 +46,17 @@ The following types of projects are supported: - Windows Forms - Class libraries - Console apps -- .NET Native UWP - Xamarin Forms - .NET MAUI +- .NET Native UWP + +Some products provide guidance on how to use .NET Upgrade Assistant. + +- [ASP.NET](/aspnet/core/migration/mvc) +- [Windows Presentation Foundation](/dotnet/desktop/wpf/migration/) +- [Windows Forms](/dotnet/desktop/winforms/migration/) +- [Universal Windows Platform](/windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/upgrade-assistant) +- [Windows Communication Foundation](../../core/porting/upgrade-assistant-wcf.md) ## Upgrade paths @@ -45,22 +64,19 @@ The following upgrade paths are supported: - .NET Framework to .NET - .NET Core to .NET +- Azure Functions v1-v3 to v4 isolated (targeting net6.0+) - UWP to WinUI 3 - Previous .NET version to the latest .NET version -- Azure Functions v1-v3 to v4 isolated - Xamarin Forms to .NET MAUI - XAML file transformations only support upgrading namespaces. For more comprehensive transformations, use Visual Studio 2022 version 17.6 or later. -## Upgrade with the Visual Studio extension +## Upgrade details and options -After you've [installed the .NET Upgrade Assistant extension](upgrade-assistant-install.md#install-the-visual-studio-extension), right-click on the project in the **Solution Explorer** window, and select **Upgrade**. +When an upgrade is started, a wizard walks you through configuring some of the options before the upgrade is initiated. Based on the type of project you're upgrading, the wizard presents different options. For an example of upgrading a project, see [Upgrade projects with .NET Upgrade Assistant](upgrade-assistant-how-to-upgrade.md). -> [!CAUTION] -> Make sure you backup your projects prior to upgrading if you're not using source control. +### How the upgrade should be performed -:::image type="content" source="media/upgrade-assistant-overview/visual-studio-upgrade.png" alt-text="The .NET Upgrade Assistant's Upgrade menu item in Visual Studio."::: - -A tab is opened which provides, based on your project type, different styles of upgrade: +Based on the type of project you're upgrading, you might be able to change how the upgrade is performed. The type of project affects which options are available, and one or more of the following items might be missing: - In-place project upgrade @@ -72,107 +88,30 @@ A tab is opened which provides, based on your project type, different styles of - Side-by-side incremental - A good choice for complicated web apps. Upgrading from ASP.NET to ASP.NET Core requires quite a bit of work and at times manual refactoring. This mode puts a .NET project next to your existing .NET Framework project, and routes endpoints that are implemented in the .NET project, while all other calls are sent to .NET Framework application. + This is a good choice for complicated web apps. Upgrading from ASP.NET to ASP.NET Core requires quite a bit of work and at times manual refactoring. This mode puts a .NET project next to the existing .NET Framework project. Endpoints are routed through the .NET project, while all other calls are sent to .NET Framework application. - This mode lets you slowly upgrade your ASP.NET or Library app piece-by-piece. + This mode lets you slowly upgrade your ASP.NET or library app piece-by-piece. -Once your app has been upgraded, a status screen is displayed which shows all of the artifacts related to your project that were associated with the upgrade. Each upgrade artifact can be expanded to read more information about the status. The following list describes the status icons: +### Upgrade results + +Once the upgrade is finished, a status screen is displayed which shows all of the artifacts associated with the upgrade. Each upgrade artifact can be expanded to read more information about the status. The following list describes the status icons: -- **Filled green checkmark**: The artifact was upgraded and completed successfully. - **Unfilled green checkmark**: The tool didn't find anything about the artifact to upgrade. +- **Filled green checkmark**: The artifact was upgraded and completed successfully. - **Yellow warning sign**: The artifact was upgraded, but there's important information you should consider. -- **Red _X_**: The artifact was to be upgraded, but the upgrade failed. +- **Red _X_**: The artifact upgrade was unsuccessful. :::image type="content" source="media/upgrade-assistant-overview/visual-studio-upgrade-results.png" alt-text="The .NET Upgrade Assistant's Upgrade results tab in Visual Studio."::: -Additionally, the actions the Upgrade Assistant performed are logged to the **Output** window under the **Upgrade Assistant** source, as shown in the following image: +Additionally, the actions the performed during the upgrade are logged to the **Output** window under the **Upgrade Assistant** source, as shown in the following image: :::image type="content" source="media/upgrade-assistant-overview/visual-studio-output-window.png" alt-text="The output window in Visual Studio showing the results from the .NET Upgrade Assistant."::: -After upgrading your project, you'll need to test it thoroughly. - -## Upgrade with the CLI tool - -After you've [installed the .NET Upgrade Assistant CLI tool](upgrade-assistant-install.md#install-the-net-global-tool), open a terminal window and navigate to the directory that contains the project you want to upgrade. You can use the `upgrade-assistant --help` command to see the available options the CLI provides. - -> [!CAUTION] -> Make sure you backup your projects prior to upgrading if you're not using source control. - -Run the tool with the `upgrade-assistant upgrade` command, all of the projects from the current folder and below, are listed. The CLI tool provides an interactive way of choosing which project to upgrade. Use the arrow keys to select an item, and press Enter to run the item. Select the project you want to upgrade. In the example provided by this article, there are four projects under the current folder: - -```txt - Selected options -─────────────────────────────────────────────────────────── - No options specified, follow steps below to continue - - Steps -───────────────── - Source project -───────────────── - -Which project do you want to upgrade (found 9)? - -> MatchingGame (winforms\MatchingGame\MatchingGame.csproj) - MatchingGame.Logic (winforms\MatchingGame.Logic\MatchingGame.Logic.csproj) - StarVoteControl (csharp\StarVoteControl\StarVoteControl.csproj) - WebSiteRatings (csharp\WebSiteRatings\WebSiteRatings.csproj) - - Navigation - Exit -``` - -Depending on the project you upgrade, you may be presented with an option to specify how the upgrade should proceed: - -- In-place project upgrade - - This option upgrades your project without making a copy. - -- Side-by-side project upgrade - - This option is only available for .NET Framework projects. Copies your project and upgrades the copy, leaving your original project alone. - -```txt - Selected options -────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── - Source project C:\Code\winforms\MatchingGame\MatchingGame.csproj - - Steps -─────────────────────────────── - Source project / Upgrade type -─────────────────────────────── - -How do you want to upgrade project MatchingGame? - -> In-place project upgrade - Side-by-side project upgrade - - Navigation - Back - Exit -``` - -After this step, if there's more than one upgradable target framework, you'll choose a target: - -```txt - Selected options -────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── - Source project C:\Code\Work\dotnet\dotnet-docs\docs\core\porting\snippets\upgrade-assistant-wpf-framework\winforms\MatchingGame\MatchingGame.csproj - Ugrade type Inplace - - Steps -────────────────────────────────────────────────── - Source project / Ugrade type / Target framework -────────────────────────────────────────────────── - -What is your preferred target framework? - -> .NET 6.0 (Supported until November, 2024) - .NET 7.0 (Supported until May, 2024) - .NET 8.0 (Try latest preview features) +After upgrading your project, test it thoroughly! - Navigation - Back - Exit -``` +## Related content -After upgrading your project, you'll need to test it thoroughly. +- [What is code analysis with .NET Upgrade Assistant?](upgrade-assistant-analyze-overview.md) +- [Install .NET Upgrade Assistant](upgrade-assistant-install.md) +- [Analyze projects with .NET Upgrade Assistant](upgrade-assistant-how-to-analyze.md) +- [Upgrade projects with .NET Upgrade Assistant](upgrade-assistant-how-to-upgrade.md) diff --git a/docs/core/porting/upgrade-assistant-wcf.md b/docs/core/porting/upgrade-assistant-wcf.md index ceecc92d09c23..2552866ed2151 100644 --- a/docs/core/porting/upgrade-assistant-wcf.md +++ b/docs/core/porting/upgrade-assistant-wcf.md @@ -1,13 +1,12 @@ --- -title: Upgrade WCF Server-side Project to use CoreWCF on .NET 6 -description: Use the .NET Upgrade Assistant to upgrade an existing WCF Server-side project on .NET Framework to use CoreWCF services on .NET 6. +title: Upgrade WCF Server-side Project to CoreWCF +description: Use .NET Upgrade Assistant to upgrade an existing WCF Server-side project on .NET Framework to use CoreWCF services on .NET 6 or later. author: SimonaLiao -ms.date: 09/01/2022 +ms.date: 10/08/2024 + --- -# Upgrade a WCF Server-side Project to use CoreWCF on .NET 6 -> [!IMPORTANT] -> This article was written before the release of the Upgrade Assistant extension for Visual Studio and it uses the legacy CLI tool. For more information, see [Use the legacy .NET Upgrade Assistant](upgrade-assistant-install-legacy.md). +# Upgrade a WCF Server-side Project to CoreWCF The .NET Upgrade Assistant is a command-line tool that can assist with upgrading an existing WCF Server-side project on .NET Framework to use CoreWCF services on .NET 6. This article provides: @@ -15,12 +14,13 @@ The .NET Upgrade Assistant is a command-line tool that can assist with upgrading - A demonstration of how to run the tool against a WCF Server-side project on .NET Framework. - Troubleshooting tips. -For more information on how to install the tool, see [Use the legacy .NET Upgrade Assistant](upgrade-assistant-install-legacy.md). - ## Things to know before starting This tool currently supports C# projects and uses [CoreWCF](https://github.com/corewcf/corewcf) to port self-hosted WCF Server-side projects to .NET 6. +> [!IMPORTANT] +> Upgrading WCF projects requires a legacy version of .NET Upgrade Assistant and isn't compatible with the latest versions. Instructions on how to install the legacy version are provided in the [Install the legacy version](#install-the-legacy-version) section. + For a WCF project to be applicable for this upgrade, it must meet the following requirements: 1. Includes a .cs file that references `System.ServiceModel` and creates new `ServiceHost`. @@ -35,6 +35,28 @@ The current version of the tool does not support WCF projects hosted via .svc fi > If your project is not applicable for this tool, we recommend you take a look at the [CoreWCF walkthrough guide](https://github.com/CoreWCF/CoreWCF/blob/main/Documentation/Walkthrough.md) and [BeanTrader Sample demo](https://devblogs.microsoft.com/dotnet/upgrading-a-wcf-service-to-dotnet-6/) and manually update the project. +## Prerequisites + +- Windows Operating System +- [Visual Studio 2022 version 17.1 or newer](https://visualstudio.microsoft.com/downloads/). +- [.NET SDK 6 or later](https://dotnet.microsoft.com/download/dotnet/). +- Version `0.4.421302` of .NET Upgrade Assistant, known as the "legacy" version. + +### Install the legacy version + +Use the `dotnet` command to install version `0.4.421302` of .NET Upgrade Assistant. + +```dotnetcli +dotnet tool install upgrade-assistant -g --version 0.4.421302 +``` + +> [!IMPORTANT] +> If you configured extra NuGet feed sources, the install might fail with an error indicating that the NuGet package isn't available in the feed. Use the `--ignore-failed-sources` parameter to treat those failures as warnings instead of errors, bypassing the other NuGet feed sources: +> +> ```dotnetcli +> dotnet tool install upgrade-assistant -g --ignore-failed-sources --version 0.4.421302 +> ``` + ## Demo app You can use the [Basic Calculator Sample][wcf-sample] project to test upgrading with the Upgrade Assistant, which is also the demo used in this documentation. @@ -168,7 +190,7 @@ Please choose a backup path The tool chooses a default backup path named after the current folder, but with `.backup` appended to it. You can choose a custom path as an alternative to the default path. For each upgraded project, the folder of the project is copied to the backup folder. In this example, the `CalculatorService` folder is copied from _CalculatorSample\CalculatorService_ to _CalculatorSample.backup\CalculatorService_ during the backup step: ```output -[10:25:53 INF] Backing up C:\Users\Desktop\CalculatorSample\CalculatorService to C:\Users\t-simonaliao\OneDrive - Microsoft\Desktop\CalculatorSample.backup\CalculatorService +[10:25:53 INF] Backing up C:\Users\Desktop\CalculatorSample\CalculatorService to C:\Users\OneDrive - Microsoft\Desktop\CalculatorSample.backup\CalculatorService [10:25:53 INF] Project backed up to C:\Users\Desktop\CalculatorSample.backup\CalculatorService [10:25:53 INF] Upgrade step Back up project applied successfully Please press enter to continue... diff --git a/docs/navigate/migration-guide/toc.yml b/docs/navigate/migration-guide/toc.yml index 3af07aae76855..b138b9b1e3c22 100644 --- a/docs/navigate/migration-guide/toc.yml +++ b/docs/navigate/migration-guide/toc.yml @@ -20,19 +20,31 @@ items: - name: Install href: ../../core/porting/upgrade-assistant-install.md displayName: upgrade assistant - - name: Install (legacy version) - href: ../../core/porting/upgrade-assistant-install-legacy.md + - name: How to upgrade + href: ../../core/porting/upgrade-assistant-how-to-upgrade.md displayName: upgrade assistant - - name: Windows Communication Foundation - href: ../../core/porting/upgrade-assistant-wcf.md - - name: Windows Presentation Foundation - href: /dotnet/desktop/wpf/migration/ - - name: Windows Forms - href: /dotnet/desktop/winforms/migration/ - - name: Universal Windows Platform - href: /windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/upgrade-assistant - - name: ASP.NET - href: /aspnet/core/migration/mvc + - name: Analyze + expanded: true + items: + - name: Overview + href: ../../core/porting/upgrade-assistant-analyze-overview.md + displayName: upgrade assistant + - name: How to analyze a project + href: ../../core/porting/upgrade-assistant-how-to-analyze.md + displayName: upgrade assistant + - name: Project upgrade guide + expanded: true + items: + - name: ASP.NET + href: /aspnet/core/migration/mvc + - name: Windows Presentation Foundation + href: /dotnet/desktop/wpf/migration/ + - name: Windows Forms + href: /dotnet/desktop/winforms/migration/ + - name: Universal Windows Platform + href: /windows/apps/windows-app-sdk/migrate-to-windows-app-sdk/upgrade-assistant + - name: Windows Communication Foundation + href: ../../core/porting/upgrade-assistant-wcf.md - name: Telemetry href: ../../core/porting/upgrade-assistant-telemetry.md - name: Breaking changes diff --git a/includes/deprecating-api-port.md b/includes/deprecating-api-port.md index fb4542253fb7f..54032811ce1a5 100644 --- a/includes/deprecating-api-port.md +++ b/includes/deprecating-api-port.md @@ -1,2 +1,2 @@ > [!NOTE] -> API Port has been deprecated in favor of binary analysis with the CLI version of the [.NET Upgrade Assistant](../docs/core/porting/upgrade-assistant-overview.md#upgrade-with-the-cli-tool) tool. The backend service of API Port has been shut down, so to use the tool, you must use it offline. For more information, see [.NET API Port README](https://github.com/microsoft/dotnet-apiport/blob/dev/docs/Console/README.md#run-the-tool-in-an-offline-mode). +> API Port has been deprecated in favor of binary analysis with the [.NET Upgrade Assistant](../docs/core/porting/upgrade-assistant-overview.md) tool. The backend service of API Port has been shut down, so to use the tool, you must use it offline. For more information, see [.NET API Port README](https://github.com/microsoft/dotnet-apiport/blob/dev/docs/Console/README.md#run-the-tool-in-an-offline-mode).