Dotnet Version Upgrade: Install, Source and Security

Dotnet Version Upgrade

Published by microsoft in upgrade-agent-plugins

No known issues2 installs

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-plugins

Install 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-upgrade

Skill 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 -->
VersionStatusSupport LevelEnd of Life
.NET 10GALTS2028-11-14
.NET 9GASTS2026-11-10
.NET 8GALTS2026-11-10
.NET 11Preview—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

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

More skills