Common Issues When Upgrading to .NET 9 — A Step-by-Step Guide

Upgrading to the latest .NET version always feels exciting — better runtime performance, new language features, improved trimming/AOT, and modern cloud-native support. But let’s be honest: upgrades also bring surprises — build errors, runtime changes, or third-party libraries not ready for the new framework.

When I upgraded my projects to .NET 9, I hit multiple roadblocks. Some were minor warnings, others were runtime crashes that took hours to figure out. That’s why I wrote this step-by-step guide, so you can learn from my mistakes and upgrade smoothly.

📌 Quick fact: .NET 9 is a Standard-Term Support (STS) release (18 months of support). It’s focused on performance, trimming/AOT improvements, and cloud-native workloads.
👉 Official .NET 9 overview

🚨 Common Problems You’ll Likely Face

1. SDK / toolchain mismatch between dev machine, CI, and Docker images.

2. BinaryFormatter removed — legacy serialization code just breaks.

3. EF Core 9 changes — pending migrations now throw at runtime.

4. ASP.NET Core tweaks (MapStaticAssets, proxy headers).

5. Third-party NuGet packages lagging behind.

6. Trimming/AOT surprises when reflection-heavy code disappears in publish.

Step 1 — Update Your Environment

The first upgrade mistake I made was only updating my local SDK but forgetting CI/CD agents. Always start with the environment:

• Install the .NET 9 SDK everywhere.

• Pin the SDK with global.json:

{
  "sdk": {
    "version": "9.0.x",
    "rollForward": "disable"
  }
}

• Update Docker images:

FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS base
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build

• Confirm versions:

dotnet --list-sdks
dotnet --info

👉 More info: Upgrade to .NET 9 guide

Step 2 — Update Project Files

Open each .csproj and bump your target framework:

<PropertyGroup>
  <TargetFramework>net9.0</TargetFramework>
</PropertyGroup>

If you multi-target, add net9.0 inside <TargetFrameworks>.

Then run:

dotnet restore
dotnet build

Step 3 — Update Dependencies

The next thing I ran into: NuGets not supporting net9.0.

Run:

dotnet list package --outdated

• Update Microsoft packages (ASP.NET Core, EF Core, Extensions) first.

• Then check third-party packages — some might not yet support .NET 9.

• If stuck: replace them, use a compatibility shim, or hold production upgrade until stable.

Step 4 — Breaking Changes (The Big Pain Points)

👉 Full list: Breaking changes in .NET 9

BinaryFormatter is Gone

Any code using it will break. For example:

// Old way (removed)
var bf = new BinaryFormatter();
using var ms = new MemoryStream(bytes);
var obj = (MyDto)bf.Deserialize(ms);

// New way (safe)
var obj = JsonSerializer.Deserialize<MyDto>(Encoding.UTF8.GetString(bytes));

API Overloads

Some string/Span overloads now conflict → you may need explicit casts.

Runtime Behavior

Float-to-int conversions behave differently in JIT → test number-sensitive logic.

Step 5 — ASP.NET Core Changes

👉 See: ASP.NET Core in .NET 9

• Static files: new MapStaticAssets() in templates (with fingerprinting). Stick with UseStaticFiles() if you host custom static content.

• Proxy headers: changes to forwarded headers — double-check reverse proxy setups.

• Blazor: reconnection and SignalR serialization tweaks — test carefully.

Step 6 — EF Core 9 Pitfalls

👉 See: EF Core 9 Breaking Changes

• Migrations: calling Migrate() now throws if there are pending model changes.

• Transactions: EF wraps Migrate() in a transaction — if you wrapped it already, expect conflicts.

• Cosmos DB: discriminator/JSON mapping changed.

• Sync I/O: Cosmos now throws on sync calls → go async.

Step 7 — Trimming & AOT Surprises

If you publish with trimming:

dotnet publish -c Release -p:PublishTrimmed=true

Reflection-based code can vanish.
Fix it with [DynamicDependency], source generators, or configuration files.

👉 Trimming in .NET 9

Step 8 — CI/CD & Hosting

• Update pipeline agents with .NET 9 SDK.

• Update Docker FROM images.

• Verify hosting platform (Azure App Service, Functions, AWS, etc.) supports .NET 9.

Step 9 — Testing & Rollout Strategy

• Run unit, integration, and end-to-end tests on net9.0.

• Use canary deployments → push one service first, monitor, then roll out.

• Always have a rollback plan.

🚀 Benchmarking .NET 8 vs .NET 9

One of the main reasons to upgrade is performance. .NET 9 brings improvements in JIT, GC, and async handling — but how much does it matter in practice? Let’s run a quick benchmark.

I used BenchmarkDotNet to compare a simple JSON serialization and string processing task in .NET 8 vs .NET 9.

Sample Benchmark Code

using BenchmarkDotNet.Attributes;
using BenchmarkDotNet.Running;
using System.Text.Json;

public class SerializationBenchmarks
{
    private readonly MyDto _dto = new MyDto { Id = 1, Name = "Kamlesh", Value = 123.45 };

    [Benchmark]
    public string Serialize()
    {
        return JsonSerializer.Serialize(_dto);
    }

    [Benchmark]
    public MyDto Deserialize()
    {
        var json = JsonSerializer.Serialize(_dto);
        return JsonSerializer.Deserialize<MyDto>(json)!;
    }

    [Benchmark]
    public string StringConcat()
    {
        string result = "";
        for (int i = 0; i < 1000; i++)
            result += "dotnet";
        return result;
    }
}

public class MyDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public double Value { get; set; }
}

class Program
{
    static void Main(string[] args)
    {
        var summary = BenchmarkRunner.Run<SerializationBenchmarks>();
    }
}

Run it on both .NET 8 and .NET 9.

Results (Sample Output)

👉 The exact numbers vary depending on your machine, but the trend is clear: .NET 9 consistently outperforms .NET 8 in common tasks.

Why This Matters

• Serialization and string operations are common in APIs — so you’ll feel the gains directly.

• Multiply these improvements across thousands of requests, and you get better throughput + lower latency in production.

• Combine with .NET 9’s trimming/AOT, and you also reduce app size + startup time.

✅ Quick Pre-Production Checklist

• All machines/CI on same SDK (global.json).

• All NuGets updated.

• No BinaryFormatter.

• EF Core migrations applied.

• Trimming/AOT validated.

• Smoke tests pass.

• Rollback plan ready.

🙋 FAQs

Q: Should I upgrade right away?
If you need new features and performance → yes. For long-term stability, you might wait for the next LTS.

Q: My app still uses BinaryFormatter, what now?
Migrate to System.Text.Json or Protobuf. Create a migration tool for old data.

Q: EF migrations broke, why?
Because EF Core 9 enforces pending migrations. Add migrations before calling Migrate().

🎯 Conclusion

Upgrading to .NET 9 doesn’t have to be stressful. Most of the headaches — BinaryFormatter removal, EF Core migrations, ASP.NET tweaks — are solvable once you know where to look.

This guide gives you a field-tested upgrade path:

• Beginners can follow the steps confidently.

• Experts get deeper coverage of trimming, EF Core, and CI/CD.

With proper testing and rollback planning, you’ll be running on .NET 9 smoothly — and ready to enjoy its performance and modern features right away.