diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 717a62c31c..e437970bff 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -1,5 +1,10 @@ { "redirections": [ + { + "source_path": "docs/porting/copilot-app-modernization-cpp.md", + "redirect_url": "/cpp/porting/github-copilot-modernization-cpp/overview", + "redirect_document_id": true + }, { "source_path": "docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md", "redirect_url": "/previous-versions/cpp/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism", diff --git a/docs/porting/copilot-app-modernization-cpp.md b/docs/porting/copilot-app-modernization-cpp.md deleted file mode 100644 index d6e23461ba..0000000000 --- a/docs/porting/copilot-app-modernization-cpp.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "Modernize your C++ project with GitHub Copilot modernization" -description: "Instructions on effectively using GitHub Copilot modernization in your C++ projects" -ms.date: 03/12/2026 -ms.topic: upgrade-and-migration-article -author: michaelbprice -ms.author: miprice ---- - -# Using GitHub Copilot modernization for C++ - -GitHub Copilot modernization for C++ helps you upgrade C++ projects to newer MSVC Build Tools versions. If necessary, Copilot will upgrade your project's settings to use the latest MSVC, and then conduct a thorough assessment of the impact of those changes after executing a build. It develops a plan on how to address each identified problem. Once you approve the plan, the agent completes a sequence of tasks and validates that any changes resolved the identified problems. If there remains work to be done, the agent continues iterating until the problems are resolved or you discontinue the conversation. - -> [!NOTE] -> GitHub Copilot modernization for C++ is currently in preview. - -## Requirements - -- Visual Studio 2026 version 18.3 or later -- A GitHub Copilot account -- A MSBuild-based codebase (`.sln`, `.vcxproj`) OR a CMake-based codebase - -## Enable GitHub Copilot modernization for C++ - -GitHub Copilot modernization for C++ is enabled by default. To disable or explicitly enable the feature, follow these steps. - -1. From Visual Studio, select **Tools > Options...** to open the **Options** window. -1. Navigate to **All Settings > GitHub > Copilot > C/C++**. -1. Select (to enable) or clear (to disable) the checkbox for **Enable GitHub Copilot modernization for C++ (preview)**. -1. Restart Visual Studio for the setting change to take effect. - -:::image type="content" source="media/enable-copilot-app-modernization-cpp.png" alt-text="Screenshot of Visual Studio Options dialog. GitHub > Copilot > C/C++ settings are visible. The modernization for C++ checkbox is enabled." lightbox="media/enable-copilot-app-modernization-cpp.png"::: - -## Upgrade your codebase by using GitHub Copilot modernization for C++ - -This section describes how to start the Modernize agent and the stages it goes through to upgrade your codebase. - -### Start the Modernize agent - -GitHub Copilot modernization is an agent that operates inside the GitHub Copilot Chat window. You can start the agent in any of the following ways: - -- **From the Solution Explorer context menu**: Right-click on the solution or a loaded project in the Solution Explorer, and choose **Modernize** from the context menu. This automatically launches a GitHub Copilot Chat window, activates the Modernize agent, and provides you with relevant prompts to choose from to get you started. - -:::image type="content" source="media/copilot-app-modernization-context-menu.png" alt-text="Screenshot of Visual Studio Solution Explorer showing a right-click context menu with Modernize selected to start the Copilot agent."::: - -- **From GitHub Copilot Chat**: Open the GitHub Copilot Chat Window by selecting **View > GitHub Copilot Chat**. After the GitHub Copilot Chat window opens, mention `@Modernize` in a prompt to activate the Modernize agent. For example, type this prompt: - - `Use @Modernize to update MSVC Build Tools.` - -#### For MSBuild-based codebases targeting an earlier version of MSVC Build Tools - -The first time that you load a `.vcxproj` project that targets an earlier version of the MSVC Build Tools, you see an option to [upgrade project settings to use a newer version of the MSVC Build Tools](/visualstudio/install/setup-assistant). If you retarget any of your projects to a new version of MSVC Build Tools and GitHub Copilot modernization for C++ is enabled, you receive an infobar in Visual Studio prompting you to use GitHub Copilot modernization for C++ to resolve any newly introduced build problems. Selecting **Run GitHub Copilot modernization for C++** launches the GitHub Copilot Chat window, activates the Modernize agent, and provides you with relevant prompts to choose from to get you started. - -### Start the upgrade - -Once the Modernize agent is active, you can instruct it via a prompt to upgrade your MSVC Build Tools, or select the already constructed prompt from the list shown in the window. If you launched the agent directly in the GitHub Copilot Chat window by mentioning `@Modernize` in your prompt, you probably don't need to provide more prompting. - -:::row::: -:::column::: - -**MSBuild Projects** - -:::column-end::: -:::column::: - -**CMake Projects** - -:::column-end::: -:::row-end::: -:::row::: -:::column::: - -:::image type="content" source="media/app-modernization-msbuild-ice-breaker.png" alt-text="Screenshot of GitHub Copilot Chat window. The dropdown is set to Modernize experience and Upgrade MSVC Build Tools to the latest version is highlighted."::: - -:::column-end::: -:::column::: - -:::image type="content" source="media/app-modernization-cmake-ice-breaker.png" alt-text="Screenshot of GitHub Copilot Chat window. The dropdown is set to Modernize experience and Resolve build issues by migrating to modern alternatives is highlighted."::: - -:::column-end::: -:::row-end::: - - -### Assessment stage - -The agent first assesses what kinds of problems show up after upgrading. If you didn't already upgrade the project, the agent guides you through that process before creating its assessment. After ensuring that your project is upgraded, the agent builds your codebase, analyzes the reported warnings and errors, and generates an `assessment.md` file that describes the problems that it found, their severity, and other useful information. This is your opportunity to tell the agent any other context that could help it make a plan. - -One of the things you might choose to do here is to tell the agent not to fix certain discovered problems, because you know that resolving them involves some strategic decisions or because they were preexisting warnings that you decided are acceptable for your project. You should carefully read through the plan, making sure to provide that extra context where it is needed. Once you approve the assessment, the agent moves on to creating a concrete plan on addressing the problems. - -### Planning stage - -Based on the approved assessment and any other context or instructions you provide, the agent creates a `plan.md` file that proposes a detailed plan for resolving each of the identified problems. If the agent produces a plan that doesn't match your organization's coding style or practices, you can provide that guidance to the agent and have it solve the problem differently. After you agree on the plan, the agent moves to the execution stage. - -### Execution stage - -Now that the agent has a plan, it breaks down the necessary tasks to execute the plan. You can define these tasks as finely as you want. The tasks can even include steps to work on a branch or to commit specific changes together in the same commit. After making any changes, the agent builds the project again to confirm that the problems are resolved. If the problems aren't resolved, the agent iterates with you until they're resolved to your satisfaction. - -### Post-upgrade validation - -When the agent finishes, run the changes through any testing infrastructure you have. Have a colleague review the changes in a pull request. Since this feature is currently in preview, you might receive an infobar to complete a product survey to let the product team know how the agent performed on your codebase. The product team looks forward to hearing how they can improve the agent to solve your problems and accelerate your upgrade and modernization efforts. \ No newline at end of file diff --git a/docs/porting/github-copilot-modernization-cpp/faq.md b/docs/porting/github-copilot-modernization-cpp/faq.md new file mode 100644 index 0000000000..8a797d0953 --- /dev/null +++ b/docs/porting/github-copilot-modernization-cpp/faq.md @@ -0,0 +1,104 @@ +--- +title: "GitHub Copilot modernization for C++ FAQ" +description: "Frequently asked questions about GitHub Copilot modernization for C++." +author: michaelbprice +ms.author: miprice +ms.date: 05/27/2026 +ms.topic: faq +ai-usage: ai-assisted +--- + +# GitHub Copilot modernization for C++ FAQ + +This FAQ answers common questions C++ users might have about GitHub Copilot modernization. + +## General + +### What is GitHub Copilot modernization for C++? + +GitHub Copilot modernization for C++ is a GitHub Copilot agent for Visual Studio that helps you modernize and upgrade C++ projects to newer tools, libraries, and patterns. It recognizes specific tasks such as upgrading MSVC Build Tools to newer versions and provides additional tools and instructions to accomplish those tasks. It automates assessment, planning, and execution to accomplish the modernization task, and you can run it in a fully automated mode or a guided mode that allows you to approve each step and provide additional guidance. + +### What development environments are supported? + +GitHub Copilot modernization for C++ is available in Visual Studio 2026 version 18.7 and later. + +### Do I need a GitHub Copilot subscription? + +Yes. You need an active GitHub Copilot subscription to use the modernization agent. + +### Is my code sent to external services? + +GitHub Copilot processes code snippets according to [GitHub's Copilot privacy policy](https://docs.github.com/copilot/responsible-use-of-github-copilot-features/responsible-use-of-github-copilot-chat-in-your-ide). Code isn't retained beyond the immediate session. Workflow files such as `scenario-instructions.md` and `tasks.md` stay in your repository and aren't transmitted to external services. + +## MSVC upgrade scenarios + +### What project types are supported? + +The agent supports these project types: + +- MSBuild-based projects (`.sln` and `.vcxproj`). +- CMake-based projects. + +The agent does not currently support Unreal Engine projects (`.uproject`). + +### What does the agent actually change in my code? + +The agent modifies source code to resolve build errors and warnings introduced by upgrading to a newer version of MSVC Build Tools. Common changes include replacing deprecated APIs, fixing issues caused by using a more conformant compiler, updating include directives for removed or relocated headers, and resolving linker errors caused by library changes. When your project is in a git repository, all changes are committed so you can review and revert individual modifications. + +### Can I control what the agent changes? + +Yes. You can review and approve the plan before execution starts, tell the agent to skip specific issues or tasks, and provide preferences in `scenario-instructions.md`. You can also pause execution, redirect the agent, or revert any commit it makes. + +### Does the agent run tests? + +The agent validates changes by building the project after each task. If your project runs tests as part of the build, those tests run too. You can also tell the agent to skip test validation for specific tasks. + +### What if the agent makes a mistake? + +Stop the agent and tell it right away. It will adapt and apply corrections when you tell the agent to resume. You can also run `git revert HEAD`, ask the agent to try a different approach, or make a manual fix. + +For more information, see [Troubleshoot GitHub Copilot modernization for C++](./troubleshooting.md). + +### Can I upgrade only part of my solution? + +Yes. Tell the agent which projects to upgrade, for example, `Upgrade only the CoreLib project to the latest MSVC Build Tools.` The agent scopes its work to the projects you specify. + +## State and sessions + +### Where does the agent store its state? + +All state lives in `.github/upgrades/{SCENARIO ID}` inside your repository. This includes the assessment, plan, task progress, your preferences, and execution logs. + +### Can I resume an interrupted upgrade? + +Yes. You can close Visual Studio or end the chat session at any time. When you start a new conversation, the agent detects the existing state and picks up where it left off. + +### Should I commit the `.github/upgrades` folder? + +Yes. Committing the folder to your branch backs up upgrade progress, lets team members view the upgrade state, and helps the agent resume from the correct state. You can remove the folder after the upgrade is complete. + +### Can multiple people work on the same upgrade? + +The state files in `.github/upgrades` are shareable through Git. However, only one person should actively interact with the agent at a time to avoid conflicting changes. + +## Compatibility + +### Which MSVC Build Tools versions can I upgrade from? + +The agent supports upgrading from any earlier version of the MSVC Build Tools to the latest version supported by your Visual Studio installation. + +### Does the agent handle third-party library compatibility? + +The agent identifies third-party library compatibility issues during assessment. It suggests alternatives or workarounds when they're available. If a library isn't compatible with the target toolset, the agent documents the issue so you can decide how to proceed. + +### Can I use the agent with precompiled headers? + +Yes. The agent understands precompiled header configurations and accounts for them during the upgrade process. + +## Related content + +- [GitHub Copilot modernization for C++ overview](./overview.md) +- [Install GitHub Copilot modernization for C++](./install.md) +- [Scenarios and skills reference](./scenarios-and-skills.md) +- [Walkthrough - Hilo](./walkthrough-hilo.md) +- [Troubleshoot GitHub Copilot modernization for C++](./troubleshooting.md) diff --git a/docs/porting/github-copilot-modernization-cpp/install.md b/docs/porting/github-copilot-modernization-cpp/install.md new file mode 100644 index 0000000000..7aece28c21 --- /dev/null +++ b/docs/porting/github-copilot-modernization-cpp/install.md @@ -0,0 +1,54 @@ +--- +title: "Install GitHub Copilot modernization for C++" +description: "Set up GitHub Copilot modernization for C++ in Visual Studio to start upgrading your C++ projects." +ms.date: 6/11/2026 +ms.topic: how-to +author: michaelbprice +ms.author: miprice +ai-usage: ai-assisted +--- + +# Install GitHub Copilot modernization for C++ + +GitHub Copilot modernization helps you modernize your C++ codebase. Follow these steps to install the feature in Visual Studio. + +## Prerequisites + +- Windows operating system. +- [Visual Studio 2026 version 18.7 or later](https://aka.ms/vs/download). +- One or more of the following C++ development workloads: + - **Desktop development with C++** + - **Game development with C++** + - **Linux, Mac, and embedded development with C++** +- These optional components must be enabled: **GitHub Copilot**, **GitHub Copilot modernization** +- GitHub Copilot subscription (paid or free). +- [Sign in to Visual Studio with a GitHub account](/visualstudio/ide/work-with-github-accounts) that has [Copilot access](https://docs.github.com/copilot/get-started/plans#ready-to-choose-a-plan). +- Code written in C or C++ and in either a MSBuild-based codebase that uses `.sln` or `.vcxproj`, or a CMake-based codebase. Unreal Engine projects (`.uproject`) are not currently supported. + +## Verify your Visual Studio version + +If you need to update Visual Studio, select **Help** > **Check for Updates**, or download the latest version from [Visual Studio downloads](https://aka.ms/vs/download). + +## Enable or disable the feature + +GitHub Copilot modernization for C++ is enabled by default. To disable or explicitly enable the feature: + +1. In Visual Studio, select **Tools** > **Options** to open the **Options** dialog. +1. Navigate to **GitHub** > **Copilot** > **C/C++**. +1. Select the **Enable GitHub Copilot modernization for C++** checkbox to enable the feature, or clear it to disable the feature. +1. Restart Visual Studio for the setting change to take effect. + +## Verify the agent is available + +After setup, verify that the modernization agent is accessible: + +1. Open a C++ solution or project in Visual Studio. +1. Open **GitHub Copilot Chat** by selecting **View** > **GitHub Copilot Chat**. +1. Type `@Modernize` in the chat input. If the agent responds, setup is complete. + +Alternatively, right-click your solution or project in **Solution Explorer**. If **Modernize** appears in the context menu, the agent is ready. + +## Related content + +- [GitHub Copilot modernization for C++ overview](./overview.md) +- [Troubleshoot GitHub Copilot modernization for C++](./troubleshooting.md) diff --git a/docs/porting/github-copilot-modernization-cpp/overview.md b/docs/porting/github-copilot-modernization-cpp/overview.md new file mode 100644 index 0000000000..198394da51 --- /dev/null +++ b/docs/porting/github-copilot-modernization-cpp/overview.md @@ -0,0 +1,103 @@ +--- +title: "GitHub Copilot modernization for C++ overview" +description: "Learn how GitHub Copilot modernization helps you upgrade C++ projects to newer MSVC Build Tools versions through automated assessment, planning, and execution." +author: michaelbprice +ms.author: miprice +ms.date: 05/27/2026 +ms.topic: overview +ai-usage: ai-assisted +--- + +# What is GitHub Copilot modernization? + +GitHub Copilot modernization is a GitHub Copilot agent that helps you upgrade and modernize your C++ projects. It guides you through assessment, solution recommendations, code fixes, and validation within Visual Studio. + +## Scenarios + +The agent provides end-to-end modernization workflows called _scenarios_. Each scenario guides you through a specific type of modernization task. + +| Scenario | Description | Example prompt | +| --- | --- | --- | +| **MSVC Build Tools upgrade (MSBuild)** | Upgrades MSBuild-based projects (`.sln`, `.vcxproj`) to a newer version of MSVC Build Tools and resolves upgrade-related build issues. | _"Upgrade my projects to use the latest, installed version of the MSVC Build Tools"_ | +| **MSVC Build Tools upgrade (CMake)** | Resolves upgrade-related build issues in your CMake-based projects after configuring the project with a newer version of MSVC Build Tools. | _"Resolve any build issues caused by upgrading my project to use the newer MSVC Build Tools"_ | + +> [!NOTE] +> If you'd like to propose or upvote other modernization scenarios, visit [Developer Community](https://developercommunity.microsoft.com/cpp). + +For a full reference of all scenarios, see [Scenarios and skills reference](./scenarios-and-skills.md). + +## Prerequisites + +Before you start, make sure you have: + +- Visual Studio 2026 version 18.7 or later. +- A GitHub Copilot subscription. +- An MSBuild-based codebase (`.sln`, `.vcxproj`) or a CMake-based codebase. + +For detailed setup steps, see [Install GitHub Copilot modernization for C++](./install.md). + +## How it works + +To start the modernization workflow: + +1. Open your C++ project or solution in Visual Studio. +1. Start the agent: In **Solution Explorer**, right-click your solution or project and select **Modernize**. Or, in **GitHub Copilot Chat**, type `@Modernize`. +1. Tell the agent what to upgrade. + +If your Visual Studio installation is missing the MSVC Build Tools that your project currently uses, the Setup Assistant should appear when you load your project. You can use the Setup Assistant to either install the missing MSVC version or to retarget to the installed MSVC version. If you retarget any projects, you will get an infobar message that can launch you directly into the Modernize agent workflow. + +When you ask the agent to upgrade your project, it prompts you to create a new branch if you're in a Git repository. Then it runs a three-stage workflow. Each stage produces Markdown files under `.github/upgrades/{scenarioId}` in your repository so you can review what comes next before you continue. If `.github/upgrades/{scenarioId}` already exists from an earlier attempt, the agent asks whether you want to continue or start fresh. + +### Stage 1: Assessment + +The agent examines your project structure, dependencies, and code patterns and saves a comprehensive assessment to `assessment.md`. The agent also presents strategy decisions for your review, such as upgrade strategy and compatibility handling. + +### Stage 2: Planning + +The agent converts the assessment into a detailed specification. The `plan.md` file documents upgrade strategies, refactoring approaches, and risk mitigations. + +### Stage 3: Execution + +The agent breaks the plan into sequential tasks with validation criteria in `tasks.md`. Each task describes a single change and how the agent confirms it succeeded. + +## Flow modes + +The agent supports two flow modes: + +- **Automatic**: Works through all stages without pausing, stopping only at genuine blockers. This mode is best for straightforward upgrades. +- **Guided**: Pauses at each stage boundary for your review. This mode is best for larger or more complex upgrades. + +You can switch modes at any time by modifying `scenario-instructions.md` or by instructing the agent to switch modes. If running in **Automatic** mode, you may have to stop the agent with the Cancel button in the Copilot Chat prompt window and instruct the agent to resume in **Guided** mode. + +## State management + +The agent stores all state in `.github/upgrades/{scenarioId}`. + +| File | Purpose | +| --- | --- | +| `assessment.md` | Analysis of your solution. | +| `plan.md` | Ordered task plan. | +| `tasks.md` | Live progress dashboard. | +| `scenario-instructions.md` | Agent's persistent memory. | +| `execution-log.md` | Audit trail of all changes. | + +You can close Visual Studio and resume later. The agent picks up where it left off by reading the state files. + +> [!TIP] +> If you want to work on your upgrade over a longer period of time while doing other work, consider committing the `.github/upgrades` folder to your branch in distinct commits. The committed state serves as a backup and lets team members view upgrade progress. Distinct commits allow you to easily remove them from your local git history before merging your branch if you do not want them permanently committed to your repository. + +## Provide feedback + +Microsoft values your feedback and uses it to improve the agent. Leave feedback using either of these options: + +- In Visual Studio, use the [Suggest a feature](/visualstudio/ide/suggest-a-feature) and [Report a problem](/visualstudio/ide/report-a-problem) options. + +- File an issue on [Developer Community](https://developercommunity.visualstudio.com/cpp). + +## Related content + +- [Install GitHub Copilot modernization for C++](./install.md) +- [Scenarios and skills reference](./scenarios-and-skills.md) +- [Walkthrough - Hilo](./walkthrough-hilo.md) +- [Troubleshoot GitHub Copilot modernization for C++](./troubleshooting.md) +- [FAQ](./faq.md) diff --git a/docs/porting/github-copilot-modernization-cpp/scenarios-and-skills.md b/docs/porting/github-copilot-modernization-cpp/scenarios-and-skills.md new file mode 100644 index 0000000000..5e0959d12c --- /dev/null +++ b/docs/porting/github-copilot-modernization-cpp/scenarios-and-skills.md @@ -0,0 +1,84 @@ +--- +title: "GitHub Copilot modernization for C++ scenarios and skills" +description: "Reference of available upgrade scenarios and skills for GitHub Copilot modernization for C++." +ms.date: 05/27/2026 +ms.topic: reference +author: michaelbprice +ms.author: miprice +ai-usage: ai-assisted +--- + +# Scenarios and skills reference + +GitHub Copilot modernization agent provides managed, end-to-end modernization workflows called _scenarios_. Each scenario guides you through a specific type of activity in practical C++ modernization work. This page documents the available scenarios and skills so you can understand what the agent can do for your project. + +## Scenarios + +A _scenario_ is a managed workflow that guides you through a specific type of modernization activity. + +### How scenarios are discovered + +You don't need to memorize scenario names. The agent detects your project type and suggests the relevant scenario automatically. + +To list the scenarios the agent supports, ask _"What scenarios are available for my project?"_ in the GitHub Copilot chat window. + +### Available scenarios + +| Scenario | Project type | Description | Example prompt | +|---|---|---|---| +| **MSVC Build Tools upgrade (MSBuild)** | `.sln`, `.vcxproj` | Upgrades MSBuild-based projects (`.sln`, `.vcxproj`) to a newer version of MSVC Build Tools and resolves upgrade-related build issues. | _"Upgrade my projects to use the latest, installed version of the MSVC Build Tools"_ | +| **MSVC Build Tools upgrade (CMake)** | CMake | Resolves upgrade-related build issues in your CMake-based projects after configuring the project with a newer version of MSVC Build Tools. | _"Resolve any build issues caused by upgrading my project to use the newer MSVC Build Tools"_ | + +> [!NOTE] +> If you'd like to propose or upvote other modernization scenarios, visit [Developer Community](https://developercommunity.microsoft.com/cpp). + +#### MSVC Build Tools upgrade (MSBuild) + +This scenario handles the complete upgrade workflow for MSBuild-based C++ projects: + +1. **Retargeting**: Updates project settings to target the latest, installed MSVC Build Tools and Platform Toolset. +1. **Build analysis**: Builds the solution and catalogs all errors and warnings introduced by the upgrade. +1. **Updating code**: Replaces deprecated APIs, addresses conformance issues, and helps with breaking changes. +1. **Validation**: Rebuilds to confirm all issues are resolved. + +For example, this scenario addresses issues like: + +- Deprecated CRT functions, for example, `sprintf` to `sprintf_s`. +- C++ conformance changes, for example, stricter template parsing. +- Standard library changes between MSVC versions, such as removed, experimental namespaces (e.g. `std::tr1`). +- Warning-as-error promotions in newer toolsets. +- Linker errors for APIs removed from the Windows SDK. + +#### MSVC Build Tools upgrade (CMake) + +This scenario handles upgrade workflows for CMake-based C++ projects: + +1. **Build analysis**: Builds the project and catalogs all errors and warnings introduced by the upgrade. +1. **Updating code**: Replaces deprecated APIs, addresses conformance issues, and helps with breaking changes. +1. **Validation**: Rebuilds to confirm all issues are resolved. + +For example, this scenario addresses issues like: + +- Deprecated CRT functions, for example, `sprintf` to `sprintf_s`. +- C++ conformance changes, for example, stricter template parsing. +- Standard library changes between MSVC versions, such as removed, experimental namespaces (e.g. `std::tr1`). +- Warning-as-error promotions in newer toolsets. +- Linker errors for APIs removed from the Windows SDK. + +### Scenario persistence + +Each active scenario gets its own folder at `.github/upgrades/{scenarioId}`. The scenario folder contains the plan, task progress, your preferences, and execution logs. The folder becomes part of your Git repository. + +## Skills + +_Skills_ are smaller, targeted modernization capabilities that the agent uses within a scenario. When the agent encounters a specific pattern during an upgrade, it loads the relevant skill with detailed instructions. + +Skills load automatically based on what the agent detects in your codebase. You don't need to manage skill loading. + +> [!NOTE] +> There are currently no additional skills specific to C++ modernization scenarios. + +## Related content + +- [GitHub Copilot modernization for C++ overview](./overview.md) +- [Troubleshoot GitHub Copilot modernization for C++](./troubleshooting.md) \ No newline at end of file diff --git a/docs/porting/github-copilot-modernization-cpp/troubleshooting.md b/docs/porting/github-copilot-modernization-cpp/troubleshooting.md new file mode 100644 index 0000000000..60278df965 --- /dev/null +++ b/docs/porting/github-copilot-modernization-cpp/troubleshooting.md @@ -0,0 +1,129 @@ +--- +title: "Troubleshoot GitHub Copilot modernization for C++" +description: "Solutions to common problems when using GitHub Copilot modernization to upgrade C++ projects." +ms.date: 05/27/2026 +ms.topic: troubleshooting +author: michaelbprice +ms.author: miprice +ai-usage: ai-assisted +--- + +# Troubleshoot GitHub Copilot modernization for C++ + +This article helps you resolve common issues when you use GitHub Copilot modernization to upgrade your C++ projects. If you run into a problem that isn't covered here, use **Help** > **Send Feedback** > **Report a problem** in Visual Studio. + +## Before you start + +### Verify that your solution or project builds + +For MSVC upgrade scenarios, the agent validates changes by building your solution or project. If your solution or project is already broken before you start, the agent will have greater difficulty distinguishing pre-existing issues from problems introduced by the upgrade. + +If you have known build issues, document them in [custom instructions](https://docs.github.com/copilot/concepts/prompting/response-customization?tool=visualstudio), provide them in your response when the agent asks for context during the assessment stage, or add them to `scenario-instructions.md` so the agent knows to ignore them. + +### Commit or stash uncommitted work + +Start with a clean working directory. The agent makes commits as it works, and mixing uncommitted changes with the agent's modifications makes it harder to review or revert changes. + +```git +git stash +git status +``` + +### Back up non-Git repositories + +The agent can also work with folders that aren't under source control. If your project isn't in a Git repository, the agent skips branching and commit operations. Back up your project folder before you start so you can restore it if needed. + +> [!TIP] +> Consider initializing a local Git repository before you start, even if you don't push to a remote. This gives you a way to roll back individual changes and track progress step by step. +> +> Example: +> ```git +> git init +> git add +> git commit -m "Initial Commit" +> ``` +> +> When you and the agent are done, if you don't want to continue using git, just make sure the code currently in your working tree is what you want, and delete the `.git` directory in the directory where you ran `git init`. + +## Common problems + +### Agent doesn't appear in Copilot Chat + +**Symptoms**: Typing @Modernize in the GitHub Copilot chat window doesn't activate the agent, or **Modernize** doesn't appear in the **Solution Explorer** context menu. + +**Solutions**: + +1. Verify that Visual Studio is version 18.7 or later in **Help** > **About Microsoft Visual Studio**. +1. Verify that GitHub Copilot is active by checking for the Copilot icon in the status bar. +1. Check that the feature is enabled in **Tools** > **Options** > **GitHub** > **Copilot** > **C/C++**. Then select **Enable GitHub Copilot modernization for C++**. +1. Restart Visual Studio after you change settings. + + +### Agent gets stuck in a loop + +**Symptoms**: The agent repeatedly tries the same fix without making progress. + +**Solutions**: + +- Stop the agent with the cancel button in the Copilot Chat prompt window, describe what you're observing in the prompt, and send the prompt to resume the agent. +- Provide a manual fix, and tell the agent what you changed. The agent learns from your correction. +- Ask the agent to try a different approach. For example, type in the GitHub Copilot chat window: _"That fix isn't working. Try a different strategy."_ +- If needed, revert or undo the last changes, and restart the task. + +### Large solutions take too long + +**Symptoms**: The upgrade of a large solution with many projects takes a very long time or seems to stall. + +**Solutions**: + +- Start with one representative project as a pilot. This surfaces systemic issues early. +- Monitor progress by reviewing `tasks.md` in `.github/upgrades/{SCENARIO ID}`. +- If a session times out, start a new session. The agent picks up where it left off. + +## Recovery strategies + +### Undo all changes + +If you used a Git branch for the upgrade, undo everything: + +```git +git checkout your-original-branch +git branch -D upgrade-branch +``` + +Your original code is untouched. + +### Undo the last change + +Revert the most recent commit: + +```git +git revert HEAD +``` + +Or tell the agent, `Revert the last change.` + +### Restart from a specific stage + +If the agent's plan isn't working, restart from an earlier stage by sending a prompt similar to: + +- `Let's redo the plan. I want a different approach to the conformance issues.` +- `Go back to the assessment and reconsider the upgrade strategy.` + +### Start fresh + +Delete the `.github/upgrades/{SCENARIO ID}` folder, and start a new conversation with the agent. It begins from scratch. + +## Get help + +If you can't resolve an issue: + +1. Use **Help** > **Send Feedback** > **Report a problem** in Visual Studio. +1. Include the contents of `execution-log.md` from `.github/upgrades/{SCENARIO ID}` if possible. + +## Related content + +- [Install GitHub Copilot modernization for C++](./install.md) +- [GitHub Copilot modernization for C++ overview](./overview.md) +- [Walkthrough - Hilo](./walkthrough-hilo.md) +- [FAQ](./faq.md) diff --git a/docs/porting/github-copilot-modernization-cpp/walkthrough-hilo.md b/docs/porting/github-copilot-modernization-cpp/walkthrough-hilo.md new file mode 100644 index 0000000000..f27161c2f8 --- /dev/null +++ b/docs/porting/github-copilot-modernization-cpp/walkthrough-hilo.md @@ -0,0 +1,167 @@ +--- +title: "Walkthrough: Using GitHub Copilot modernization for C++ to upgrade MSVC for the sample Hilo project" +description: "Demonstrates how to use GitHub Copilot to upgrade the Hilo sample project to use the most recent version of the MSVC Build Tools." +author: michaelbprice +ms.author: miprice +ms.date: 06/04/2026 +ms.topic: overview +ai-usage: ai-assisted +--- + +# Walkthrough: Upgrading Microsoft C++ (MSVC) Build Tools for the Hilo sample project + +This walkthrough shows how to use GitHub Copilot to modernize the Hilo sample project by upgrading it to the latest MSVC Build Tools. You'll use the modernization agent to identify and resolve issues, then use the Debugger agent to fix a runtime problem. + +## About Hilo + +Hilo was a sample project developed by Microsoft in 2012 to demonstrate creating applications targeting Windows 8 using "modern" C++, XAML, and the Windows Runtime. The Hilo application is a photo browsing application that also includes annotation and sharing features. We stopped updating the sample in 2015 and archived the source code for this sample and other previously shipped C++ samples in the [VCSamples GitHub repository](https://github.com/microsoft/VCSamples). + +![Screenshot of the main Hilo application window showing the contents of the user's Pictures folder.](../media/walkthrough-hilo-window.png) + +## Modernization challenges + +There are several issues that the agent discovers and resolves after upgrading Hilo to use a newer MSVC Build Tools version. Here are the issues when building with Microsoft C++ (MSVC) Build Tools version 14.51. + +- The `std::tr1::is_base_of` class template is used in several places, but is no longer available in MSVC's C++ standard library since `is_base_of` class template was promoted to be a part of the full standard. This is a blocking error. +- The `ID2D1Factory::GetDesktopDpi` function is deprecated. +- The`[uuid(_string_)]`syntax for ATL attributes on types is deprecated. +- There's a project that the Setup Assistant fails to upgrade. If you don't have the v120 MSVC Build Tools installed (which is likely), then this is a blocking error. +- There's a pointer truncation in window handling code that causes a runtime memory access exception. + +There are a few other warnings that may not be strictly related to the upgrade, but that the agent can optionally fix. These warnings include: + +- Narrowing warnings around multi-byte character strings and wide character strings. +- A typo in the name of an output file in a custom build step. + +## Setup + +### Install development tools + +In order to complete this walkthrough, you need to follow the [installation directions for the GitHub Copilot modernization agent for C++](./install.md). + +### Clone the repository + +Open Visual Studio and from the Start Window select **Clone a repository**. If the Start Window didn't appear, you can open it via **File** > **Start Window**. + +![Screenshot of the Visual Studio Start Window with the Clone a repository link highlighted.](../media/walkthrough-hilo-vs-start-window.png) + +For repository location, enter: **https://github.com/microsoft/VCSamples.git**. Choose an appropriate path on your system to clone the repository to and click the **Clone** button + +![Screenshot of the Visual Studio Clone a repository window with necessary fields completed and the Clone button highlighted.](../media/walkthrough-hilo-clone-window.png) + +## Start the upgrade + +### Load Hilo.sln in Visual Studio + +After you clone the repository, load the solution file at the `/VC2013Samples/Hilo/C++/Hilo.sln`. We're using the version that shipped with Visual Studio 2013 for this walkthrough. + +### Use the Setup Assistant to upgrade project files + +If you don't have the v120 tools installed, Visual Studio should launch the Setup assistant window to guide you through dealing with the missing components. When you see this window, you should choose to **Retarget all** and click **Apply**. If the window doesn't appear, you can open it from the file menu by clicking **Project** > **Retarget solution**. + +![Screenshot of the Setup assistant window showing the Hilo projects. All are selected for retargeting and the Apply button is highlighted.](../media/walkthrough-hilo-setup-assistant.png) + +### Launch the Copilot modernization agent + +After the Setup assistant has retargets the project, you should receive an infobar message with a link to start the modernization agent. Clicking the `Run GitHub Copilot modernization for C++` link starts the upgrade process. + +![Screenshot of the infobar message in Visual Studio for launching the modernization agent.](../media/walkthrough-hilo-infobar.png) + +If the infobar doesn't appear, you can launch the agent by right clicking the solution in the **Solution Explorer** and clicking **Modernize**. If you go that route, you can start the upgrade by sending the prompt `I just updated MSVC Build Tools. Resolve any upgrade issues.` to Copilot Chat. + +## Working with the agent + +### How to interact with the agent to get the best results + +The .NET modernization agent shares the same underlying interaction model as the C++ agent. The [Work with the modernization agent](/dotnet/core/porting/github-copilot-app-modernization/working-with-agent) documentation for .NET covers the general patterns in detail. Keep in mind that the examples and scenarios in that article are .NET-specific and don't apply directly to C++. + +For C++ upgrades, a few more tips can help the agent perform well: + +- **Be specific about scope.** Rather than asking the agent to upgrade everything at once, tell it which projects, libraries, or diagnostics to focus on. For example: _"Fix the C4996 deprecation warnings in the `NetworkClient` project."_ +- **Describe the diagnostics you expect the agent to fix.** If you know the specific warning or error codes introduced by the toolset upgrade, tell the agent upfront. These additional instructions help the agent prioritize and avoids time being spent on unrelated issues. +- **Make sure C/C++ code editing tools are enabled.** Verify the required tools are available in your setup before starting. For details, see [C/C++ code editing tools](/visualstudio/ide/copilot-agent-mode#c-code-editing-tools). +- **Encode coding conventions using custom instructions.** Encode guidelines such as naming conventions, preferred APIs, or patterns to avoid, in [custom instructions](https://docs.github.com/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot). The agent reads and follows these instructions throughout the upgrade. Useful C++ examples include conventions like _"Prefer `auto` where the type is obvious"_ and _"Follow Rule of Zero (or Rule of Three/Five where resource ownership requires it)."_ + +## Expected behaviors + +> [!NOTE] +> Due to the nature of LLM-based AI agents, the steps that the agent takes and the output it produces may differ from what is shown here. + +### Pre-assessment + +The agent first determines the environment that it's running in, such as your source control system, and to understand its goal. In our case, it detects that you're trying to upgrade your project to use the latest MSVC and initializes the appropriate scenario. It creates a `scenario.md` file and a `scenario-instructions.md` file to contain metadata about the scenario. + +These files contain information such as whether the agent should operate in **Automatic** or **Guided** mode, what the strategy for making commits is, and other information that affects _how_ the agent should proceed. If you express any preferences later on during the operation of the agent, the agent may add those preferences to the `scenario-instructions.md` file. + +![Screenshot of the contents of a scenario-instructions.md file.](../media/walkthrough-hilo-scenario-instructions.png) + +### Assessment + +After initialization, the agent does an assessment of the project by doing a clean rebuild of the project and inspecting the build output for errors and warnings. Using that information, and context the agent collects from the repository, it produces an `assessment.md` file that describes the issues that it found and whether or not it considers them to be in-scope or out-of-scope for the upgrade task. + +![Screenshot of the rendered contents of an assessment.md file.](../media/walkthrough-hilo-assessment.png) + +If the agent is operating in **Guided** mode, the agent stops here and requests your review of the assessment. Make any desired changes by prompting the agent or by editing the Markdown file directly, and then to continue on to the _Planning_ stage. If the agent is operating in **Automatic** mode, the agent continues on to the next stage automatically. If you want to change something, you need to stop the agent by pressing the cancel button, make the changes, and resume the agent by typing the prompt _"Resume"_ in the Copilot chat window. + +The assessment identifies several of the issues mentioned earlier in the walkthrough. Some issues don't appear until later since they're hidden by existing errors. Don't worry, they're discovered later on. If you'd like for the agent to pause to get your approval for any late-discovered issues, you can specify those instructions in your `scenario-instructions.md` file. + +### Planning + +Once the agent starts the Planning stage, it does a deeper analysis of the in-scope issues and proposes possible solutions in a generated `plan.md` file. It also generates a `tasks.md` file that provides more structured steps and instructions for executing the plan. + +![Screenshot of the rendered contents of a plan.md file.](../media/walkthrough-hilo-plan.png) + +Like with Assessment, what the agent does depends on if it's operating in **Guided** or **Automatic** mode. If running in **Guided** mode, the agent gives you the opportunity to direct it to fix issues in certain ways or even to ask it to come up with alternative options with more detailed descriptions of trade-offs. You can also specify other constraints such as coding conventions or special validation steps for some issues. + +### Execution + +After you approve the plan (or once Planning is completed in **Automatic** mode), the agent moves to the Execution stage. Here, it begins handling the tasks that it has in front of it, adapting to new information discovered while executing. With careful observation, you'll see that the agent discovers the previously hidden issues and adjusts its plan accordingly. + +![Screenshot of the agent in the middle of the Execution stage, reacting to newly discovered issues.](../media/walkthrough-hilo-execution.png) + +The end result of the Execution stage is a series of commits to your repository that resolve the in-scope issues, and a project that can now build successfully. However, a clean compilation is just one of the steps towards upgrading your project. It also needs to run correctly. + +## Use the Debugger agent to resolve runtime issues + +### Launch the Browser + +In the **Solution Explorer**, right-click the **Browser** project and click **Set as startup project**. Then launch a debugger session of the Hilo Browser by pressing **F5** or selecting **Debug** > **Start Debugging** from the file menu. + +The debugging session should almost immediately break on an unhandled memory access exception. + +:::image type="content" source="../media/walkthrough-hilo-exception.png" alt-text="Screenshot of the memory read access exception when first launching the Hilo browser." lightbox="../media/walkthrough-hilo-exception.png"::: + +### Examine memory read access exception + +We're going to use the Debugger agent to analyze this exception and implement a fix. Click on the **Analyze with Copilot** button on the exception information window to launch the Debugger agent. + +![Screenshot of the exception window for the Hilo browser with the Analyze with Copilot button highlighted.](../media/walkthrough-hilo-analyze-with-copilot.png) + +The Debugger agent uses debug and program state information to determine the root cause of runtime errors and then analyzes the source code to implement a solution. In this case, the agent identifies that the invalid memory access is due to an improper cast operation that truncated a 64-bit pointer to only 32 bits. That pointer is now invalid and points at an invalid memory location, which causes the exception. It proposes a different method of getting the correct type and avoids the truncation. + +### Apply changes + +Accept the changes it suggests, stop the debugging session by pressing *Shift + F5**, and then start a new session by pressing **F5**. The project is recompiled with the change and Visual Studio launches the updated application. You should now see the Hilo Browser window appear. + +![Screenshot of the main Hilo application window showing the contents of the user's Pictures folder.](../media/walkthrough-hilo-window.png) + +If you spend time exploring the application, you may discover more runtime issues. We leave any other issues as exercises for the reader. Just remember to use your new agentic tools to get to your end goal faster. + +## Summary + +This walkthrough demonstrated how GitHub Copilot agents can significantly accelerate the modernization of older C++ projects. The modernization agent and debugger agent can work together to streamline the upgrade process from initial assessment through runtime validation. + +### Key benefits + +- **Automated problem detection**: The agents systematically identify breaking changes, deprecations, and compatibility issues that arise from upgrades. +- **Intelligent solutions**: Rather than requiring manual fixes, the agents analyze code context and propose appropriate solutions tailored to your codebase. +- **Efficiency**: What might take days or weeks of manual work is completed in hours, with the agent handling both build errors and runtime issues. +- **Guided or automatic modes**: Choose between hands-on guidance or fully automated execution based on your comfort level and project requirements. +- **Learning and adaptation**: The agents discover hidden issues as they progress and adjust their approach accordingly, ensuring comprehensive coverage. + +## Related content + +- [GitHub Copilot modernization for C++ overview](./overview.md) +- [Install GitHub Copilot modernization for C++](./install.md) +- [Troubleshoot GitHub Copilot modernization for C++](./troubleshooting.md) +- [FAQ](./faq.md) diff --git a/docs/porting/media/walkthrough-hilo-analyze-with-copilot.png b/docs/porting/media/walkthrough-hilo-analyze-with-copilot.png new file mode 100644 index 0000000000..7e410c8945 Binary files /dev/null and b/docs/porting/media/walkthrough-hilo-analyze-with-copilot.png differ diff --git a/docs/porting/media/walkthrough-hilo-assessment.png b/docs/porting/media/walkthrough-hilo-assessment.png new file mode 100644 index 0000000000..7dba9355ac Binary files /dev/null and b/docs/porting/media/walkthrough-hilo-assessment.png differ diff --git a/docs/porting/media/walkthrough-hilo-clone-window.png b/docs/porting/media/walkthrough-hilo-clone-window.png new file mode 100644 index 0000000000..5e0e43934c Binary files /dev/null and b/docs/porting/media/walkthrough-hilo-clone-window.png differ diff --git a/docs/porting/media/walkthrough-hilo-exception.png b/docs/porting/media/walkthrough-hilo-exception.png new file mode 100644 index 0000000000..7178496127 Binary files /dev/null and b/docs/porting/media/walkthrough-hilo-exception.png differ diff --git a/docs/porting/media/walkthrough-hilo-execution.png b/docs/porting/media/walkthrough-hilo-execution.png new file mode 100644 index 0000000000..645956927e Binary files /dev/null and b/docs/porting/media/walkthrough-hilo-execution.png differ diff --git a/docs/porting/media/walkthrough-hilo-infobar.png b/docs/porting/media/walkthrough-hilo-infobar.png new file mode 100644 index 0000000000..30161f7018 Binary files /dev/null and b/docs/porting/media/walkthrough-hilo-infobar.png differ diff --git a/docs/porting/media/walkthrough-hilo-plan.png b/docs/porting/media/walkthrough-hilo-plan.png new file mode 100644 index 0000000000..2bc0aaf0cd Binary files /dev/null and b/docs/porting/media/walkthrough-hilo-plan.png differ diff --git a/docs/porting/media/walkthrough-hilo-scenario-instructions.png b/docs/porting/media/walkthrough-hilo-scenario-instructions.png new file mode 100644 index 0000000000..89c00cb9e2 Binary files /dev/null and b/docs/porting/media/walkthrough-hilo-scenario-instructions.png differ diff --git a/docs/porting/media/walkthrough-hilo-setup-assistant.png b/docs/porting/media/walkthrough-hilo-setup-assistant.png new file mode 100644 index 0000000000..4dabcdcb7f Binary files /dev/null and b/docs/porting/media/walkthrough-hilo-setup-assistant.png differ diff --git a/docs/porting/media/walkthrough-hilo-vs-start-window.png b/docs/porting/media/walkthrough-hilo-vs-start-window.png new file mode 100644 index 0000000000..f791838f47 Binary files /dev/null and b/docs/porting/media/walkthrough-hilo-vs-start-window.png differ diff --git a/docs/porting/media/walkthrough-hilo-window.png b/docs/porting/media/walkthrough-hilo-window.png new file mode 100644 index 0000000000..b440688064 Binary files /dev/null and b/docs/porting/media/walkthrough-hilo-window.png differ diff --git a/docs/porting/toc.yml b/docs/porting/toc.yml index 6f05b7a672..2d7ce6cafb 100644 --- a/docs/porting/toc.yml +++ b/docs/porting/toc.yml @@ -9,8 +9,20 @@ items: href: ../porting/overview-of-potential-upgrade-issues-visual-cpp.md - name: Upgrade your code to the Universal CRT href: ../porting/upgrade-your-code-to-the-universal-crt.md - - name: Modernize your C++ project with GitHub Copilot modernization - href: ../porting/copilot-app-modernization-cpp.md + - name: GitHub Copilot modernization for C++ + items: + - name: Overview + href: ../porting/github-copilot-modernization-cpp/overview.md + - name: Install + href: ../porting/github-copilot-modernization-cpp/install.md + - name: Scenarios and skills reference + href: ../porting/github-copilot-modernization-cpp/scenarios-and-skills.md + - name: Walkthrough - Hilo + href: ../porting/github-copilot-modernization-cpp/walkthrough-hilo.md + - name: Troubleshooting + href: ../porting/github-copilot-modernization-cpp/troubleshooting.md + - name: FAQ + href: ../porting/github-copilot-modernization-cpp/faq.md - name: Update WINVER and _WIN32_WINNT href: ../porting/modifying-winver-and-win32-winnt.md - name: Fix your dependencies on library internals diff --git a/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md b/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md index 471d610561..5aabda3b23 100644 --- a/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md +++ b/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md @@ -14,6 +14,8 @@ In Visual Studio 2026, this experience is enhanced with a setup assistant. The s With the setup assistant open, choose an action for each target or select **Retarget all** to set all projects at once. Then select **Apply** to complete the upgrade in place. Once your projects are retargeted, they can't be converted back to the earlier version. It's good practice to make a backup copy of the existing project and solution files before upgrading them. +The [GitHub Copilot modernization agent](./github-copilot-modernization-cpp/overview.md) can assist you with any changes that need to be made after your project files are upgraded. It will analyze your project for any new compilation warnings or errors and will iterate along with you to resolve them to complete your upgrade process. + > [!NOTE] > Visual Studio 2022 and later have deprecated support for the upgrade of project types that have *`.dsw`* or *`.dsp`* extensions. You can use an earlier version of Visual Studio, such as Visual Studio 2019, to upgrade these projects, then upgrade them again in Visual Studio 2022 or later to use the latest tools and features of Visual Studio. diff --git a/docs/porting/visual-cpp-porting-and-upgrading-guide.md b/docs/porting/visual-cpp-porting-and-upgrading-guide.md index 64aa8a53e5..17b0491189 100644 --- a/docs/porting/visual-cpp-porting-and-upgrading-guide.md +++ b/docs/porting/visual-cpp-porting-and-upgrading-guide.md @@ -61,7 +61,7 @@ ms.author: twhitney - [⬆️ Upgrading C++ Projects to Visual Studio 2026](https://devblogs.microsoft.com/cppblog/upgrading-c-projects-to-visual-studio-2026/) - [⬆️ Upgrade projects from earlier versions](upgrading-projects-from-earlier-versions-of-visual-cpp.md) -- [🤖 Upgrade with an AI agent (preview)](copilot-app-modernization-cpp.md) +- [🤖 Upgrade with an AI agent](github-copilot-modernization-cpp/overview.md) - [🛠️ IDE tools for upgrading C++ code](ide-tools-for-upgrading-code.md) - [🔄 Upgrade to Universal CRT](upgrade-your-code-to-the-universal-crt.md) - [🔧 Update WINVER and _WIN32_WINNT](modifying-winver-and-win32-winnt.md)