dotnet-version-upgrade

Upgrades .NET to a newer TFM. LTS-to-LTS, staged through STS, preview, upgrade paths.

الانتقال إلى التثبيت

المستودع: rudironsoni/Synaxis
آخر نشاط في المصدر: ٨ مارس ٢٠٢٦ في ١٤:٥٩
لغة SKILL.md المكتشفة: الإنجليزية
النجوم: ٢
التفرعات: ١

خيارات التثبيت

يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.

مراجعة ملفات المصدر

اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.

العودة إلى البحث العودة إلى التثبيت

name	dotnet-version-upgrade
category	developer-experience
subcategory	project
description	Upgrades .NET to a newer TFM. LTS-to-LTS, staged through STS, preview, upgrade paths.
license	MIT
targets	["*"]
tags	["csharp","dotnet","skill"]
version	0.0.1
author	dotnet-agent-harness
invocable	true
claudecode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
codexcli	{"short-description":".NET skill guidance for csharp tasks"}
opencode	{"allowed-tools":["Read","Grep","Glob","Bash","Write","Edit"]}
copilot	{}
geminicli	{}
antigravity	{}

dotnet-version-upgrade

Comprehensive guide for .NET version upgrade planning and execution. This skill consumes the structured output from [skill:dotnet-version-detection] (current TFM, SDK version, preview flags) and provides actionable upgrade guidance based on three defined upgrade lanes. Covers TFM migration, package updates, breaking change detection, deprecated API replacement, and test validation.

Scope

Upgrade lane selection (Production LTS-to-LTS, Staged STS, Experimental preview)
TFM migration checklists per lane
Package update strategies (dotnet-outdated, Central Package Management)
Breaking change detection (build-time, analyzer diagnostics, API diff tools)
.NET Upgrade Assistant usage

Out of scope

TFM detection logic -- see [skill:dotnet-version-detection]
Multi-targeting project setup and polyfill strategies -- see [skill:dotnet-multi-targeting]
Cloud deployment configuration
CI/CD pipeline changes

Cross-references: [skill:dotnet-version-detection] for TFM resolution and version matrix, [skill:dotnet-multi-targeting] for polyfill-first multi-targeting strategies when maintaining backward compatibility during migration.

Upgrade Lanes

Select the appropriate upgrade lane based on project requirements and ecosystem constraints.

Lane	Path	Use Case	Risk Level
Production (default)	net8.0 -> net10.0	LTS-to-LTS, recommended for most apps	Low -- both endpoints are LTS with long support windows
Staged production	net8.0 -> net9.0 -> net10.0	When ecosystem dependencies require incremental migration	Medium -- intermediate STS version has shorter support
Experimental	net10.0 -> net11.0 (preview)	Non-production exploration of upcoming features	High -- preview APIs may change or be removed

Lane Selection Decision Flow

Are all your NuGet dependencies available on the target LTS? Yes -> Production lane (direct LTS-to-LTS).
Do any dependencies require an intermediate version? Yes -> Staged production lane.
Are you exploring preview features for R&D or proof-of-concept? Yes -> Experimental lane.

Production Lane: LTS-to-LTS (net8.0 -> net10.0)


<!-- Before -->
<PropertyGroup>
  <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>

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

```text

For solutions with shared properties:

```xml

<!-- Directory.Build.props -->
<PropertyGroup>
  <TargetFramework>net10.0</TargetFramework>
</PropertyGroup>

```xml

**Step 2: Update global.json SDK version**

```json

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

```text

**Step 3: Update NuGet packages**

Use `dotnet-outdated` to detect stale packages and identify which packages need updates for TFM compatibility:

```bash

# Install dotnet-outdated as a global tool
dotnet tool install -g dotnet-outdated-tool

# Check for outdated packages across the solution
dotnet outdated

# Check a specific project
dotnet outdated MyProject/MyProject.csproj

# Auto-upgrade to latest stable versions
dotnet outdated --upgrade

# Upgrade only to the latest minor/patch (safer)
dotnet outdated --upgrade --version-lock major

