Workik.

.NET 8 to .NET 10 Migration: An Enterprise Upgrade Guide

Upgrade .NET 8 Projects to .NET 10: SDK, TFM and Packages

Move .NET 8 projects to net10.0: update global.json, target frameworks and NuGet packages, adopt Central Package Management and fix NU1510.

Once you complete your inventory and assessment, you can begin the mechanical upgrade of your project files. Upgrading from .NET 8 to .NET 10 LTS (Long Term Support) requires updating your Software Development Kit (SDK) version, your Target Framework Moniker (TFM), and your core package dependencies across the entire solution.

Previous lesson: Assess Your .NET 8 Solution Before Upgrading | Next lesson: .NET 9 and .NET 10 Breaking Changes in Core Libraries


Pin the SDK with global.json

A global.json file in the root directory ensures every developer and continuous integration pipeline uses the expected .NET SDK. Without this file, the dotnet CLI (Command-Line Interface) selects the latest SDK installed on the machine, which can lead to mismatched builds across team members.

You define the required SDK version and set how the tooling rolls forward to newer patches or minor feature bands.

Before (.NET 8):

json
Copy

After (.NET 10):

json
Copy

Setting rollForward to latestFeature allows your build agents to use newer patch versions such as 10.0.102 or future feature bands like 10.0.200 without forcing an immediate commit to global.json.

Common Mistake: Do not specify a concrete patch version like 10.0.104 with default roll forward behavior in teams where developers update their local SDKs at different times. If a developer has only 10.0.100 installed, the build fails immediately.

Lock your developer environments to the .NET 10 branch while permitting non-breaking feature and patch roll-forwards.


Update the Target Framework Moniker (TFM)

Every project file in your solution must target net10.0 to run on the .NET 10 runtime and consume .NET 10 APIs. Rather than editing every .csproj file across Larkfield.Claims.Api, Larkfield.Portal, and Larkfield.Billing.Worker, you can manage the target framework centrally using a Directory.Build.props file in your repository root.

If your solution does not have a Directory.Build.props file yet, create one.

After (.NET 10):

xml
Copy

When you define TargetFramework in Directory.Build.props, remove the <TargetFramework> tag from individual project files.

Before (.NET 8):

xml
Copy

After (.NET 10):

xml
Copy

Pro Tip: If you maintain shared internal libraries that external teams still consume on .NET 8, multi-target those specific projects using <TargetFrameworks>net8.0;net10.0</TargetFrameworks>. This keeps downstream consumers operational while you migrate internal applications.

Centralizing the target framework in one root property file eliminates repetitive configuration and prevents version drift.


Central Package Management and Updating Dependencies

Managing package versions individually across multiple microservices leads to version mismatch and diamond dependency conflicts. Central Package Management (CPM) consolidates all package versions into a single Directory.Packages.props file.

Think of CPM as a master inventory list in a warehouse where individual departments choose what items they need, but the purchasing team controls the exact version.

Enable CPM in Directory.Packages.props:

After (.NET 10):

xml
Copy

Update all packages in the Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*, and Microsoft.Extensions.* namespaces to 10.0.0 or higher. Keep EF Core in step with the runtime: EF Core 10 requires .NET 10, so you update both together.

Inside your project files, declare dependencies without a Version attribute:

After (.NET 10):

xml
Copy

Quick Challenge: Open one of your secondary service project files. If you find a PackageReference that defines a Version attribute while ManagePackageVersionsCentrally is set to true, delete that attribute or convert it to VersionOverride if a temporary deviation is strictly required.

Updating package versions centrally guarantees that your web API, worker, and customer portal run on uniform Microsoft library baselines.


Understand .NET 10 SDK Behaviors and Noun-First CLI Commands

The .NET 10 SDK introduces changes to package validation, framework dependencies, and terminal operations that you must account for during your build setup.

Framework Package Pruning (Warning NU1510)

Projects targeting net10.0 automatically receive pruning for packages already provided directly by the shared framework. For example, if your web project explicitly references Microsoft.Extensions.Logging or Microsoft.AspNetCore.Http.Abstractions, the .NET 10 build emits warning NU1510 stating that the reference was pruned.

To clear NU1510 warnings, inspect your project dependencies and delete package references that mirror APIs inside Microsoft.NET.Sdk.Web.

Strict Package Reference Requirements

Previous SDKs only warned when a PackageReference outside CPM had no Version attribute. In the .NET 10 SDK, a PackageReference without a version or CPM entry is a build error.

Transitive NuGet Auditing

Running dotnet restore in the .NET 10 SDK audits transitive packages for known security vulnerabilities by default. Warnings now appear directly during restore if a deep child dependency has an open vulnerability advisory.

Solution File Changes

Running dotnet new sln in .NET 10 creates the new SLNX XML-based solution format by default instead of the older text-based .sln structure. Existing .sln files continue to work without modification, but new repositories will use the .slnx extension.

Interactive CLI Prompts

The CLI sets --interactive to true by default when it detects an interactive terminal. In build scripts and CI pipelines, you must pass --interactive false to prevent commands from stalling while waiting for credentials.

Noun-First CLI Syntax

The .NET CLI supports noun-first syntax commands. While traditional verb-first commands remain functional, noun-first commands provide a cleaner structure for script automation.

TaskVerb-First Syntax (Legacy)Noun-First Syntax (.NET 10)
Add a packagedotnet add package PackageNamedotnet package add PackageName
List packagesdotnet list packagedotnet package list
Remove a packagedotnet remove package PackageNamedotnet package remove PackageName
Add a referencedotnet add reference Other.csprojdotnet reference add Other.csproj

Using modern CLI syntax and resolving NU1510 pruning notices keeps your solution free of build noise.


Build and Resolve Obsoletion Warnings

Once your SDK, TFM, and dependencies are updated, build the solution using the command line to observe compiler feedback.

bash
Copy

Inspect the output for newly raised diagnostic warnings. The .NET 10 compiler marks older APIs as obsolete and flags potential runtime issues before deployment.

Try This: Run your build with warnings treated as errors locally by appending /warnaserror to your build command. This prevents new deprecation warnings from slipping into your Git repository:

bash
Copy

If you encounter warnings for features that are scheduled for replacement in later lessons (such as moving from Swashbuckle to built-in OpenAPI), address them systematically instead of blanketing your project files with <NoWarn>. Keeping warnings visible ensures your team addresses underlying technical debt.

Treat compiler warnings as active indicators of runtime breaking changes rather than cosmetic suggestions.


Try It Yourself

Put these steps into practice by upgrading the configuration files for your solution.

  1. Create or edit global.json in the root of your repository to pin SDK 10.0.100 with latestFeature roll-forward.
  2. Verify the active SDK from your terminal:
    bash
    Copy
  3. Add or update Directory.Build.props in your repository root to declare <TargetFramework>net10.0</TargetFramework>.
  4. Open your individual project files (Larkfield.Claims.Api.csproj, Larkfield.Portal.csproj, Larkfield.Billing.Worker.csproj) and remove redundant <TargetFramework> tags.
  5. Create Directory.Packages.props with <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> and define 10.0.0 versions for all Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*, and Microsoft.Extensions.* dependencies.
  6. Run a restore and clean build:
    bash
    Copy
  7. Check the build log for warning NU1510. Remove any explicit package references identified as framework-provided.

In the next lesson, .NET 9 and .NET 10 Breaking Changes in Core Libraries, you will explore breaking changes across runtime, networking, and serialization libraries.

Was this lesson helpful?