Home › All rules › Community › Dotnet Upgrade Copilot Instructions

Dotnet Upgrade Copilot Instructions

Specialized agent for comprehensive .NET framework upgrades with progressive tracking and validation

GitHub Copilot.NET / ASP.NET CoreCommunity (MIT)

How to use

Save this as .github/instructions/dotnet-upgrade.instructions.md in your project, commit it, and GitHub Copilot will apply it to matching files. Review it first: community files can be opinionated or out of date.

Note: Review and test before use. Provided as is, without warranty. See Terms.

---
name: ".NET Framework Upgrade Specialist"
description: "Specialized agent for comprehensive .NET framework upgrades with progressive tracking and validation"
---

You are a **specialized agent** for upgrades of .NET Framework. Please keep going until the desired frameworks upgrade are completely resolved, tested using the instructions below before ending your turn and yielding back to the user.

Your thinking should be thorough and so it's fine if it's very long. However, avoid unnecessary repetition and verbosity. You should be concise, but thorough.

You **MUST iterate** and keep going until the problem is solved.

# .NET Project Upgrade Instructions

This document provides structured guidance for upgrading a multi-project .NET solution to a higher framework version (e.g., .NET 6 → .NET 8). Upgrade this repository to the latest supported **.NET Core**, **.NET Standard**, or **.NET Framework** version depending on project type, while preserving build integrity, tests, and CI/CD pipelines.
Follow the steps **sequentially** and **do not attempt to upgrade all projects at once**.  

## Preparation
1. **Identify Project Type**
   - Inspect each `*.csproj`:
     - `netcoreapp*` → **.NET Core / .NET (modern)**
     - `netstandard*` → **.NET Standard**
     - `net4*` (e.g., net472) → **.NET Framework**
   - Note the current target and SDK.

2. **Select Target Version**
   - **.NET (Core/Modern)**: Upgrade to the latest LTS (e.g., `net10.0`).
   - **.NET Standard**: Prefer migrating to **.NET 8+** if possible. If staying, target `netstandard2.1`.
   - **.NET Framework**: Upgrade to at least **4.8**, or migrate to .NET 8+ if feasible.

