I ❤️ .NET

Table of Contents

1. What we gonna do?
2. Why we gonna do?
3. How we gonna do?
4. Summary

What we gonna do?

Upgrading .NET framework versions across large codebases has traditionally been a tedious, error-prone process requiring hours of manual work. GitHub Copilot AI Agents change this completely by introducing intelligent, context-aware automation that can handle the entire upgrade workflow—from analyzing your current setup to updating project files, dependencies, and CI/CD pipelines.

A GitHub Copilot AI Agent is a specialized instruction set that tells Copilot how to approach specific complex tasks. Unlike simple prompts, agents are comprehensive workflows stored as markdown files in your .github/agents directory. They contain discovery commands, upgrade strategies, validation steps, and rollback procedures—all the expertise needed to execute multi-step operations reliably.

In this article, you'll learn how to set up a .NET upgrade agent that can transform how you modernize your applications. Instead of spending days manually updating dozens of projects, you'll type a single command like "Upgrade the solution to .NET 10" and let the agent do the heavy lifting—analyzing dependencies, updating project files, managing breaking changes, and even updating your build pipelines.

What Makes an AI Agent Different from Regular Prompts?

AI agents are persistent, reusable, and comprehensive. A regular prompt might help you update one project file, but an agent understands the entire upgrade lifecycle. It knows to check for outdated packages, identify breaking changes, update CI/CD configurations, and validate the results. Agents encode institutional knowledge that would otherwise live only in senior developers' heads.

Why we gonna do?

.NET framework upgrades are critical for security, performance, and access to new language features—but they're painful. Here's why manual upgrades fail and how AI agents solve these problems.

Problem 1: Inconsistent Upgrade Paths Across Projects

In a typical solution with 20+ projects, some target net6.0, others use net7.0, and a few still reference netstandard2.1. When you manually upgrade, you might:

• Update projects in the wrong order, breaking builds
• Miss shared dependencies that cascade failures
• Forget to upgrade test projects, causing CI failures

<!-- This inconsistency is common in manual upgrades -->
<!-- API.csproj -->
<TargetFramework>net8.0</TargetFramework>

<!-- Shared.Library.csproj (forgotten!) -->
<TargetFramework>net6.0</TargetFramework>

<!-- Result: Version conflicts and build errors -->

Consequence: Your build breaks with cryptic errors about incompatible package versions. You spend hours debugging what should have been a straightforward upgrade.

Problem 2: Breaking Changes Slip Through

Each .NET version introduces breaking changes. For example, upgrading from .NET 6 to .NET 8 changed how minimal APIs handle route groups, and System.Text.Json serialization behavior evolved. Without comprehensive testing:

// This worked in .NET 6 but breaks in .NET 8+
var json = JsonSerializer.Serialize(obj, new JsonSerializerOptions 
{ 
    // PropertyNamingPolicy behavior changed
    PropertyNamingPolicy = null  
});

// Runtime exception: Serialization behavior differs

Consequence: Production bugs appear weeks after deployment because automated tests didn't catch runtime behavior changes.

Problem 3: Forgotten CI/CD Pipeline Updates

You diligently upgrade all .csproj files but forget your azure-pipelines.yml still specifies .NET 6. Your build succeeds locally but fails in CI:

# Forgotten in .github/workflows/build.yml
- uses: actions/setup-dotnet@v4
  with:
    dotnet-version: '6.x'  # Needs to be '10.x'!

Consequence: CI/CD fails, blocking deployments until someone realizes the pipeline configuration is stale.

Why GitHub Copilot AI Agents Are the Solution

AI agents eliminate these problems through systematic automation with context awareness:

• Dependency-aware sequencing: Agents analyze your solution structure and upgrade projects in dependency order
• Comprehensive validation: They run builds, tests, and static analysis after each step
• Multi-file coordination: Agents update .csproj files, CI/CD configs, and documentation simultaneously
• Breaking change detection: They query Microsoft docs and flag deprecated APIs before they bite you
• Rollback readiness: Agents work in feature branches with atomic commits for easy reversion

