update-dotnet-version

/dotnet:update-dotnet-version

Flagship command: Comprehensive .NET version upgrade that handles SDK installation, TFM updates, package compatibility, and build validation with automatic error resolution.

Arguments

Parse arguments from $ARGUMENTS:

Flag	Description	Default
--version <version>	Target .NET version (e.g., 10, 10.0)	Latest stable
--check-only	Analyze without making changes	false
--force	Skip compatibility warnings and proceed	false
--skip-packages	Skip package upgrades	false
--skip-build	Skip build validation	false

Workflow Overview

┌─────────────────────────────────────────────────────────────┐
│                 /dotnet:update-dotnet-version               │
├─────────────────────────────────────────────────────────────┤
│ 1. Pre-flight Analysis                                      │
│    ├── Detect current TFM across all projects               │
│    ├── Check package compatibility with target              │
│    └── Report blockers                                      │
├─────────────────────────────────────────────────────────────┤
│ 2. SDK Installation                                         │
│    ├── Check if target SDK installed                        │
│    └── Install via /dotnet:install-sdk if needed            │
├─────────────────────────────────────────────────────────────┤
│ 3. Update global.json                                       │
│    └── Set SDK version and rollForward policy               │
├─────────────────────────────────────────────────────────────┤
│ 4. Update Target Frameworks                                 │
│    ├── Update <TargetFramework> in all .csproj              │
│    ├── Update <LangVersion> if needed                       │
│    └── Update Directory.Build.props if centralized          │
├─────────────────────────────────────────────────────────────┤
│ 5. Upgrade Packages                                         │
│    └── Run /dotnet:upgrade-nuget-packages --major --auto    │
├─────────────────────────────────────────────────────────────┤
│ 6. Build & Fix Loop                                         │
│    ├── Run dotnet build                                     │
│    ├── If errors: spawn build-fixer agent                   │
│    └── Retry up to 5 times                                  │
├─────────────────────────────────────────────────────────────┤
│ 7. Verification                                             │
│    ├── Run tests if available                               │
│    └── Report final status                                  │
└─────────────────────────────────────────────────────────────┘

Detailed Workflow

Phase 1: Pre-flight Analysis

1.1 Detect Current State:

# Find all project files
find . -name "*.csproj" -type f

