diff --git a/docs/core/porting/media/upgrade-assistant-install/visual-studio-modify-workloads.png b/docs/core/porting/media/upgrade-assistant-install/visual-studio-modify-workloads.png new file mode 100644 index 0000000000000..2590d88a6a888 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-install/visual-studio-modify-workloads.png differ diff --git a/docs/core/porting/media/upgrade-assistant-install/visual-studio-solution-explorer-modernize-menu.png b/docs/core/porting/media/upgrade-assistant-install/visual-studio-solution-explorer-modernize-menu.png new file mode 100644 index 0000000000000..a16490a52dea1 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-install/visual-studio-solution-explorer-modernize-menu.png differ diff --git a/docs/core/porting/media/upgrade-assistant-install/visual-studio-solution-explorer-upgrade-menu.png b/docs/core/porting/media/upgrade-assistant-install/visual-studio-solution-explorer-upgrade-menu.png new file mode 100644 index 0000000000000..5cbbc1e85ff74 Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-install/visual-studio-solution-explorer-upgrade-menu.png differ diff --git a/docs/core/porting/media/upgrade-assistant-install/visual-studio-tools-options-enable-legacy-upgrade-assistant.png b/docs/core/porting/media/upgrade-assistant-install/visual-studio-tools-options-enable-legacy-upgrade-assistant.png new file mode 100644 index 0000000000000..16ae73db3b8ae Binary files /dev/null and b/docs/core/porting/media/upgrade-assistant-install/visual-studio-tools-options-enable-legacy-upgrade-assistant.png differ diff --git a/docs/core/porting/upgrade-assistant-install.md b/docs/core/porting/upgrade-assistant-install.md index 08106083a28b1..75eafaa34d1c5 100644 --- a/docs/core/porting/upgrade-assistant-install.md +++ b/docs/core/porting/upgrade-assistant-install.md @@ -4,7 +4,7 @@ description: "Learn how to install .NET Upgrade Assistant as a Visual Studio ext author: adegeo ms.author: adegeo ms.topic: install-set-up-deploy -ms.date: 10/08/2024 +ms.date: 11/06/2025 #customer intent: As a developer, I want to install .NET Upgrade Assistant so that I can upgrade my projects. @@ -12,47 +12,66 @@ ms.date: 10/08/2024 # Install .NET Upgrade Assistant -This article teaches you how to install .NET Upgrade Assistant using either the Visual Studio extension or the command-line interface (CLI) tool. +This article teaches you how to enable .NET Upgrade Assistant in Visual Studio or install the tool using the command-line interface (CLI). [!INCLUDE [github-copilot-suggestion](includes/github-copilot-suggestion.md)] ## Prerequisites - Windows Operating System -- [Visual Studio 2022 version 17.1 or newer](https://visualstudio.microsoft.com/downloads/). +- [Visual Studio 2022 version 17.14.6 or newer](https://visualstudio.microsoft.com/downloads/). - [.NET SDK 8 or later](https://dotnet.microsoft.com/download/dotnet/). +> [!IMPORTANT] +> Starting with Visual Studio 2022 17.14.16, the GitHub Copilot app modernization agent is included with Visual Studio. And, the .NET Upgrade Assistant is installed along with that feature. If you're using an older version of Visual Studio 2022, upgrade to the latest release. +> +> If you installed any of the following extensions published by Microsoft, uninstall them before using the version now included in Visual Studio: +> +> - .NET Upgrade Assistant +> - GitHub Copilot App Modernization – Upgrade for .NET +> - Azure Migrate Application and Code Assessment for .NET + ## Methods -.NET Upgrade Assistant can be installed as a Visual Studio extension or as a .NET Global Tool. +.NET Upgrade Assistant is available as a feature in Visual Studio and it can be installed as a .NET Global Tool. + +The .NET Global Tool is an interactive console application that runs on a solution or project file at or below the current directory. + +If you want the streamlined experience of opening a project in Visual Studio and upgrading it, then enable the feature. + +## Enable the Visual Studio Feature -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. +The following sections are both required to enable the .NET Upgrade Assistant. -If you want the streamlined experience of opening a project in Visual Studio and upgrading it, install the extension. +### Enable the GitHub Copilot app modernization for .NET -## Visual Studio Extension +1. Open the Visual Studio installer +2. Click the Modify button next to your Visual Studio instance +3. On the Workloads tab + 1. Find the Installation details outline on the right side of the window + 2. Click the arrow to expand the ASP.NET and web development section + 3. Click the checkbox to install GitHub Copilot app modernization for .NET -The following steps install the Visual Studio extension. +![Visual Studio installation details shows GitHub Copilot app modernization for .NET as a feature under the ASP.NET and web development workload](./media/upgrade-assistant-install/visual-studio-modify-workloads.png) -> [!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). +When completed successfully. You can open a .NET solution in Visual Studio and will be able to see the Modernize menu option when you right-click a solution in the Solution Explorer. -01. Open Visual Studio. +![Visual Studio solution explorer shows modernize menu after right-click](./media/upgrade-assistant-install/visual-studio-solution-explorer-modernize-menu.png) - If the **Open Recent \ Get Started** window opens, select the **Continue without code** link. +### Enable the .NET Upgrade Assistant in Visual Studio -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**. +1. Click on the Tools -> Options menu item to open the Options window +2. Use the left-side to select Projects and Solutions -> Modernization +3. Select True to Enable legacy Upgrade Assistant - :::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."::: +![Visual Studio tools options dialog shows how to enable the .NET Upgrade Assistant](./media/upgrade-assistant-install/visual-studio-tools-options-enable-legacy-upgrade-assistant.png) -01. Once the extension finishes downloading, close Visual Studio to automatically start the installation. +> [!IMPORTANT] +> You will need to restart Visual Studio for this change to take effect. - :::image type="content" source="media/upgrade-assistant-install/install-prompt.png" alt-text="A prompt to install the .NET Upgrade Assistant extension."::: +When completed successfully. You can open a .NET solution in Visual Studio and will be able to see the Modernize menu option when you right-click a solution in the Solution Explorer. -01. Select **Modify** and follow the instructions to install the extension. +![Visual Studio solution explorer shows upgrade menu after right-click](./media/upgrade-assistant-install/visual-studio-solution-explorer-upgrade-menu.png) ## .NET Global Tool