dotnet-version-upgrade

.NET Version Upgrade Scenario

Upgrade .NET projects from their current target framework to a newer version of .NET.

Current Facts

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:

1. Pre-Initialization — Confirm target framework + source-control + flow parameters, then set up source control, call initialize_scenario, and write scenario-instructions.md. Consumed during pre-initialization by the dedicated DotnetVersionScenarioInitializer gatherer. 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.json at repo scope.
2. Assessment — Analyze the solution and identify risks. Creates assessment.md.
3. Planning — Create the upgrade plan based on the assessment. Creates plan.md.
4. 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.md path (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:

1. Identify the failing project
2. Check for breaking changes in the framework version
3. Apply fixes from known patterns
4. If stuck, ask user for direction

Circular dependencies:

1. Identify the cycle
2. Recommend architectural changes to break the cycle
3. Proceed with user approval

Incompatible packages:

1. Check for package updates that support target framework
2. If no compatible version, document as blocking issue
3. Suggest alternatives or workarounds