# Extract current TFMs
grep -h "<TargetFramework" **/*.csproj | sort -u

Parse and report:

Current .NET Version Analysis

  Projects found: 12
  Current TFM: net9.0 (10 projects), net8.0 (2 projects)
  Target TFM: net10.0

  Mixed TFM detected: 2 projects on net8.0
    - src/Legacy/Legacy.csproj
    - tests/Legacy.Tests/Legacy.Tests.csproj

1.2 Package Compatibility Check:

For each unique package, check .NET 10 support:

Use mcp__perplexity__search:
  query: "<package-name> .NET 10 support compatibility January 2026"

Report findings:

Package Compatibility Analysis

  Compatible (confirmed):
    - Microsoft.Extensions.* (10.0.0 available)
    - Serilog (4.0.0 supports net10.0)
    - xunit (2.9.0 supports net10.0)

  Needs Upgrade:
    - Newtonsoft.Json 12.0.0 -> 13.0.3 (net10.0 support)
    - AutoMapper 11.0.0 -> 13.0.0 (net10.0 support)

  Potential Blockers:
    - OldLibrary 2.0.0 - No .NET 10 support found
      Options: Find alternative, wait for update, or remove dependency

  Unknown (verify manually):
    - CustomInternalLib 1.0.0

1.3 Breaking Changes Research:

Use mcp__microsoft-learn__microsoft_docs_search:
  query: ".NET 10 breaking changes migration from .NET 9"

Use mcp__perplexity__reason:
  query: ".NET 9 to .NET 10 migration breaking changes C# 14 what to watch for"

Report relevant breaking changes:

Breaking Changes to Watch

  .NET 10 Breaking Changes:
    - System.Text.Json: New source generator requirements
    - ASP.NET Core: Minimal API changes
    - EF Core: Query behavior changes

  C# 14 New Features Available:
    - Field keyword in properties
    - Collection expressions improvements
    - Extension types (preview)

1.4 Decision Point:

If --check-only:

• Report analysis and exit

If blockers found and NOT --force:

Blockers Found - Cannot Proceed

  1. OldLibrary 2.0.0 has no .NET 10 support

Options:
  1. Remove OldLibrary dependency first
  2. Run with --force to proceed anyway (may fail)
  3. Cancel and resolve manually

[AskUserQuestion with options]

Phase 2: SDK Installation

Check if target SDK is installed:

dotnet --list-sdks | grep "^10\."

If not installed:

.NET 10 SDK not found. Installing...

[Invoke /dotnet:install-sdk --version 10.0 --update-global-json]

Phase 3: Update global.json

Create or update global.json:

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestPatch"
  }
}

Phase 4: Update Target Frameworks

4.1 Check for centralized TFM:

Look for Directory.Build.props with:

<TargetFramework>net9.0</TargetFramework>

If found, update only Directory.Build.props.

4.2 Update individual projects:

For each .csproj file:

<!-- Before -->
<TargetFramework>net9.0</TargetFramework>

<!-- After -->
<TargetFramework>net10.0</TargetFramework>

4.3 Update LangVersion if explicit:

<!-- If LangVersion is set explicitly -->
<LangVersion>13.0</LangVersion>
<!-- Update to -->
<LangVersion>14.0</LangVersion>
<!-- Or remove to use SDK default -->

4.4 Handle multi-targeting:

<!-- Before -->
<TargetFrameworks>net8.0;net9.0</TargetFrameworks>

<!-- After -->
<TargetFrameworks>net9.0;net10.0</TargetFrameworks>

Phase 5: Upgrade Packages

Unless --skip-packages:

Upgrading packages for .NET 10 compatibility...

[Invoke internal package upgrade logic]

Focus on:

• Microsoft.* packages (align with .NET version)
• Packages with known .NET 10 versions
• Security-vulnerable packages

Phase 6: Build & Fix Loop

6.1 Initial Build:

dotnet build --verbosity minimal

6.2 If errors, spawn build-fixer:

Build failed with 12 errors. Attempting auto-fix...

[Task: dotnet:build-fixer with error context]

6.3 Retry loop:

Fix attempt 1/5:
  - Fixed 8 errors
  - 4 errors remaining

Fix attempt 2/5:
  - Fixed 3 errors
  - 1 error remaining

Fix attempt 3/5:
  - Fixed 1 error
  - Build successful!

6.4 Max attempts reached:

Build still failing after 5 fix attempts.

Remaining errors:
  CS0012: Type 'OldType' is defined in assembly not referenced

These errors require manual intervention:
  1. OldLibrary uses types not available in .NET 10
  2. Consider removing or replacing OldLibrary

Partial upgrade complete. Manual fixes required.

Phase 7: Verification

7.1 Run tests (if available):

dotnet test --no-build

7.2 Report final status:

Output Format

Check-Only Mode:

.NET Version Upgrade Analysis (--check-only)

  Current: net9.0
  Target: net10.0
  Projects: 12

Package Compatibility:
  Compatible: 45 packages
  Needs Upgrade: 8 packages
  Blockers: 1 package (OldLibrary)

Breaking Changes: 3 relevant changes found
  - System.Text.Json source generator changes
  - ASP.NET Core minimal API updates
  - EF Core query translation changes

Recommendation: Resolve OldLibrary dependency before upgrading.
Run without --check-only to proceed with upgrade.

Successful Upgrade:

.NET Version Upgrade Complete

  Upgraded: net9.0 -> net10.0
  Projects modified: 12
  SDK: 10.0.100

Changes Made:
  - global.json: Created with SDK 10.0.100
  - Directory.Build.props: Updated TFM to net10.0
  - 12 .csproj files: Updated TFM
  - 8 packages upgraded to .NET 10 compatible versions

Build: Successful (after 2 fix iterations)
Tests: 142 passed, 0 failed

Fixes Applied:
  - Added System.Text.Json source generator attribute (3 files)
  - Updated deprecated API calls (5 files)

Upgrade complete! Your project now targets .NET 10.

Partial Upgrade:

.NET Version Upgrade Partial

  Target: net10.0
  Projects modified: 12

Changes Made:
  - TFM updated to net10.0
  - 6 packages upgraded

Build Status: FAILED (after 5 fix attempts)

Remaining Issues:
  1. OldLibrary.OldType not available (3 errors)
     - src/MyApp/Services/LegacyService.cs:42
     - src/MyApp/Services/LegacyService.cs:78
     - src/MyApp/Models/LegacyModel.cs:15

Manual Action Required:
  Replace or remove OldLibrary dependency.
  Then run: dotnet build

Rollback Command (if needed):
  git checkout -- .
  dotnet restore

Examples

# Analyze upgrade without making changes
/dotnet:update-dotnet-version --check-only

# Upgrade to latest stable .NET
/dotnet:update-dotnet-version

# Upgrade to specific version
/dotnet:update-dotnet-version --version 10.0

# Force upgrade despite warnings
/dotnet:update-dotnet-version --force

# Upgrade TFM only, skip packages
/dotnet:update-dotnet-version --skip-packages

Rollback

If upgrade fails or causes issues:

# Revert all changes
git checkout -- .

# Restore original packages
dotnet restore

# Verify original state builds
dotnet build

Related Commands

• /dotnet:install-sdk - Install SDK only
• /dotnet:upgrade-nuget-packages - Upgrade packages only
• /dotnet:build --fix - Build with auto-fix
• /dotnet:solution-health - Analyze project health