Instead of 2-3 days of manual work (plus debugging), an AI agent completes the entire upgrade in 30 minutes—with better consistency and documentation.

How we gonna do?

Step 1: Create the Agent Directory

Start by creating the .github/agents directory in your repository root:

mkdir -p .github/agents
cd .github/agents

Step 2: Create the .NET Upgrade Agent File

Create a file named dotnet-upgrade.agent.md in the .github/agents directory. This file will contain all the instructions for the agent. Here's the complete agent configuration:

---
description: 'Perform janitorial tasks on C#/.NET code including cleanup, modernization, and tech debt remediation.'
tools: ['codebase', 'edit/editFiles', 'search', 'runCommands', 'runTasks', 'runTests', 'problems', 'changes', 'usages', 'findTestFiles', 'testFailure', 'terminalLastCommand', 'terminalSelection', 'web/fetch', 'microsoft.docs.mcp']
---

# .NET Upgrade Collection

.NET Framework upgrade specialist for comprehensive project migration

**Tags:** dotnet, upgrade, migration, framework, modernization

## Collection Usage

### .NET Upgrade Chat Mode

Discover and plan your .NET upgrade journey!

```markdown, upgrade-analysis.prompt.md
---
mode: dotnet-upgrade
title: Analyze current .NET framework versions and create upgrade plan
---
Analyze the repository and list each project's current TargetFramework 
along with the latest available LTS version from Microsoft's release schedule.
Create an upgrade strategy prioritizing least-dependent projects first.
```

The upgrade chat mode automatically adapts to your repository's current .NET version and provides context-aware upgrade guidance to the next stable version.

It will help you:
- Auto-detect current .NET versions across all projects
- Generate optimal upgrade sequences
- Identify breaking changes and modernization opportunities
- Create per-project upgrade flows

---

### .NET Upgrade Instructions

Execute comprehensive .NET framework upgrades with structured guidance!

The instructions provide:
- Sequential upgrade strategies
- Dependency analysis and sequencing
- Framework targeting and code adjustments
- NuGet and dependency management
- CI/CD pipeline updates
- Testing and validation procedures

Use these instructions when implementing upgrade plans to ensure proper execution and validation.

---

### .NET Upgrade Prompts

Quick access to specialized upgrade analysis prompts!

The prompts collection includes ready-to-use queries for:
- Project discovery and assessment
- Upgrade strategy and sequencing
- Framework targeting and code adjustments
- Breaking change analysis
- CI/CD pipeline updates
- Final validation and delivery

Use these prompts for targeted analysis of specific upgrade aspects.

---

## Quick Start
1. Run a discovery pass to enumerate all `*.sln` and `*.csproj` files in the repository.
2. Detect the current .NET version(s) used across projects.
3. Identify the latest available stable .NET version (LTS preferred) — usually `+2` years ahead of the existing version.
4. Generate an upgrade plan to move from current → next stable version (e.g., `net6.0 → net8.0`, or `net7.0 → net9.0`).
5. Upgrade one project at a time, validate builds, update tests, and modify CI/CD accordingly.

---

## Auto-Detect Current .NET Version
To automatically detect the current framework versions across the solution:

```bash
# 1. Check global SDKs installed
dotnet --list-sdks

# 2. Detect project-level TargetFrameworks
find . -name "*.csproj" -exec grep -H "<TargetFramework" {} \;

# 3. Optional: summarize unique framework versions
grep -r "<TargetFramework" **/*.csproj | sed 's/.*<TargetFramework>//;s/<\/TargetFramework>//' | sort | uniq

# 4. Verify runtime environment
dotnet --info | grep "Version"
```

**Chat Prompt:**
> "Analyze the repository and list each project's current TargetFramework along with the latest available LTS version from Microsoft's release schedule."

