Imported from Trigent-Software-Pvt-Ltd/trigen-aidlc (plugins/dotnet/skills/version-upgrade/SKILL.md). Install upstream with npx skills add Trigent-Software-Pvt-Ltd/trigen-aidlc --skill version-upgrade. Copyright stays with the author.

.NET Version Upgrader

You are performing a structured .NET version upgrade workflow for an engineering team using GitLab.com, GitLab CI, and GitLab Merge Requests. Follow each phase in order.

Phase 0: Understand the Request

Parse arguments or ask the user for the following, using [FACT]/[INFERRED]/[ASSUMED] labels where appropriate:

Target framework validation:

The target framework must match one of these valid patterns:

• net8.0, net9.0, net10.0, net12.0, net14.0 (or any netX.0 where X >= 6)
• netstandard2.0, netstandard2.1
• net48, net472 (only for library multi-targeting, never as a migration target)

If the user provides a version number (e.g., "10", ".NET 10", "10.0"), normalise to the correct TFM (e.g., net10.0).

If no target is specified, default to net10.0 (current team LTS) and tell the user.

Check for version-specific guidance: After determining the target, use the Read tool to read: {{SKILL_DIR}}/../../references/version-upgrade/version-guidance/{target-framework}.md

If Read succeeds, guidance is available — note it for Phase 4. If Read returns an error or file-not-found, try the Bash fallback:

find "$HOME/.claude/plugins" -name "{target-framework}.md" -path "*/version-guidance/*" 2>/dev/null | head -1

Then Read from the returned path. Report whether guidance was found — this controls whether modernisation recommendations are available.

Phase 1: Scan the Repository

Run the scan script if available, otherwise perform manual scanning. Present a summary before making any changes.

Files to Scan

Solution and project files:

• *.sln — Visual Studio solution files
• *.slnx — Modern XML solution files
• *.csproj — C# project files (recurse)
• *.fsproj — F# project files (recurse)

Build configuration:

• global.json — SDK version pin
• Directory.Build.props — Shared MSBuild properties
• Directory.Build.targets — Shared MSBuild targets
• Directory.Packages.props — Central Package Management

Package management:

• NuGet.config

Container and CI/CD:

• Dockerfile (all, recurse)
• .gitlab-ci.yml
• GitLab CI include templates (follow include: references where local)

Azure Functions:

• host.json (all, recurse)
• local.settings.json (all, recurse)
• *.csproj files with Functions SDK references

Configuration:

• appsettings.json, appsettings.*.json

What to Detect

Framework detection:

• Current <TargetFramework> or <TargetFrameworks> in each project file
• SDK version from global.json
• Whether TargetFramework is set in Directory.Build.props (centralised)

Application type (per project):

• ASP.NET Core Web API: has Microsoft.AspNetCore.* packages or <Project Sdk="Microsoft.NET.Sdk.Web">
• Azure Function (in-process): has Microsoft.NET.Sdk.Functions package, [FunctionName] attribute usage, FunctionsStartup class
• Azure Function (isolated worker): has Microsoft.Azure.Functions.Worker package, [Function] attribute, ConfigureFunctionsWorkerDefaults()
• Class library: <Project Sdk="Microsoft.NET.Sdk"> without web/functions markers
• Test project: contains xunit, NUnit, MSTest package references

Package management:

• Central Package Management: Directory.Packages.props exists AND <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
• Packages with inline Version attributes (non-CPM pattern)
• PackageVersion entries in Directory.Packages.props

Risky packages (flag for manual review — see references/risky-packages.md):

• Entity Framework Core packages
• Npgsql
• Microsoft.Extensions.*
• Microsoft.AspNetCore.*
• Azure Functions worker and extensions packages
• Newtonsoft.Json / System.Text.Json
• OpenTelemetry.*
• MassTransit.*
• RabbitMQ.Client
• Serilog.*
• Swashbuckle.AspNetCore
• NSwag.*
• Scalar.*
• FluentValidation
• MediatR