```text

For ASP.NET Core shared framework packages, update version references to match the target TFM:

```xml

<ItemGroup>
  <!-- Match package version to TFM major version -->
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.*" />
  <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.*" />
</ItemGroup>

```text

**Step 4: Review breaking changes**

```bash

# Build to surface warnings and errors
dotnet build --warnaserror

# Run analyzers for deprecated API usage
dotnet build /p:TreatWarningsAsErrors=true

```text

Review the official breaking change lists:
- [.NET 9 Breaking Changes](https://learn.microsoft.com/en-us/dotnet/core/compatibility/9.0)
- [.NET 10 Breaking Changes](https://learn.microsoft.com/en-us/dotnet/core/compatibility/10.0)

**Step 5: Replace deprecated APIs**

Common replacements when moving from net8.0 to net10.0:

| Deprecated | Replacement | Notes |
|-----------|-------------|-------|
| `BinaryFormatter` | `System.Text.Json` or `MessagePack` | `BinaryFormatter` throws `PlatformNotSupportedException` starting in net9.0 |
| `Thread.Abort()` | Cooperative cancellation via `CancellationToken` | `Thread.Abort()` throws `PlatformNotSupportedException` |
| `WebRequest` / `HttpWebRequest` | `HttpClient` via `IHttpClientFactory` | Obsolete (`SYSLIB0014`), migrate to `HttpClient` |

**Recommended modernizations** (not deprecated, but improve performance and AOT readiness):

| Pattern | Improvement | Notes |
|---------|-------------|-------|
| `Regex` without source gen | `[GeneratedRegex]` attribute | Source-generated regex is faster and AOT-compatible |

**Step 6: Run tests and validate**

```bash

# Run full test suite
dotnet test --configuration Release

# Enable trim/AOT analyzers to surface compatibility warnings without publishing
dotnet build --configuration Release /p:EnableTrimAnalyzer=true /p:EnableAotAnalyzer=true

```text

### .NET Upgrade Assistant

The .NET Upgrade Assistant automates parts of the migration process. It is most useful for large solutions with many projects.

```bash

# Install as a global tool
dotnet tool install -g upgrade-assistant

# Analyze a project (non-destructive, reports recommendations)
upgrade-assistant analyze MyProject/MyProject.csproj

# Perform the upgrade (modifies files)
upgrade-assistant upgrade MyProject/MyProject.csproj

