Dotnet Version Upgrade
Published by microsoft in upgrade-agent-plugins
What this skill does
Upgrade .NET projects to newer .NET versions, including guidance on current release status, support lifecycle (LTS/STS), and recommended upgrade targets.
Add Dotnet Version Upgrade to your agent
Review the source and files first. When you are ready, copy the prompt instruction or use the CLI command supported by your environment.
Install with a prompt
Paste this into a compatible coding agent:
add this skill "dotnet-version-upgrade" from https://github.com/microsoft/upgrade-agent-pluginsInstall with the CLI
Run this command in a controlled environment after reviewing the repository:
npx skills add https://github.com/microsoft/upgrade-agent-plugins --skill dotnet-version-upgradeSkill instructions
.NET Version Upgrade Scenario
Upgrade .NET projects from their current target framework to a newer version of .NET.
Current Facts
<!-- Last updated: 2025-11-12 -->| Version | Status | Support Level | End of Life |
|---|---|---|---|
| .NET 10 | GA | LTS | 2028-11-14 |
| .NET 9 | GA | STS | 2026-11-10 |
| .NET 8 | GA | LTS | 2026-11-10 |
| .NET 11 | Preview | — | 2030-11-12 (projected) |
Staleness check: If the user asks about a version listed as Preview above, verify its current status using an internet search tool before answering — it may have shipped since this data was last updated.
Scenario Overview
Goal: Migrate one or more .NET projects to a target framework version while maintaining functionality.
Workflow Stages
Run these stages in order:
- Pre-Initialization — Confirm target framework + source-control + flow parameters, then set up source control, call
initialize_scenario, and writescenario-instructions.md. Consumed during pre-initialization by the dedicatedDotnetVersionScenarioInitializergatherer. Tool:get_dotnet_upgrade_options. 0.5. Build Baseline — Record what already builds and what is already broken, before any change. Owned by the orchestrator's Build Baseline stage; unconditional and not tied to any upgrade option. Creates.github/upgrades/build-baseline.jsonat repo scope. - Assessment — Analyze the solution and identify risks. Creates
assessment.md. - Planning — Create the upgrade plan based on the assessment. Creates
plan.md. - Execution — Execute tasks and validate changes. Creates
tasks/*/task.md. Uses the executor's execution steps.
Pre-Initialization
This section is consumed during pre-initialization by the dedicated DotnetVersionScenarioInitializer
gatherer. It defines the scenario-specific parameters and tools for this scenario.
Tools to Call
Step 1: Call get_dotnet_upgrade_options(solutionPath, projectPath, targetFramework) to get:
- Solution and project file paths
- Suggested target framework version
- Available target frameworks for upgrade (with support level and end-of-life dates)
Step 2: Assemble the confirmFields list — one entry per user-confirmable parameter, in
display order: Target Framework first (suggested value first, then the available frameworks
from get_dotnet_upgrade_options), then flow mode, then — only in a git repo — the working
branch and commit strategy. These feed the single combined confirmation.
One combined confirmation: the framework is one parameter among several. It MUST appear in the same single confirmation — alongside flow mode, source-control (git only), and any other gathered parameters — never as its own separate question.
Step 3 — With confirmFields, git facts, and initializeDescription assembled, proceed to the
combined confirmation and then to initialize_scenario.
Stage Instructions
IMPORTANT: Load each stage's instructions file only when entering that stage (not all upfront).
Stage 1: Assessment
When entering this stage, load: assessment.md (read completely - contains 3 required steps)
Analyzes the solution and produces the assessment document:
- Solution analysis and dependency mapping
- Package update and vulnerability detection
- Risk identification
Assessment gatherer: this stage is handled by the dedicated DotnetVersionAssessor (the generic
Assessor is the fallback if the dedicated one is unavailable or returns BLOCKED). It works from
these inputs:
scenario id, repo/workspace path, and the workflow folder- the assessment parameters from pre-init:
inputMode,paths,targetFramework - the
scenario-instructions.mdpath (fallback source)
Stage 2: Planning
When entering this stage, load: planning.md (read completely - contains 5 steps)
Confirms upgrade options (including strategy) and creates the plan:
- Upgrade options evaluation — strategy, project approach, compatibility, modernization choices
- Planning gate: upgrade options are evaluated and returned for a single combined confirmation; the confirmed selections are persisted before the plan is generated
- Task breakdown following chosen strategy's rules
- Dependency ordering and phasing
- Strategy and execution constraints persisted in scenario-instructions.md
Stage 3: Execution
When entering this stage, load: execution.md (read completely - contains 7 sections)
Executes the upgrade tasks using the executor's core task-execution steps:
- Reads execution constraints from scenario-instructions.md (distilled during planning)
- Follows plan.md task order (which encodes the strategy structure)
- Decomposition rules in execution.md supplement the core execution steps (stub resolution subtasks, package replacement research, multi-targeting mechanics)
Success Criteria
- All projects target the specified framework version
- All package updates applied (no security vulnerabilities)
- Solution builds without errors
- All tests pass
- No dependency conflicts
Error Handling
Build errors after upgrade:
- Identify the failing project
- Check for breaking changes in the framework version
- Apply fixes from known patterns
- If stuck, ask user for direction
Circular dependencies:
- Identify the cycle
- Recommend architectural changes to break the cycle
- Proceed with user approval
Incompatible packages:
- Check for package updates that support target framework
- If no compatible version, document as blocking issue
- Suggest alternatives or workarounds
Files included
- assessment.md
- breakdown-hints/common.md
- breakdown-hints/framework-migration.md
- breakdown-hints/framework-web-migration.md
- breakdown-hints/test.md
- confirm-options-mcp.md
- execution.md
- planning-rules/framework-migration.md
- planning-rules/modern-upgrade.md
- planning.md
- post-completion.md
- SKILL.md
- strategies/all-at-once.md
- strategies/bottom-up.md
- strategies/top-down.md
- upgrade-options/binding-redirects.md
- upgrade-options/configuration-migration.md
- upgrade-options/cross-app-cookie-auth.md
- upgrade-options/dependency-injection.md
- upgrade-options/entity-framework.md
- upgrade-options/logging-framework.md
- upgrade-options/nullable-reference-types.md
- upgrade-options/package-management.md
- upgrade-options/project-approach.md
- upgrade-options/strategy.md
- upgrade-options/system-web-adapters.md
- upgrade-options/test-coverage.md
- upgrade-options/unsupported-api-handling.md
- upgrade-options/unsupported-packages.md
- upgrade-options/upgrade-options-index.md
- upgrade-options/windows-native-apis.md