OpenAPI/Swagger detection:

• Swashbuckle.AspNetCore usage
• NSwag usage
• Scalar usage (if already modernised)
• Registration in Program.cs / Startup.cs

GitLab CI detection:

• Docker image tags containing SDK/runtime versions (mcr.microsoft.com/dotnet/sdk:X.X, mcr.microsoft.com/dotnet/aspnet:X.X)
• DOTNET_VERSION, SDK_VERSION, DOTNET_SDK_VERSION variables
• Build, test, publish, deploy stages
• Test report artifact paths
• Coverage job configuration
• include: project: references to trigent1/pipeline-templates — if present, extract the ref: (template version/branch) and any inputs: overrides for SDK/version variables. The template owns SDK defaults; individual services override via inputs:.

Solution file detection:

• Whether only .sln exists (recommend .slnx)
• Whether .slnx already exists (modern)
• Whether both exist (prefer .slnx for validation)

Phase 2: Present Pre-Upgrade Summary

Before making any changes, present:

## Pre-Upgrade Scan Summary

**Repo:** {path}
**Target framework:** {target-framework}
**Version guidance available:** yes/no

### Projects Found
| Project | Type | Current TFM | Multi-target |
|---------|------|-------------|--------------|

### Package Management
- Central Package Management: yes/no
- Directory.Build.props: yes/no
- Directory.Build.targets: yes/no

### Risky Packages Detected
{list packages requiring care}

### GitLab CI
{findings}

### Flags for This Run
{list all flags and their values}

### What Will Change
{itemised list of planned changes}

### What Will NOT Change (requires explicit flags)
{itemised list of optional changes not activated}

Ask for confirmation before proceeding if in interactive mode, unless --report-only was passed.

Phase 3: Apply Upgrade Changes

Apply changes in this order. Only apply steps that are safe and in scope.

Step 3.1: Update TargetFramework / TargetFrameworks

Safe mechanical change — always apply (unless --report-only).

For each .csproj and .fsproj:

1. If TargetFramework is set in the project file:

   • Replace with the target TFM.
   • Exception: preserve netstandard2.0 / netstandard2.1 targets by default unless --allow-breaking-changes is passed.

2. If TargetFrameworks (multi-target) is set:

   • Replace the non-netstandard TFM only.
   • Preserve all netstandard* targets.
   • Example: net8.0;netstandard2.0 → net10.0;netstandard2.0

3. If TargetFramework is defined in Directory.Build.props:

   • Update there instead. Note this in the report.
   • Do not also update individual project files unless they override it.

Step 3.2: Update global.json

Safe mechanical change — always apply (unless --report-only).

When a global.json exists, update the SDK version to match the target framework if version-specific guidance specifies the expected SDK. For net10.0, the expected SDK is 10.0.100 with rollForward: latestMinor.

If no version-specific guidance exists for the target, note that global.json should be reviewed manually and leave it unchanged.

Step 3.3: Update Package References (requires --allow-packages)

Only when --allow-packages is passed:

• For packages with a known major-version alignment to the target framework (e.g., Microsoft.Extensions.*, Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*), suggest aligned versions.
• Do NOT automatically update risky packages. Flag each one for manual review.
• Do NOT update packages where the appropriate target version is unknown.
• Prefer updating PackageVersion entries in Directory.Packages.props over inline Version attributes when CPM is active.

Step 3.4: Central Package Management Migration (requires --allow-cpm)

Only when --allow-cpm is passed AND Directory.Packages.props does not already exist:

1. Create Directory.Packages.props at repo root.
2. Move all Version attributes from PackageReference entries to PackageVersion entries in the new file.
3. Remove Version attributes from PackageReference entries in .csproj files.
4. Add <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> to Directory.Build.props (or create it).

Step 3.5: Directory.Build.props Creation/Refactor (requires --allow-dbprops)

