.NET 11 is arriving with changes across the runtime, libraries, SDK, networking, ASP.NET Core, and developer tooling. For teams maintaining existing applications, the important question is not only what is new, but what needs to be checked before moving a production application to the new runtime.
.NET 11 is currently in the release-candidate stage, with general availability expected in November 2026. Microsoft has also announced the .NET 11 launch as part of .NET Conf 2026.
An upgrade should therefore be treated as a compatibility and validation exercise rather than simply changing the target framework from net10.0 to net11.0.
This article walks through a practical checklist for upgrading an ASP.NET Core application to .NET 11.
Start With the Current Application
Before changing the project file, understand what the application currently depends on.
Check:
For a typical ASP.NET Core application, the project file may currently contain:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
</Project>
The first upgrade step is straightforward:
<TargetFramework>net11.0</TargetFramework>
But changing this one line does not prove that the application is ready for production.
Check the .NET 11 SDK First
Install the .NET 11 SDK in a development or isolated environment before changing production infrastructure.
Verify the SDK:
dotnet --version
Then check the installed SDKs:
dotnet --list-sdks
For a team environment, consider adding a global.json file so developers and CI systems use the intended SDK version.
For example:
{
"sdk": {
"version": "11.0.100"
}
}
The exact SDK version should match the version your team has standardized on after .NET 11 reaches the required release state.
Update the Target Framework
Once the SDK is available, update the application:
<PropertyGroup>
<TargetFramework>net11.0</TargetFramework>
</PropertyGroup>
Then restore and build:
dotnet restore
dotnet build
Do this before making additional application changes.
The first build result is useful because it identifies compatibility issues early.
A successful build does not mean the migration is complete. Runtime behavior, integration tests, deployment configuration, and third-party packages still need to be checked.
Review NuGet Dependencies
NuGet dependencies are one of the first places to look when an application moves to a new .NET version.
Run:
dotnet list package --outdated
Also inspect direct and transitive dependencies:
dotnet list package
Look for packages that:
Do not support net11.0
Depend on older framework versions
Use deprecated APIs
Include native components
Have newer versions specifically supporting .NET 11
Do not automatically upgrade every package at the same time.
A better approach is to separate the framework migration from unrelated dependency upgrades.
For example:
.NET 10
|
+-- Upgrade application to .NET 11
|
+-- Fix compatibility issues
|
+-- Run tests
|
+-- Upgrade selected dependencies
|
+-- Run tests again
This makes failures easier to diagnose.
Review ASP.NET Core Dependencies
ASP.NET Core applications often depend on more than the main Microsoft packages.
Check packages related to:
Authentication
Authorization
OpenAPI
JSON serialization
Entity Framework Core
Health checks
Background jobs
Messaging
Caching
Distributed tracing
Rate limiting
API documentation
If a package depends on a specific ASP.NET Core version, verify that its supported version aligns with the .NET 11 application.
Avoid ignoring package compatibility warnings simply because the application compiles.
Review Runtime Changes
.NET 11 includes runtime changes that can affect application performance and behavior.
Microsoft documents changes to the JIT, async execution, NativeAOT, hardware intrinsics, and other runtime areas.
One area receiving significant attention is runtime-native async.
The runtime can now manage async suspension and resumption differently from previous compiler-generated approaches, with associated performance and debugging improvements.
For most application teams, this does not mean rewriting existing async code.
Instead, existing asynchronous code should be tested under the new runtime.
Pay particular attention to:
public async Task<IActionResult> GetOrders()
{
var orders = await service.GetOrdersAsync();
return Ok(orders);
}
Do not replace working async code simply because the runtime has improved its async implementation.
Measure the application first.
Test HTTP and Networking Behavior
ASP.NET Core applications often spend a significant amount of time communicating with other services.
.NET 11 introduces networking changes including configurable HTTP connection eviction, HTTP request-body compression, improved HTTP/2 handling, DNS APIs, and other networking improvements.
Review applications that use:
HttpClient
especially when they maintain long-lived connections to external services.
A typical production configuration might use IHttpClientFactory:
builder.Services.AddHttpClient("OrdersApi", client =>
{
client.BaseAddress =
new Uri("https://orders.example.internal");
});
Then:
var client = httpClientFactory.CreateClient("OrdersApi");
var response = await client.GetAsync("api/orders");
The upgrade is a good opportunity to verify connection lifetime, timeout, retry, and DNS behavior.
Test JSON Serialization
System.Text.Json continues to receive improvements in .NET 11, including additional support around unions, JSON Lines, polymorphism, source generation, naming, and collection contracts.
Applications that use custom JSON converters should receive particular attention.
For example:
builder.Services.ConfigureHttpJsonOptions(options =>
{
options.SerializerOptions.PropertyNamingPolicy =
JsonNamingPolicy.CamelCase;
});
Run API integration tests against real payloads rather than relying only on unit tests.
Verify:
Property names
Null handling
Enum serialization
Custom converters
Polymorphic types
Date/time formatting
Request validation
Response compatibility
This is especially important for APIs consumed by older mobile or desktop clients.
Review API Compatibility
A runtime upgrade should not accidentally change your public API contract.
Before deployment, compare representative API responses from the old and new versions.
For example:
.NET 10 Application
|
v
GET /api/customers/123
|
v
Response Snapshot
.NET 11 Application
|
v
GET /api/customers/123
|
v
Response Snapshot
Compare:
HTTP status codes
Headers
JSON structure
Property names
Null values
Validation errors
Error responses
An application can compile successfully while still introducing an API behavior change.
Test Authentication and Authorization
Authentication middleware should be tested independently.
Check:
For example:
app.UseAuthentication();
app.UseAuthorization();
Run tests for both authenticated and unauthenticated requests.
Also verify that failed authentication produces the expected response rather than exposing internal exception details.
Test Entity Framework Core
If the application uses Entity Framework Core, treat the EF Core version as a separate dependency to validate.
Test:
A migration should not be considered successful simply because the application starts.
Run representative production queries against a test database.
For example:
var customers = await dbContext.Customers
.Where(c => c.IsActive)
.OrderBy(c => c.Name)
.Take(100)
.ToListAsync();
Measure query execution time before and after the upgrade.
Review Docker Images
If the application is containerized, update the base image as part of the migration.
For example:
FROM mcr.microsoft.com/dotnet/aspnet:11.0 AS runtime
WORKDIR /app
COPY . .
ENTRYPOINT ["dotnet", "MyApplication.dll"]
The exact image tag should match the supported .NET 11 release you are deploying.
Also update the SDK image used for building:
FROM mcr.microsoft.com/dotnet/sdk:11.0 AS build
Do not update only the runtime image while leaving the build environment on an incompatible SDK.
Check CI/CD Pipelines
The development machine may use .NET 11 while CI still uses .NET 10.
That can create confusing build failures.
Review:
Developer SDK
|
v
Source Control
|
v
CI Build Image
|
v
Automated Tests
|
v
Container Build
|
v
Production Runtime
Every stage should use a deliberate SDK/runtime version.
Update:
GitHub Actions
Azure Pipelines
GitLab CI
Jenkins
Docker build images
Deployment agents
Test environments
Then run the complete pipeline before production deployment.
Test Performance Before and After
Do not assume .NET 11 will automatically make your application faster.
Measure it.
Useful metrics include:
Requests per second
Average latency
p95 latency
p99 latency
CPU utilization
Memory usage
GC activity
Database latency
HTTP client latency
Startup time
For example:
Metric Before After
Requests/sec 2,100 2,150
p95 latency 180 ms 165 ms
CPU 62% 58%
Memory 420 MB 405 MB
These numbers are illustrative. Use actual production-like benchmark data when making upgrade decisions.
Pay Attention to Hardware Requirements
.NET 11 updates the minimum hardware requirements for some x86/x64 and Arm64 scenarios. Microsoft documents a move from x86-64-v1 to x86-64-v2 for supported x86/x64 environments, along with updated Arm64 requirements for some platforms.
This matters when applications run on older virtual machines or specialized infrastructure.
Before upgrading, check:
Production VM
|
+-- CPU architecture
+-- Instruction-set support
+-- Operating system
+-- Container runtime
+-- Hosting platform
Do not assume that every old server configuration is automatically suitable for the new runtime.
Test Background Services
ASP.NET Core applications frequently host background workers.
For example:
public sealed class OrderWorker(
IServiceScopeFactory scopeFactory)
: BackgroundService
{
protected override async Task ExecuteAsync(
CancellationToken stoppingToken)
{
while (!stoppingToken.IsCancellationRequested)
{
using var scope = scopeFactory.CreateScope();
var service =
scope.ServiceProvider
.GetRequiredService<IOrderService>();
await service.ProcessAsync(stoppingToken);
await Task.Delay(
TimeSpan.FromMinutes(1),
stoppingToken);
}
}
}
Test:
Graceful shutdown
Cancellation tokens
Database connections
Queue processing
Retry behavior
Duplicate processing
Worker startup
Worker restart
A runtime upgrade can expose issues that are invisible during normal API testing.
Use Staged Deployment
Do not make the first .NET 11 deployment a full production rollout.
A safer approach is:
Development
|
v
Automated Tests
|
v
Staging
|
v
Production Canary
|
v
Small Traffic Percentage
|
v
Full Production
Monitor the canary deployment for errors, latency, CPU, memory, database load, and external dependency failures.
If the metrics remain healthy, continue the rollout.
Common Mistakes
Updating the target framework and stopping there
Changing net10.0 to net11.0 is only the beginning.
Upgrading every NuGet package simultaneously
This makes compatibility problems difficult to isolate.
Ignoring native dependencies
Native libraries may have architecture or runtime requirements that managed packages do not expose clearly.
Testing only successful API requests
Error handling, authentication failures, timeouts, and malformed input need testing too.
Forgetting CI/CD
A developer machine using .NET 11 does not mean the deployment pipeline is ready.
Skipping performance benchmarks
Runtime improvements should be validated against your actual workload.
Deploying directly to all production instances
Use staged rollout when the application is business-critical.
Recommended Upgrade Checklist
Before moving an ASP.NET Core application to .NET 11, verify:
[ ] .NET 11 SDK installed
[ ] Target framework updated
[ ] NuGet dependencies reviewed
[ ] ASP.NET Core dependencies verified
[ ] Authentication tested
[ ] Authorization tested
[ ] JSON serialization tested
[ ] API contracts compared
[ ] EF Core queries tested
[ ] Database migrations tested
[ ] HttpClient behavior tested
[ ] Background workers tested
[ ] Docker images updated
[ ] CI/CD updated
[ ] Production hardware checked
[ ] Performance benchmark completed
[ ] Integration tests passed
[ ] Staging deployment completed
[ ] Rollback plan prepared
[ ] Production monitoring configured
Advantages of Moving to .NET 11
The upgrade provides access to the latest .NET platform improvements, including runtime, library, networking, SDK, and language changes. Microsoft also highlights improvements in areas such as JSON handling, HTTP networking, diagnostics, compression, numeric APIs, and async execution.
For applications that regularly update their platform version, adopting .NET 11 can also reduce the amount of technical debt accumulated from staying several releases behind.
What Should Not Be Changed During the Upgrade
A useful migration rule is to avoid changing unrelated architecture at the same time.
For example, do not combine:
.NET 10 → .NET 11
+
Database migration
+
Authentication rewrite
+
Microservices conversion
+
New messaging platform
unless there is a strong reason to do so.
A smaller change set makes production failures easier to understand.
A better approach is:
.NET 10
|
v
.NET 11
|
v
Validate
|
v
Stabilize
|
v
Make Next Architecture Change
Final Thoughts
Upgrading an ASP.NET Core application to .NET 11 should be treated as a controlled engineering change rather than a project-file edit.
Start with dependency compatibility, then test the runtime, networking, JSON serialization, database access, authentication, background services, containers, and CI/CD pipeline.
Performance should be measured rather than assumed, and production rollout should be gradual for applications where downtime or regressions are expensive.
.NET 11 brings meaningful changes across the platform, but the best upgrade is not the one that adopts every new feature immediately. It is the one that moves the existing application to the new runtime with predictable behavior, measurable performance, and a clear rollback path.
Join the conversation! Your thoughts help the community grow.