|
| 1 | +--- |
| 2 | +title: GitHub Copilot app modernization custom upgrade instructions |
| 3 | +description: "Learn more about GitHub Copilot app modernization custom upgrade instructions. Custom upgrade instructions allow you to give Copilot more context so that it can automate more changes." |
| 4 | +titleSuffix: "" |
| 5 | +author: kschlobohm |
| 6 | +ms.author: kschlobohm |
| 7 | +ms.topic: overview |
| 8 | +ms.date: 09/29/2025 |
| 9 | + |
| 10 | +#customer intent: As a developer, I want to learn how I can customize my upgrade with the GitHub Copilot app modernziation, so that I can automate more of my upgrade changes. |
| 11 | + |
| 12 | +--- |
| 13 | + |
| 14 | +# Custom Upgrade Instructions for GitHub Copilot app modernization: upgrade for .NET |
| 15 | + |
| 16 | +## Overview |
| 17 | +GitHub Copilot App Modernization: upgrade for .NET has extensibility support in a few different ways and this article will focus on a feature called **Custom Upgrade Instructions**. While the upgrade tool will inspect, and follow, custom instructions in the `copilot-instructions.md` file we know those are sent to the LLM for every request. For upgrade specific scenarios, the upgrade can follow additional instructions from markdown files stored in the solution directory under the folder `.github\upgrades\prompts\<your_file_name>.md`. The upgrade experience supports these files in three ways. |
| 18 | + |
| 19 | +1. Creating custom upgrade instructions |
| 20 | +2. Running the custom upgrade instruction as a one-time step |
| 21 | +3. Running custom upgrade instructions during upgrade |
| 22 | + |
| 23 | +## Creating custom upgrade instructions |
| 24 | +To demonstrate this capability we can show how to replace Newtonsoft.Json with System.Text.Json. Both packages are supported on modern .NET and this scenario is provided for learning. |
| 25 | + |
| 26 | +To get started, follow these steps to create a new custom instructions file. Start by opening Visual Studio 2026 and your solution. You can learn more about [Visual Studio 2026 Insiders](//devblogs.microsoft.com/visualstudio/visual-studio-2026-insiders-is-here/) in the announcement. |
| 27 | + |
| 28 | +> [!NOTE] |
| 29 | +> You can follow along with these instructions using the code sample: [MvcMovieNet6](https://github.com/KSchlobohm/MvcMovieNet6) |
| 30 | +
|
| 31 | +1. Right-click the solution file and choose **Modernize** |
| 32 | + |
| 33 | +  |
| 34 | + |
| 35 | +2. Type `I want to generate a custom upgrade instruction` into the chat |
| 36 | + |
| 37 | +  |
| 38 | + |
| 39 | +3. The Copilot will produce a new file and ask you if you would like to refine the custom upgrade instruction further. |
| 40 | + |
| 41 | +  |
| 42 | + |
| 43 | +Tips for best outcomes: |
| 44 | +1. Custom upgrade instructions work best when Copilot can follow specific instructions. A common pattern follows the "if this, then that" approach to replace or alter code in your solution. |
| 45 | +2. If your instructions require multiple steps then we recommend breaking those steps into different files and describing the sequence as a prerequisite in each file. |
| 46 | +3. Using Visual Studio helps to generate a well-formed custom upgrade instruction but is not required. You can edit the instructions directly, or create it in VS Code with other tools like #fetch to refine the instructions. |
| 47 | +3. The custom upgrade instruction file does not have to be added to the solution file to function properly but adding it can be helpful. It helps create visibility into how this upgrade was executed. It helps you find and edit the file when refining it for best results. |
| 48 | +4. Code changing instructions work best when an example is provided. If you can make the change in your code then Copilot can capture that as an example by following these steps with your custom upgrade instruction file still open. |
| 49 | + 1. Make the code change you want to automate. |
| 50 | + 2. Type `check my git changes and add diffs as examples to my prompt file` |
| 51 | + 3. Copilot will update the instructions and add an example diff |
| 52 | + |
| 53 | +  |
| 54 | + |
| 55 | + |
| 56 | +## Running the custom upgrade instruction as a one-time step |
| 57 | + |
| 58 | +Once the custom upgrade instruction is created you can run it directly. This is useful for testing and helping to refine the approach before sharing it with others, or applying it during the upgrade. This approach is also helpful for tasks that need to be completed prior to starting the upgrade as a way to address technical debt in the solution. |
| 59 | + |
| 60 | +> [!NOTE] |
| 61 | +> These instructions assume you already have a custom instructions file created from the previous steps. You can follow along with these instructions using the code sample: [MvcMovieNet6](https://github.com/KSchlobohm/MvcMovieNet6) |
| 62 | +
|
| 63 | +1. Right-click the solution file and choose **Modernize** |
| 64 | + |
| 65 | +  |
| 66 | + |
| 67 | +2. Type `Replace Newtonsoft with System.Text.Json` into the chat |
| 68 | + |
| 69 | +  |
| 70 | + |
| 71 | +3. The upgrade will read the custom upgrade instructions and apply the change |
| 72 | + |
| 73 | +  |
| 74 | + |
| 75 | + |
| 76 | +Tips for best outcomes: |
| 77 | +1. Try to use words similar to the file name when activating the custom upgrade instruction. In this scenario we used 'Replace Newtonsoft with System.Text.Json' because the file was named `replace_newtonsoft_with_system_text_json.md`. If your file name uses other wording like **update** or **modify** then follow that pattern. |
| 78 | +2. You can tell if Copilot understood your instructions by checking the chat to see if it retrieved the file. If this does not appear, then the custom upgrade instruction was not used during the code transformation. |
| 79 | + |
| 80 | +  |
| 81 | + |
| 82 | +## Running custom upgrade instructions during upgrade |
| 83 | + |
| 84 | +When you need to repeatedly run a custom upgrade instruction, or need to run it during the upgrade, you can tell Copilot to incorporate the instructions into the plan. |
| 85 | + |
| 86 | +> [!NOTE] |
| 87 | +> These instructions assume you already have a custom instructions file created from the previous steps. You can follow along with these instructions using the code sample: [MvcMovieNet6](https://github.com/KSchlobohm/MvcMovieNet6) |
| 88 | +
|
| 89 | +1. Right-click the solution file and choose **Modernize** |
| 90 | + |
| 91 | +  |
| 92 | + |
| 93 | +2. Choose **Upgrade to a newer version of .NET** and generate a plan file |
| 94 | + |
| 95 | +  |
| 96 | + |
| 97 | +3. Choose **Accept upgrade settings and continue** |
| 98 | + |
| 99 | +  |
| 100 | + |
| 101 | +4. Choose **Address security vulnerabilities issues during this upgrade** |
| 102 | + |
| 103 | +  |
| 104 | + |
| 105 | +5. Review the plan file to see if your instructions are added. In the following image, we see the custom upgrade instruction is not part of the plan because the plan says Newtonsoft would be upgraded, and not replaced. |
| 106 | + |
| 107 | +  |
| 108 | + |
| 109 | +6. To modify the plan type `modify the plan with custom instructions to replace Newtonsoft` |
| 110 | + |
| 111 | + You should be able to see the effect on the planned package upgrades. |
| 112 | + |
| 113 | +  |
| 114 | + |
| 115 | + You should be able to see the effect on the planned project upgrades. |
| 116 | + |
| 117 | +  |
| 118 | + |
| 119 | + |
| 120 | +Tips for best outcomes: |
| 121 | +1. We recommend asking Copilot to edit the file for your best results. It is convenient and effective to ask Copilot to take responsibility for editing the plan thoroughly and correctly. |
| 122 | +2. Avoid action phrases like `upgrade the plan` as some action words can encourage Copilot to start the upgrade without modifying the plan. |
0 commit comments