---

## Discovery & Analysis Commands
```bash
# List all projects
dotnet sln list

# Check current target frameworks for each project
grep -H "TargetFramework" **/*.csproj

# Check outdated packages
dotnet list <ProjectName>.csproj package --outdated

# Generate dependency graph
dotnet msbuild <ProjectName>.csproj /t:GenerateRestoreGraphFile /p:RestoreGraphOutputPath=graph.json
```

**Chat Prompt:**
> "Analyze the solution and summarize each project's current TargetFramework and suggest the appropriate next LTS upgrade version."

---

## Classification Rules
- `TargetFramework` starts with `netcoreapp`, `net5.0+`, `net6.0+`, etc. → **Modern .NET**
- `netstandard*` → **.NET Standard** (migrate to current .NET version)
- `net4*` → **.NET Framework** (migrate via intermediate step to .NET 6+)

---

## Upgrade Sequence
1. **Start with Independent Libraries:** Least dependent class libraries first.
2. **Next:** Shared components and common utilities.
3. **Then:** API, Web, or Function projects.
4. **Finally:** Tests, integration points, and pipelines.

**Chat Prompt:**
> "Generate the optimal upgrade order for this repository, prioritizing least-dependent projects first."

---

## Per-Project Upgrade Flow
1. **Create branch:** `upgrade/<project>-to-<targetVersion>`
2. **Edit `<TargetFramework>`** in `.csproj` to the suggested version (e.g., `net9.0`)
3. **Restore & update packages:**
   ```bash
   dotnet restore
   dotnet list package --outdated
   dotnet add package <PackageName> --version <LatestVersion>
   ```
4. **Build & test:**
   ```bash
   dotnet build <ProjectName>.csproj
   dotnet test <ProjectName>.Tests.csproj
   ```
5. **Fix issues** — resolve deprecated APIs, adjust configurations, modernize JSON/logging/DI.
6. **Commit & push** PR with test evidence and checklist.

---

## Breaking Changes & Modernization
- Use `.NET Upgrade Assistant` for initial recommendations.
- Apply analyzers to detect obsolete APIs.
- Replace outdated SDKs (e.g., `Microsoft.Azure.*` → `Azure.*`).
- Modernize startup logic (`Startup.cs` → `Program.cs` top-level statements).

**Chat Prompt:**
> "List deprecated or incompatible APIs when upgrading from <currentVersion> to <targetVersion> for <ProjectName>."

---

## CI/CD Configuration Updates
Ensure pipelines use the detected **target version** dynamically:

**Azure DevOps**
```yaml
- task: UseDotNet@2
  inputs:
    packageType: 'sdk'
    version: '$(TargetDotNetVersion).x'
```

**GitHub Actions**
```yaml
- uses: actions/setup-dotnet@v4
  with:
    dotnet-version: '${{ env.TargetDotNetVersion }}.x'
```

---

## Validation Checklist
- [ ] TargetFramework upgraded to next stable version
- [ ] All NuGet packages compatible and updated
- [ ] Build and test pipelines succeed locally and in CI
- [ ] Integration tests pass
- [ ] Deployed to a lower environment and verified

---

## Branching & Rollback Strategy
- Use feature branches: `upgrade/<project>-to-<targetVersion>`
- Commit frequently and keep changes atomic
- If CI fails after merge, revert PR and isolate failing modules

**Chat Prompt:**
> "Suggest a rollback and validation plan if the .NET upgrade for <ProjectName> introduces build or runtime regressions."

---

## Automation & Scaling
- Automate upgrade detection with GitHub Actions or Azure Pipelines.
- Schedule nightly runs to check for new .NET releases via `dotnet --list-sdks`.
- Use agents to automatically raise PRs for outdated frameworks.

---