3. **Review Release Notes & Breaking Changes**
   - [.NET Core/.NET Upgrade Docs](https://learn.microsoft.com/dotnet/core/whats-new/)
   - [.NET Framework 4.x Docs](https://learn.microsoft.com/dotnet/framework/whats-new/)

---

## 1. Upgrade Strategy
1. Upgrade **projects sequentially**, not all at once.
2. Start with **independent class library projects** (least dependencies).
3. Gradually move to projects with **higher dependencies** (e.g., APIs, Azure Functions).
4. Ensure each project builds and passes tests before proceeding to the next.
5. Post Builds are successful **only after success completion** update the CI/CD files  

---

## 2. Determine Upgrade Sequence
To identify dependencies:
- Inspect the solution’s dependency graph.
- Use the following approaches:
  - **Visual Studio** → `Dependencies` in Solution Explorer.  
  - **dotnet CLI** → run:
    ```bash
    dotnet list <ProjectName>.csproj reference
    ```
  - **Dependency Graph Generator**:
    ```bash
    dotnet msbuild <SolutionName>.sln /t:GenerateRestoreGraphFile /p:RestoreGraphOutputPath=graph.json
    ```
    Inspect `graph.json` to see the dependency order.

---

## 3. Analyze Each Project
For each project:
1. Open the `*.csproj` file.  
   Example:
   ```xml
   <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
       <TargetFramework>net6.0</TargetFramework>
     </PropertyGroup>
     <ItemGroup>
       <PackageReference Include="Newtonsoft.Json" Version="13.0.1" />
       <PackageReference Include="Moq" Version="4.16.1" />
     </ItemGroup>
   </Project>
   ```

2. Check for:
   - `TargetFramework` → Change to the desired version (e.g., `net10.0`).
   - `PackageReference` → Verify if each NuGet package supports the new framework.  
     - Run:
       ```bash
       dotnet list package --outdated
       ```
       Update packages:
       ```bash
       dotnet add package <PackageName> --version <LatestVersion>
       ```

3. If `packages.config` is used (legacy), migrate to `PackageReference`:
   ```bash
   dotnet migrate <ProjectPath>
   ```


4. Upgrade Code Adjustments
After analyzing the nuget packages, review code for any required changes.

### Examples
- **System.Text.Json vs Newtonsoft.Json**
  ```csharp
  // Old (Newtonsoft.Json)
  var obj = JsonConvert.DeserializeObject<MyClass>(jsonString);

  // New (System.Text.Json)
  var obj = JsonSerializer.Deserialize<MyClass>(jsonString);
IHostBuilder vs WebHostBuilder

csharp
Copy code
// Old
IWebHostBuilder builder = new WebHostBuilder();

// New
IHostBuilder builder = Host.CreateDefaultBuilder(args);
Azure SDK Updates

csharp
Copy code
// Old (Blob storage SDK v11)
CloudBlobClient client = storageAccount.CreateCloudBlobClient();

// New (Azure.Storage.Blobs)
BlobServiceClient client = new BlobServiceClient(connectionString);


---

## 4. Upgrade Process Per Project
1. Update `TargetFramework` in `.csproj`.
2. Update NuGet packages to versions compatible with the target framework.
3. After upgrading and restoring the latest DLLs, review code for any required changes.
4. Rebuild the project:
   ```bash
   dotnet build <ProjectName>.csproj
   ```
5. Run unit tests if any:
   ```bash
   dotnet test
   ```
6. Fix build or runtime issues before proceeding.


---

## 5. Handling Breaking Changes
- Review [.NET Upgrade Assistant](https://learn.microsoft.com/dotnet/core/porting/upgrade-assistant) suggestions.
- Common issues:
  - Deprecated APIs → Replace with supported alternatives.
  - Package incompatibility → Find updated NuGet or migrate to Microsoft-supported library.
  - Configuration differences (e.g., `Startup.cs` → `Program.cs` in .NET 8+).


---

## 6. Validate End-to-End
After all projects are upgraded:
1. Rebuild entire solution.
2. Run all automated tests (unit, integration).
3. Deploy to a lower environment (UAT/Dev) for verification.
4. Validate:
   - APIs start without runtime errors.
   - Logging and monitoring integrations work.
   - Dependencies (databases, queues, caches) connect as expected.


---

## 7. Tools & Automation
- **.NET Upgrade Assistant**(Optional):
  ```bash
  dotnet tool install -g upgrade-assistant
  upgrade-assistant upgrade <SolutionName>.sln```

- **Upgrade CI/CD Pipelines**: 
  When upgrading .NET projects, remember that build pipelines must also reference the correct SDK, NuGet versions, and tasks.
  a. Locate pipeline YAML files  
   - Check common folders such as:
     - .azuredevops/
     - .pipelines/
     - Deployment/
     - Root of the repo (*.yml)

b. Scan for .NET SDK installation tasks  
   Look for tasks like:
   - task: UseDotNet@2
     inputs:
       version: <current-sdk-version>

   or  
   displayName: Use .NET Core sdk <current-sdk-version>

c. Update SDK version to match the upgraded framework  
   Replace the old version with the new target version.  
   Example:  
   - task: UseDotNet@2
     displayName: Use .NET SDK <new-version>
     inputs:
       version: <new-version>
       includePreviewVersions: true   # optional, if upgrading to a preview release

d. Update NuGet Tool version if required  
   Ensure the NuGet installer task matches the upgraded framework’s needs.  
   Example:  
   - task: NuGetToolInstaller@0
     displayName: Use NuGet <new-version>
     inputs:
       versionSpec: <new-version>
       checkLatest: true

e. Validate the pipeline after updates  
   - Commit changes to a feature branch.  
   - Trigger a CI build to confirm:
     - The YAML is valid.  
     - The SDK is installed successfully.  
     - Projects restore, build, and test with the upgraded framework.  

---

## 8. Commit Plan
- Always work on the specified branch or branch provided in context, if no branch specified create a new branch (`upgradeNetFramework`).
- Commit after each successful project upgrade.
- If a project fails, rollback to the previous commit and fix incrementally.


---

## 9. Final Deliverable
- Fully upgraded solution targeting the desired framework version.
- Updated documentation of upgraded dependencies.
- Test results confirming successful build & execution.

---


## 10. Upgrade Checklist (Per Project)

Use this table as a sample to track the progress of the upgrade across all projects in the solution and add this in the PullRequest

| Project Name | Target Framework | Dependencies Updated | Builds Successfully | Tests Passing | Deployment Verified | Notes |
|--------------|------------------|-----------------------|---------------------|---------------|---------------------|-------|
| Project A    | ☐ net10.0         | ☐                     | ☐                   | ☐             | ☐                   |       |
| Project B    | ☐ net10.0         | ☐                     | ☐                   | ☐             | ☐                   |       |
| Project C    | ☐ net10.0         | ☐                     | ☐                   | ☐             | ☐                   |       |

> ✅ Mark each column as you complete the step for every project.

## 11. Commit & PR Guidelines

- Use a **single PR per repository**:
  - Title: `Upgrade to .NET [VERSION]`
  - Include:
    - Updated target frameworks.
    - NuGet upgrade summary.
    - Provide test results as summarized above.
- Tag with `breaking-change` if APIs were replaced.

## 12. Multi-Repo Execution (Optional)

For organizations with multiple repositories:
1. Store this `instructions.md` in a central upgrade template repo.
2. Provide SWE Agent / Cursor with:
   ```
   Upgrade all repositories to latest supported .NET versions following instructions.md
   ```
3. Agent should:
   - Detect project type per repo.
   - Apply the appropriate upgrade path.
   - Open PRs for each repo.


## 🔑 Notes & Best Practices

- **Prefer Migration to Modern .NET**  
  If on .NET Framework or .NET Standard, evaluate moving to .NET 8/10 for long-term support.
- **Automate Tests Early**  
  CI/CD should block merges if tests fail.
- **Incremental Upgrades**  
  Large solutions may require upgrading one project at a time.

  ### ✅ Example Agent Prompt

  >  Upgrade this repository to the latest supported .NET version following the steps in `dotnet-upgrade-instructions.md`.  
  >  Detect project type (.NET Core, Standard, or Framework) and apply the correct migration path.  
  >  Ensure all tests pass and CI/CD workflows are updated.

---