From f6f3b7dcf708546a17a98e1298ffd7f296950862 Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Tue, 8 Oct 2024 13:09:37 -0700 Subject: [PATCH 1/7] Handle articles --- .../upgrade-assistant-analyze-overview.md | 118 +++++++++++++ .../upgrade-assistant-how-to-analyze.md | 86 ++++++++++ .../upgrade-assistant-how-to-upgrade.md | 100 +++++++++++ .../upgrade-assistant-install-legacy.md | 162 ------------------ .../core/porting/upgrade-assistant-install.md | 106 ++++++++---- .../porting/upgrade-assistant-overview.md | 157 ++++++----------- docs/core/porting/upgrade-assistant-wcf.md | 38 +++- 7 files changed, 458 insertions(+), 309 deletions(-) create mode 100644 docs/core/porting/upgrade-assistant-analyze-overview.md create mode 100644 docs/core/porting/upgrade-assistant-how-to-analyze.md create mode 100644 docs/core/porting/upgrade-assistant-how-to-upgrade.md delete mode 100644 docs/core/porting/upgrade-assistant-install-legacy.md 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..39231d0e18f0c --- /dev/null +++ b/docs/core/porting/upgrade-assistant-analyze-overview.md @@ -0,0 +1,118 @@ +--- +title: .NET Upgrade Assistant code analysis overview +description: "." +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 projects and code. The report contains information about potential issues and problems you may 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. + +## Custom configuration + +You can use a configuration file for the code analysis engine to control how the analysis is performed. + +## 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, which block the upgrade, or optional, which 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 individual panels: + +:::image type="content" source="./media/upgrade-assistant-analyze-overview/dashboard.png" alt-text="TODO"::: + +01. **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. + +01. **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="TODO"::: + +### 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="TODO"::: + +## Incident severity + +Each issue incident has an associated severity, which might block the upgrade. The severity helps you understand what has to be updated for the upgrade to succeed. + +| Severity | Description | +| --- | --- | +| Mandatory | Must be addressed. The upgrade process may handle these issues for you, such as updating the target framework runtime (TFM). | +| Optional | These shouldn't pose a problem with upgrading, but you may want to consider addressing them either before or after the upgrade. | +| Potential | Problems that if not addressed, have a chance of causing issues now or in the future. | +| 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 on resolving 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 | + + 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..111d4da2785b6 --- /dev/null +++ b/docs/core/porting/upgrade-assistant-how-to-analyze.md @@ -0,0 +1,86 @@ +--- +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 + +- Visual Studio - [Install .NET Upgrade Assistant - Visual Studio extension](upgrade-assistant-install.md#visual-studio-extension) +- Terminal - [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="TODO"::: + +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="TODO"::: + +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="TODO"::: + +1. Select the target framework, for example .NET 8.0. Select **Next**. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-target-framework.png" alt-text="TODO"::: + +1. Select the components to analyze, then select **Next**. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-components.png" alt-text="TODO"::: + +1. A progress indicator is displayed. Each project that's being processed, and the steps .NET Upgrade Assistant is taking, are listed. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-progress.png" alt-text="TODO"::: + +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="TODO"::: + +## 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 selected option, and Return to run the select the option. Each page presents you options on how you want to configure the report. + +> [!IMPORTANT] +> Visual Studio is used by .NET Upgrade Assistant. Even though you're running a .NET Global Tool from the terminal, you must have Visual Studio installed. + +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. You're asked about what you want to analyze. + + :::image type="content" source="./media/upgrade-assistant-how-to-analyze/cli-upgrade-start.png" alt-text="A terminal showing the initial page of options for .NET Upgrade Assistant Global Tool. The question 'What do you want to analyze' is being asked."::: + +1. Choose **Application sources** and press Return. +1. Choose a target framework, such as **.NET 8.0**, and press Return. +1. Select the types of items you want to scan. Use Spacebar to toggle the options, and then press Return. +1. On the **Config file** page, 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 Return. +1. Select the appropriate privacy mode, such as **Restricted** and press Return. +1. The final prompt is a confirmation, displaying all of the options you selected. Press Return 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 page 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) +- 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..c2ae72cced1c3 --- /dev/null +++ b/docs/core/porting/upgrade-assistant-how-to-upgrade.md @@ -0,0 +1,100 @@ +--- +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 general steps to upgrade a project with .NET Upgrade Assistant. The general steps involve 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 + +- Visual Studio - [Install .NET Upgrade Assistant - Visual Studio extension](upgrade-assistant-install.md#visual-studio-extension) +- Terminal - [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="TODO"::: + +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="TODO"::: + + In this example, select **Upgrade project to a newer .NET version**. + +1. Next, 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="TODO"::: + +1. Select the target framework, for example **.NET 8.0**. Select **Next**. + + :::image type="content" source="./media/upgrade-assistant-how-to-upgrade/vs-upgrade-target-framework.png" alt-text="TODO"::: + +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="TODO"::: + +1. A progress indicator is displayed. Each project that's being processed, and the steps .NET Upgrade Assistant is taking, are listed. + + :::image type="content" source="./media/upgrade-assistant-how-to-upgrade/vs-upgrade-progress.png" alt-text="TODO"::: + +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="TODO"::: + +Each artifact processed by the upgrade is listed, along with its status. For more information, see [Upgrade results](upgrade-assistant-overview.md#upgrade-results). + +## Create a report 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 selected option, and Return to run the select the option. Each page 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 be skipped or automatically applied. + + :::image type="content" source="./media/upgrade-assistant-how-to-upgrade/cli-upgrade-start.png" alt-text="A terminal showing the initial page of options for .NET Upgrade Assistant Global Tool. The question 'Which project do you want to upgrade' is being asked."::: + +1. Choose a project, if applicable, and press Return. +1. If you have an option to change the **Upgrade type**, choose one and press Return. + + 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, selecting **In-place project upgrade** is a safe option. + +1. Choose a target framework, such as **.NET 8.0**, and press Return. +1. The final prompt is a confirmation, displaying all of the options you selected. Press Return 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 page of options for .NET Upgrade Assistant Global Tool. The user is asked to continue."::: + +1. Once the upgrade finishes, the success of the upgrade is reported. + + :::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..880ee657da3dd 100644 --- a/docs/core/porting/upgrade-assistant-install.md +++ b/docs/core/porting/upgrade-assistant-install.md @@ -1,55 +1,97 @@ --- -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 uppgrading 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 tool is an interactive console application that runs on solution or project files. -## Install the Visual Studio extension +If you want the streamlined experience of opening a project in Visual Studio, then 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). +If you're familiar with running command-line tools, and want to process the upgrade step-by-step, install the .NET Global Tool. -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**. +## Visual Studio Extension + +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 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. -## 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 as 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. + + Another way to check if it's installed 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. -> [!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 -> ``` +- **.NET Global Tool** -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). + Open a command prompt and run the `upgrade-assistant` command. If the command response indicates that it doesn't know what that command is, the tool didn't install correctly or isn't in PATH. + +## Troubleshooting + +## .NET Global Tool + +If the install fails, reporting that the NuGet package isn't available in the feed, you may have 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 +``` diff --git a/docs/core/porting/upgrade-assistant-overview.md b/docs/core/porting/upgrade-assistant-overview.md index cb7aedd3a8b05..b8b514beda52c 100644 --- a/docs/core/porting/upgrade-assistant-overview.md +++ b/docs/core/porting/upgrade-assistant-overview.md @@ -1,33 +1,42 @@ --- -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? + +This article describes the different features of .NET Upgrade Assistant. .NET Upgrade Assistant helps upgrade projects to newer versions of .NET, and analyzes your code to spot and fix potential incompatibilities. The tool can be used to migrate a project from .NET Framework, .NET Core, or .NET, to the latest version of .NET. installed as a Visual Studio Extension, or installed as a command-line interface (CLI) tool. 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. + +## Analyze and upgrade + +.NET Upgrade Assistant includes an analysis engine that scans your project and dependencies, and provides a report with recommended steps if incompatibilities are detected. After you've analyzed a project, you can 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 +44,13 @@ 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 have written documentation that walks you through upgrading a project. + +- ## Upgrade paths @@ -45,22 +58,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 - -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**. +## Upgrade details and options -> [!CAUTION] -> Make sure you backup your projects prior to upgrading if you're not using source control. +When you start an upgrade, you're presented with a wizard that walks you through configuring some options before starting the upgrade. Based on the type of project you're upgrading, you'll experience different paths through the wizard. For an example of upgrading a project, see [Upgrade projects with .NET Upgrade Assistant](upgrade-assistant-how-to-upgrade.md). -:::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."::: +### How the upgrade should be performed -A tab is opened which provides, based on your project type, different styles of upgrade: +There are a few different ways to perform the upgrade on a project. Based on type of project you're upgrading, one or more of the following items may be missing from your list of options. - In-place project upgrade @@ -74,7 +84,9 @@ A tab is opened which provides, based on your project type, different styles of 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 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. + +### Upgrade results 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: @@ -89,90 +101,17 @@ Additionally, the actions the Upgrade Assistant performed are logged to the **Ou :::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 +After upgrading your project, test it thoroughly. - Steps -────────────────────────────────────────────────── - Source project / Ugrade type / Target framework -────────────────────────────────────────────────── + diff --git a/docs/core/porting/upgrade-assistant-wcf.md b/docs/core/porting/upgrade-assistant-wcf.md index ceecc92d09c23..b7dad6d6a83a7 100644 --- a/docs/core/porting/upgrade-assistant-wcf.md +++ b/docs/core/porting/upgrade-assistant-wcf.md @@ -1,13 +1,17 @@ --- -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 + +# Upgrade a WCF Server-side Project to CoreWCF > [!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). +> Upgrading WCF projects requires a legacy version of .NET Upgrade Assistant and isn't compatible with the latest versions. + +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). 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: @@ -35,6 +39,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] +> 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 +> ``` + ## 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 +194,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... From 7195f77123e579fdf414ff75de95009cb416e75c Mon Sep 17 00:00:00 2001 From: "Andy De George (adegeo)" Date: Tue, 8 Oct 2024 13:13:38 -0700 Subject: [PATCH 2/7] Handle images --- .../aggregate-issues.png | Bin 0 -> 39466 bytes .../dashboard.png | Bin 0 -> 45721 bytes .../projects.png | Bin 0 -> 29955 bytes .../cli-upgrade-end.png | Bin 0 -> 36003 bytes .../cli-upgrade-options-end.png | Bin 0 -> 37418 bytes .../cli-upgrade-start.png | Bin 0 -> 21873 bytes .../vs-upgrade-analyze-finished.png | Bin 0 -> 34954 bytes .../vs-upgrade-analyze-new-report.png | Bin 0 -> 19011 bytes .../vs-upgrade-analyze-progress.png | Bin 0 -> 17250 bytes .../vs-upgrade-analyze-right-click.png | Bin 0 -> 35271 bytes .../vs-upgrade-analyze-select-components.png | Bin 0 -> 25225 bytes .../vs-upgrade-analyze-select-projs.png | Bin 0 -> 19945 bytes .../vs-upgrade-analyze-target-framework.png | Bin 0 -> 29023 bytes .../cli-upgrade-end.png | Bin 0 -> 65597 bytes .../cli-upgrade-options-end.png | Bin 0 -> 28879 bytes .../cli-upgrade-start.png | Bin 0 -> 25253 bytes .../vs-upgrade-finished.png | Bin 0 -> 74856 bytes .../vs-upgrade-right-click.png | Bin 0 -> 35830 bytes .../vs-upgrade-select-components.png | Bin 0 -> 69117 bytes .../vs-upgrade-target-framework.png | Bin 0 -> 73441 bytes .../vs-upgrade-type.png | Bin 0 -> 66295 bytes .../vs-upgrade-welcome-framework.png | Bin 0 -> 71234 bytes .../visual-studio-manage-extensions.png | Bin 52815 -> 36331 bytes .../visual-studio-upgrade-results.png | Bin 43705 -> 76466 bytes 24 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/core/porting/media/upgrade-assistant-analyze-overview/aggregate-issues.png create mode 100644 docs/core/porting/media/upgrade-assistant-analyze-overview/dashboard.png create mode 100644 docs/core/porting/media/upgrade-assistant-analyze-overview/projects.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-analyze/cli-upgrade-end.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-analyze/cli-upgrade-options-end.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-analyze/cli-upgrade-start.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-finished.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-new-report.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-progress.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-right-click.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-components.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-select-projs.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-analyze/vs-upgrade-analyze-target-framework.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-upgrade/cli-upgrade-end.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-upgrade/cli-upgrade-options-end.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-upgrade/cli-upgrade-start.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-finished.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-right-click.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-select-components.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-target-framework.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-type.png create mode 100644 docs/core/porting/media/upgrade-assistant-how-to-upgrade/vs-upgrade-welcome-framework.png 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 0000000000000000000000000000000000000000..51aac1bfbf1c663aef01b61b2cce668d625bd763 GIT binary patch literal 39466 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