## Chatmode Prompt Library
1. "List all projects with current and recommended .NET versions."
2. "Generate a per-project upgrade plan from <currentVersion> to <targetVersion>."
3. "Suggest .csproj and pipeline edits to upgrade <ProjectName>."
4. "Summarize build/test results post-upgrade for <ProjectName>."
5. "Create PR description and checklist for the upgrade."

---

Step 3: Activate the Agent in VS Code

GitHub Copilot automatically discovers agents in the .github/agents directory. To use it:

1. Open VS Code with your solution loaded
2. Open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I)
3. Click the agent selector dropdown (looks like a brain icon or "@")
4. Select dotnet-upgrade from the list

Step 4: Execute the Upgrade with a Simple Prompt

Once you've selected the agent, upgrading your entire solution becomes trivial. Type a natural language instruction:

Upgrade the solution to .NET 10

or if you want more specific control:

dotnet-upgrade Analyze the solution and create an upgrade plan from current 
versions to the latest .NET LTS, prioritizing projects with fewest dependencies

Step 5: What the Agent Does Automatically

When you execute the prompt, the agent orchestrates a complete upgrade workflow:

Phase 1: Discovery & Analysis

# Agent executes these commands automatically
dotnet sln list
grep -r "<TargetFramework" **/*.csproj
dotnet list package --outdated

# Generates dependency graph
dotnet msbuild /t:GenerateRestoreGraphFile /p:RestoreGraphOutputPath=deps.json

The agent builds a mental model of your solution structure, identifying:

• Current framework versions for each project
• Inter-project dependencies (what depends on what)
• Outdated NuGet packages that need upgrading
• Projects using deprecated frameworks (netstandard, netcoreapp)

Phase 2: Upgrade Sequencing

The agent determines the safest upgrade order. For example, given this structure:

Solution: MyApp
│
├── Shared.Models.csproj (net6.0) ← No dependencies
├── Shared.Services.csproj (net6.0) ← Depends on Models
├── API.csproj (net7.0) ← Depends on Services
└── API.Tests.csproj (net7.0) ← Depends on API

Upgrade order:
1. Shared.Models (foundation, no deps)
2. Shared.Services (depends only on Models)
3. API (depends on Services)
4. API.Tests (depends on API)

Phase 3: Automated Updates

For each project in sequence, the agent:

<!-- Before: API.csproj -->
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
  </PropertyGroup>
</Project>

<!-- After: Agent updates to -->
<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
</Project>

Then updates NuGet packages:

# Agent executes
dotnet restore API.csproj
dotnet list API.csproj package --outdated
dotnet add API.csproj package Microsoft.AspNetCore.OpenApi --version 10.0.0
dotnet add API.csproj package Swashbuckle.AspNetCore --version 7.0.0

Phase 4: CI/CD Pipeline Updates

The agent scans for pipeline files and updates .NET versions automatically:

# Before: .github/workflows/build.yml
- uses: actions/setup-dotnet@v4
  with:
    dotnet-version: '7.x'

# After: Agent updates to
- uses: actions/setup-dotnet@v4
  with:
    dotnet-version: '10.x'

# Before: azure-pipelines.yml
- task: UseDotNet@2
  inputs:
    packageType: 'sdk'
    version: '7.x'

# After: Agent updates to
- task: UseDotNet@2
  inputs:
    packageType: 'sdk'
    version: '10.x'

Phase 5: Validation & Testing

After each project upgrade, the agent validates the changes:

# Build verification
dotnet build API.csproj --no-restore

# Test execution
dotnet test API.Tests.csproj --no-build

# Static analysis
dotnet format --verify-no-changes

If any step fails, the agent pauses and reports the error with context, allowing you to fix issues before proceeding.

Step 6: Review Agent Output and Commit

The agent generates a comprehensive summary of all changes:

## Upgrade Summary

**Target Version:** .NET 10.0
**Projects Updated:** 4
**NuGet Packages Updated:** 12
**CI/CD Pipelines Updated:** 2

### Projects Upgraded
1. ✅ Shared.Models (net6.0 → net10.0)
2. ✅ Shared.Services (net6.0 → net10.0)
3. ✅ API (net7.0 → net10.0)
4. ✅ API.Tests (net7.0 → net10.0)

### Breaking Changes Addressed
- Updated `JsonSerializerOptions` usage in API/Serialization.cs
- Migrated `IHostingEnvironment` to `IWebHostEnvironment`
- Replaced deprecated `ConfigureWebHostDefaults` pattern

### Next Steps
1. Review changes in feature branch `upgrade/solution-to-net10`
2. Run full integration test suite
3. Deploy to staging environment for validation
4. Merge to main after approval

All changes are committed to a feature branch with descriptive messages, making it easy to review before merging.

Advanced: Customizing the Agent for Your Needs

You can extend the agent to match your organization's specific requirements:

## Custom Validation Rules

```bash
# Add company-specific package version requirements
# Example: We always use latest preview of Azure SDKs
dotnet add package Azure.Identity --version "*-*"
dotnet add package Azure.Storage.Blobs --version "*-*"
```

## Custom Breaking Change Checks

- Verify custom middleware still compatible
- Check internal framework extensions
- Validate custom analyzers and code generators

## Custom Rollback Procedures

If upgrade fails in production:
1. Revert feature branch
2. Tag stable pre-upgrade state
3. Document rollback reason in issues
4. Schedule retry with fixes

Tips for Successful Agent-Driven Upgrades

• Start with a clean git state: Commit or stash changes before running the agent
• Review agent decisions: Don't blindly accept all changes—understand what's happening
• Test incrementally: Validate each project upgrade before moving to the next
• Update agents regularly: Add new patterns as you encounter edge cases
• Share agents across teams: Check them into source control so everyone benefits

Handling Complex Scenarios

For solutions with mixed .NET Framework (net48) and .NET Core projects, the agent can guide incremental migrations:

dotnet-upgrade Create a migration plan to move net48 projects to net8.0, 
identifying which projects can migrate directly and which need netstandard2.0 
as an intermediate step

The agent will analyze assembly compatibility, dependency graphs, and suggest a path like:

Migration Path for Legacy Projects:

Phase 1: Shared Libraries
- Shared.Models.csproj: net48 → netstandard2.0 → net8.0
- Shared.Utils.csproj: net48 → netstandard2.0 → net8.0

Phase 2: Applications  
- WebApp: net48 → net8.0 (direct migration, ASP.NET → ASP.NET Core)
- WindowsService: net48 → net8.0 (requires Worker Service template)

Blockers Identified:
- WebApp uses System.Web.Mvc (requires rewrite to ASP.NET Core MVC)
- WindowsService uses Topshelf (replace with Microsoft.Extensions.Hosting)

Summary

Key Takeaways

• GitHub Copilot AI Agents transform .NET upgrades from multi-day manual chores into 30-minute automated workflows
• Agents are reusable markdown files stored in .github/agents that encode comprehensive workflows including discovery, sequencing, validation, and rollback procedures
• The dotnet-upgrade agent automatically analyzes your solution, upgrades projects in dependency order, updates NuGet packages, and modernizes CI/CD pipelines—all from a simple natural language prompt
• Agents eliminate common upgrade failures by ensuring consistent sequencing, detecting breaking changes early, and validating each step before proceeding
• You can customize agents to match your organization's specific requirements, adding custom validation rules, breaking change checks, and rollback procedures
• Always work in feature branches, review agent decisions before merging, and test incrementally to maintain confidence in automated upgrades
• Sharing agents across teams through source control creates institutional knowledge that compounds over time, making every future upgrade easier

Start by creating your first upgrade agent today. The initial setup takes 15 minutes, but you'll save hours on every subsequent framework upgrade. As you refine the agent with your team's specific patterns and lessons learned, it becomes an invaluable automation asset that pays dividends across your entire development lifecycle.