```csharp

**When to use Upgrade Assistant:**
- Large solutions with many projects and complex dependency graphs
- Legacy .NET Framework-to-modern-.NET migrations
- When you need a comprehensive dependency analysis before committing to an upgrade

**Limitations:**
- May not handle all breaking changes -- manual review is still required
- Custom MSBuild extensions and third-party build tooling may need manual adjustment
- Does not update runtime behavior differences -- test coverage is essential
- Not needed for small projects with few dependencies (manual TFM update is simpler)

---

## Staged Production Lane: net8.0 -> net9.0 -> net10.0

Use the staged lane when direct LTS-to-LTS migration is blocked by ecosystem constraints. Staging through .NET 9 (STS) provides an incremental migration path.

### When to Stage Through .NET 9

- **Third-party package compatibility:** A critical dependency only supports net9.0 (not yet net10.0) and you need to upgrade away from net8.0 now.
- **Large breaking change surface:** The combined breaking changes from net8.0 to net10.0 are too many to address at once; incremental steps reduce risk.
- **Incremental validation:** You want to validate behavior changes at each step before proceeding.

### .NET 9 Context

.NET 9 is a Standard Term Support (STS) release:
- **GA:** November 2024
- **End of support:** May 2026 (18 months from GA)
- **C# version:** C# 13

Because .NET 9 is approaching end of support, do not stop at net9.0. Plan the second hop (net9.0 -> net10.0) before starting the first.

### Staged Upgrade Checklist

**Hop 1: net8.0 -> net9.0**

1. Update TFM to `net9.0` in .csproj / `Directory.Build.props`
2. Update `global.json` to SDK `9.0.xxx`
3. Run `dotnet outdated --upgrade` for package updates
4. Review [.NET 9 breaking changes](https://learn.microsoft.com/en-us/dotnet/core/compatibility/9.0)
5. Replace deprecated APIs flagged by `SYSLIB` diagnostics and `CS0618` warnings (e.g., `BinaryFormatter` -> `System.Text.Json`)
6. Run `dotnet test --configuration Release` to validate
7. Deploy to staging environment, validate in production with monitoring

**Hop 2: net9.0 -> net10.0**

1. Update TFM to `net10.0` in .csproj / `Directory.Build.props`
2. Update `global.json` to SDK `10.0.xxx`
3. Run `dotnet outdated --upgrade` again
4. Review [.NET 10 breaking changes](https://learn.microsoft.com/en-us/dotnet/core/compatibility/10.0)
5. Replace any additional deprecated APIs introduced between net9.0 and net10.0
6. Run `dotnet test --configuration Release` to validate
7. Deploy to staging, remove any net9.0-specific workarounds

**Timeline guidance:** Complete both hops within the .NET 9 support window (before May 2026). Running production workloads on an unsupported STS release exposes you to unpatched security vulnerabilities.

---

## Experimental Lane: net10.0 -> net11.0 (Preview)

For non-production exploration of upcoming features. .NET 11 is currently in preview and its APIs may change or be removed before GA.

### Guardrails

- **Non-production only.** Do not deploy preview-targeted code to production environments.
- **Separate branch or project.** Isolate experimental work from production codebases.
- **Pin the preview SDK.** Use `global.json` to lock the specific preview SDK version to avoid silent behavior changes between previews.
- **Expect breaking changes between previews.** APIs marked `[RequiresPreviewFeatures]` can change shape between preview releases.

### Enabling Preview Features

**Step 1: Install the preview SDK**

```bash

# Verify installed SDKs
dotnet --list-sdks

# Example: 11.0.100-preview.1.xxxxx should appear

```text

**Step 2: Pin to preview SDK in global.json**

```json

{
  "sdk": {
    "version": "11.0.100-preview.1.25120.13",
    "rollForward": "disable"
  }
}

```text

Use `"rollForward": "disable"` to prevent automatic SDK version advancement between previews.

**Step 3: Set TFM and enable preview features**

```xml

<PropertyGroup>
  <TargetFramework>net11.0</TargetFramework>
  <LangVersion>preview</LangVersion>
  <EnablePreviewFeatures>true</EnablePreviewFeatures>
</PropertyGroup>

```text

**Step 4: Enable runtime-async (optional)**

Runtime-async moves async/await from compiler-generated state machines to runtime-level execution, reducing allocations and improving performance for async-heavy workloads:

```xml

<PropertyGroup>
  <TargetFramework>net11.0</TargetFramework>
  <LangVersion>preview</LangVersion>
  <EnablePreviewFeatures>true</EnablePreviewFeatures>
  <Features>$(Features);runtime-async=on</Features>
</PropertyGroup>

```text

Runtime-async requires both `EnablePreviewFeatures` and the `Features` flag. It is experimental and may change significantly before GA.

### Experimental Upgrade Checklist

1. Install the .NET 11 preview SDK and pin it in `global.json` with `"rollForward": "disable"`
2. Update TFM to `net11.0` and set `<LangVersion>preview</LangVersion>` + `<EnablePreviewFeatures>true</EnablePreviewFeatures>`
3. Run `dotnet outdated` to check package compatibility with the preview TFM
4. Build and review warnings -- preview SDKs may flag new `SYSLIB` diagnostics or `CA2252` (preview feature usage)
5. Replace any deprecated APIs surfaced by the new analyzer version
6. Run `dotnet test` to validate -- expect some third-party packages to lack preview TFM support
7. Document findings for future production upgrade planning

### What to Explore in .NET 11 Preview

| Feature | Area | Notes |
|---------|------|-------|
| Runtime-async | Performance | Async/await at runtime level; requires opt-in |
| Zstandard compression | I/O | `System.IO.Compression.Zstandard`; 2-7x faster than Brotli |
| BFloat16 | Numerics | `System.Numerics.BFloat16` for AI/ML workloads |
| Happy Eyeballs | Networking | `ConnectAlgorithm.Parallel` for dual-stack IPv4/IPv6 |
| C# 15 preview features | Language | Collection expression arguments (`with()` syntax) |
| CoreCLR on WASM | Runtime | Experimental alternative to Mono for Blazor WASM |

---

## Breaking Change Detection

Systematic approaches to identify and resolve breaking changes during any upgrade.

### Build-Time Detection

```bash