Only when --allow-dbprops is passed:

• If Directory.Build.props is absent and common properties are repeated across projects:
  • Create Directory.Build.props with common TargetFramework, Nullable, ImplicitUsings, TreatWarningsAsErrors.
  • Remove those properties from individual project files.
• If Directory.Build.props exists but lacks the target framework property, recommend adding it (but only update if explicitly requested).

Step 3.6: .slnx Migration (requires --allow-slnx)

Only when --allow-slnx is passed AND no .slnx exists:

• Generate a .slnx file equivalent to the existing .sln.
• Do NOT remove the .sln unless explicitly requested with a separate confirmation.
• Note: .slnx is the recommended modern solution format.

Phase 4: Target-Version Specific Guidance

After mechanical changes, apply target-version guidance if available.

Load the version guidance file: Use the Read tool to read: {{SKILL_DIR}}/../../references/version-upgrade/version-guidance/{target-framework}.md

If Read fails, use the Bash fallback to locate the file:

find "$HOME/.claude/plugins" -name "{target-framework}.md" -path "*/version-guidance/*" 2>/dev/null | head -1

Then Read from the returned path.

• If the file loads successfully: apply its recommendations where in scope.
• If the file cannot be loaded (does NOT exist):
  • State explicitly: "No version-specific guidance exists for {target-framework}. Only safe mechanical upgrade changes have been applied."
  • Do not make speculative modernisation recommendations.
  • Do not recommend version-specific packages or patterns.

Web API Modernisation (if version guidance recommends it)

For Web APIs, when version guidance recommends OpenAPI modernisation:

• Flag Swashbuckle.AspNetCore as a modernisation candidate.
• Recommend evaluating Scalar for OpenAPI UI.
• Do NOT automatically replace Swashbuckle with Scalar.
• Note migration considerations: Scalar uses app.MapOpenApi() (built-in .NET OpenAPI) vs Swashbuckle's generator.
• Require explicit --allow-breaking-changes and user confirmation before any OpenAPI tooling replacement.

Azure Functions Modernisation (if version guidance recommends it)

For Azure Functions detected as in-process model:

• Flag as HIGH RISK modernisation candidate.
• Note that the in-process model is not supported in .NET 10+; isolated worker model is required.
• Provide a summary of in-process vs isolated worker differences:
  • [FunctionName] → [Function]
  • FunctionsStartup → HostBuilder
  • IFunctionsHostBuilder → IServiceCollection directly
  • Package changes: Microsoft.NET.Sdk.Functions → Microsoft.Azure.Functions.Worker + extensions
• Do NOT automatically migrate the execution model. Require explicit --allow-breaking-changes and user confirmation.

GitLab CI Updates

When CI findings exist:

• Recommend updating Docker image tags for build/runtime stages to match the target framework.
• Recommend updating DOTNET_VERSION / SDK_VERSION variables.
• Only apply these changes when --allow-packages or if no risk is involved (e.g., variable-only changes).
• Do NOT rewrite CI structure. Preserve existing stage/job organisation.

When trigent1/pipeline-templates is detected via include: project::

• Flag that the SDK version default is owned by the shared template, not this service repo.
• Updating a local image tag or variable will have no effect unless the service overrides the template default via inputs:.
• Report the template ref: being used (branch/tag). If it is main or unversioned, the service tracks the latest template, which may or may not support the target .NET version.
• Manual follow-up required: verify that the pipeline template version in use supports the target SDK, or add a service-level inputs: override:

include:
  - project: trigent1/pipeline-templates
    ref: main
    file: /path/to/template.yml
    inputs:
      dotnet_version: "10.0"   # override template default

• Do NOT modify the include: block automatically. Always report findings and let the engineer decide.

Phase 5: Validation

Run when tools are available. Prefer solution-level commands over individual projects.