# Clean build to surface all warnings (not just incremental)
dotnet clean && dotnet build --no-incremental

# Treat warnings as errors to catch deprecation notices
dotnet build /p:TreatWarningsAsErrors=true

# List specific obsolete API warnings
dotnet build 2>&1 | grep -E "CS0618|CS0612"

```text

- `CS0618`: Use of an `[Obsolete]` member with a message
- `CS0612`: Use of an `[Obsolete]` member without a message
- `CS8073`: Expression always evaluates to the same value (type behavior change)

### Analyzer Diagnostics

Enable .NET analyzers to detect additional issues:

```xml

<PropertyGroup>
  <EnableNETAnalyzers>true</EnableNETAnalyzers>
  <AnalysisLevel>latest-recommended</AnalysisLevel>
</PropertyGroup>

```text

Key analyzer categories for upgrades:
- `CA1422`: Platform compatibility (API removed on target platform)
- `CA1416`: Platform-specific API usage without guards
- `CA2252`: Opting into preview features
- `SYSLIB0XXX`: Obsolete system API diagnostics (e.g., `SYSLIB0011` for BinaryFormatter)

### API Diff Tools

For library authors, use API compatibility tools to validate public surface changes:

```bash

# Package validation detects breaking changes against a baseline
dotnet pack /p:EnablePackageValidation=true /p:PackageValidationBaselineVersion=1.0.0

# Standalone API comparison
dotnet tool install -g Microsoft.DotNet.ApiCompat.Tool
apicompat --left-assembly bin/Release/net8.0/MyLib.dll \
          --right-assembly bin/Release/net10.0/MyLib.dll

```text

See [skill:dotnet-multi-targeting] for detailed API compatibility validation workflows including suppression files and CI integration.

---

## Package Update Strategies

### dotnet-outdated

The `dotnet-outdated` tool provides a comprehensive view of package staleness:

```bash

# Install
dotnet tool install -g dotnet-outdated-tool

# Show all outdated packages with current vs latest versions
dotnet outdated

# Lock major version, show only minor/patch updates (safer incremental upgrades)
dotnet outdated --version-lock major

# Auto-upgrade with version locking to avoid unexpected major bumps
dotnet outdated --upgrade --version-lock major

# Output as JSON for CI integration
dotnet outdated --output-format json

```json

### Central Package Management

For solutions using Central Package Management (`Directory.Packages.props`), update versions centrally:

```xml

<!-- Directory.Packages.props -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <!-- Update all Microsoft.Extensions.* packages to match TFM -->
    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.*" />
    <PackageVersion Include="Microsoft.Extensions.Http" Version="10.*" />
    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.*" />
    <!-- Third-party packages: check compatibility before upgrading -->
    <PackageVersion Include="Serilog" Version="4.*" />
  </ItemGroup>
</Project>

```text

`Directory.Packages.props` resolves hierarchically upward from the project directory. In monorepo structures, verify that nested `Directory.Packages.props` files are not shadowing the root-level configuration.

### ASP.NET Core Shared Framework Packages

ASP.NET Core shared framework packages must align their major version with the target TFM. Two valid approaches:

```xml

<ItemGroup>
  <!-- Option A: floating version — auto-resolves latest patch, convenient for upgrades -->
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.*" />

  <!-- Option B: pinned version — deterministic CI builds, update explicitly -->
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="10.0.1" />
</ItemGroup>