dotnet --info
dotnet restore {solution-file}
dotnet build {solution-file}
dotnet test {solution-file}   # only when --run-tests is passed

Solution file selection priority:

1. .slnx if it exists (or was just created)
2. .sln if a single one exists
3. If multiple .sln exist, identify them all and ask the user to confirm which to use

On build or restore failure:

• Do NOT hide the failure.
• Report the full error output.
• Propose targeted fixes only for errors directly related to the TFM upgrade.
• Do NOT attempt to fix unrelated pre-existing build errors.

Phase 6: Generate Upgrade Report

Always produce the following report at the end, regardless of --report-only mode.

# .NET Upgrade Report

**Date:** {date}
**Repo:** {path}
**Current Framework(s):** {list}
**Target Framework:** {target-framework}
**Version Guidance Available:** yes/no
**Mode:** report-only | upgrade applied

---

## Summary of Changes

### Files Modified
{list each file and what changed}

### SDK Changes
{global.json before/after}

### Package Management
{CPM status, any package changes}

### Package Changes
{packages updated, flagged, or skipped — with reasons}

---

## Build Result
{dotnet build output summary or "not run"}

## Test Result
{dotnet test output summary or "not run" or "skipped (--run-tests not passed)"}

---

## Risks

### HIGH
{list}

### MEDIUM
{list}

### LOW
{list}

---

## Manual Follow-Up Items

- [ ] {item}

---

## GitLab CI Follow-Up Items

- [ ] {item}

---

## Modernisation Opportunities (Not Applied)

{list with reasons why not auto-applied}

---

## GitLab MR Description

{MR description ready to paste — see references/mr-template.md}

Safety Rules

Never:

• Delete projects or solution files
• Remove package references unless a build confirms they are truly unused
• Remove .sln unless explicitly asked with confirmation
• Change authentication or security behaviour
• Auto-migrate Azure Functions execution model (in-process → isolated worker)
• Auto-replace Swashbuckle with Scalar
• Hide build failures or suppress errors
• Make speculative recommendations when no version-specific guidance exists

Extra caution required for these packages — flag each one, do not silently upgrade:

• Entity Framework Core (Microsoft.EntityFrameworkCore.*)
• Npgsql and Npgsql EF Core provider
• Microsoft.Extensions.* (major version alignment with runtime)
• Microsoft.AspNetCore.* (ships with runtime, do not pin separately)
• Azure Functions worker packages (Microsoft.Azure.Functions.Worker.*)
• Microsoft.NET.Sdk.Functions (in-process — requires careful versioning)
• Newtonsoft.Json vs System.Text.Json (different serialisation behaviour)
• OpenTelemetry.* (breaking changes between major versions)
• MassTransit.* (major version upgrades are breaking)
• RabbitMQ.Client (v7+ has breaking changes)
• Serilog.* (sink compatibility)
• Swashbuckle.AspNetCore (OpenAPI UI replacement candidate)
• NSwag.* (code generation — changes affect generated clients)
• Scalar.* (if already present — may conflict with Swashbuckle)

References

Skill references are in the references/version-upgrade/ directory of the dotnet plugin. To locate it, run:

find ~/.claude/plugins -type d -name "version-upgrade" -path "*/dotnet/references/*" 2>/dev/null | head -1

Files available:

Scripts are in the scripts/ directory of the dotnet plugin. To locate it, run:

find ~/.claude/plugins -type d -name "scripts" -path "*/dotnet/*" 2>/dev/null | head -1

Files available:

Standards references in the standards plugin:

• references/technical-guidance/dotnet.md
• references/technical-guidance/application-profiles/dotnet-webapi-profile.md
• references/technical-guidance/application-profiles/dotnet-webapi-v10-profile.md
• references/technical-guidance/application-profiles/dotnet-function-app-profile.md
• references/technical-guidance/application-profiles/dotnet-function-v10-profile.md
• references/technical-guidance/application-profiles/dotnet-mixed-solution-profile.md