```text

Pinned versions are recommended for deterministic CI; floating versions are useful during exploratory upgrades. Either way, the **major version must match the TFM** (e.g., `10.x` for `net10.0`).

---

## Agent Gotchas

1. **Do not skip .NET 9 without validating ecosystem compatibility.** While LTS-to-LTS (net8.0 -> net10.0) is the recommended default, some third-party packages may only support net9.0 as an intermediate step. Check package compatibility before selecting a lane.

1. **Do not run production workloads on preview SDKs.** .NET 11 preview APIs are unstable and will change between preview releases. Isolate experimental work in separate branches or projects with pinned preview SDK versions.

1. **Do not assume .NET 9 STS has 12-month support.** STS lifecycle is 18 months from GA. .NET 9 GA was November 2024, so end-of-support is May 2026. Always calculate from actual GA date, not release year.

1. **Ensure ASP.NET shared framework package major versions match the TFM.** Packages like `Microsoft.AspNetCore.Mvc.Testing` must have their major version aligned with the project TFM (e.g., `10.x` for `net10.0`). Pin exact versions for deterministic CI or float with wildcards (e.g., `10.*`) during exploratory upgrades.

1. **Do not re-implement TFM detection.** This skill consumes the structured output from [skill:dotnet-version-detection]. Never parse `.csproj` files to determine the current version -- use the detection skill's output (TFM, C# version, SDK version, warnings).

1. **Do not treat `dotnet-outdated --upgrade` as a complete solution.** It updates package versions but does not handle breaking API changes within those packages. Always build, test, and review changelogs after upgrading packages.

1. **Do not use `"rollForward": "latestMajor"` with preview SDKs.** This can silently advance to a different preview version with breaking changes. Use `"rollForward": "disable"` for preview SDKs to maintain reproducible builds.

1. **Do not forget `Directory.Packages.props` hierarchy.** In monorepo structures, nested `Directory.Packages.props` files shadow parent-level configurations. When upgrading, search upward from the project directory to find all `Directory.Packages.props` files that may affect package resolution.

1. **Do not ignore `SYSLIB` diagnostic codes during upgrade.** These system-level obsolete warnings (e.g., `SYSLIB0011` for BinaryFormatter, `SYSLIB0014` for WebRequest) indicate APIs that will throw at runtime on newer TFMs, not just compile-time warnings.

---

## Prerequisites

- .NET SDK for the target TFM installed (e.g., .NET 10 SDK for net10.0 upgrade)
- `dotnet-outdated-tool` (for package staleness detection): `dotnet tool install -g dotnet-outdated-tool`
- `upgrade-assistant` (optional, for automated migration): `dotnet tool install -g upgrade-assistant`
- Output from [skill:dotnet-version-detection] (current TFM, SDK version, preview flags)

---

## References

> **Last verified: 2026-02-12**

- [.NET Support Policy and Lifecycle](https://dotnet.microsoft.com/en-us/platform/support/policy)
- [.NET 9 Breaking Changes](https://learn.microsoft.com/en-us/dotnet/core/compatibility/9.0)
- [.NET 10 Breaking Changes](https://learn.microsoft.com/en-us/dotnet/core/compatibility/10.0)
- [.NET Upgrade Assistant](https://dotnet.microsoft.com/en-us/platform/upgrade-assistant)
- [dotnet-outdated Tool](https://github.com/dotnet-outdated/dotnet-outdated)
- [Central Package Management](https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management)
- [Target Framework Monikers](https://learn.microsoft.com/en-us/dotnet/standard/frameworks)
- [.NET Analyzers Overview](https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/overview)
- [Package Validation](https://learn.microsoft.com/en-us/dotnet/fundamentals/package-validation/overview)

# Instead of:
Read: src/Services/OrderService.cs
Grep: "public void ProcessOrder"

# Use:
serena_find_symbol: "OrderService/ProcessOrder"
serena_get_symbols_overview: "src/Services/OrderService.cs"