What Changes When You Move an Existing App to .NET 11

public class OrderProcessor(
    ILogger<OrderProcessor> logger) : BackgroundService
{
    protected override async Task ExecuteAsync(
        CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            await ProcessOrders(stoppingToken);

            await Task.Delay(
                TimeSpan.FromSeconds(10),
                stoppingToken);
        }
    }

    private Task ProcessOrders(
        CancellationToken cancellationToken)
    {
        logger.LogInformation("Processing orders");

        return Task.CompletedTask;
    }
}

The important part is not only whether the worker starts.

Test what happens when:

Database becomes unavailable
        ↓
Message broker becomes unavailable
        ↓
External API times out
        ↓
Unexpected exception occurs
        ↓
Cancellation is requested
        ↓
Application shuts down

A background process that stops unexpectedly can create serious operational problems without making the main API unavailable.

For applications that process payments, orders, notifications, messages, or scheduled jobs, background-worker behavior should be part of the migration test plan.

Check Runtime and Performance Behavior

A newer .NET runtime can contain improvements to areas such as JIT compilation, async execution, memory management, and other runtime operations.

That does not mean every application will automatically become faster.

Application performance is usually influenced by many layers:

Application code
      ↓
.NET runtime
      ↓
Database
      ↓
Network
      ↓
External services
      ↓
Infrastructure

A framework upgrade changes one important part of that system, but it does not eliminate bottlenecks elsewhere.

For this reason, establish performance baselines before migration.

For example:

Before migration

Requests/sec:     1,200
P95 latency:      180 ms
P99 latency:      420 ms
CPU:              48%
Memory:           1.4 GB
Error rate:       0.08%

After migration, collect the same measurements under comparable workloads.

The useful question is not:

"Is the new .NET version faster?"

Instead, ask:

"How did this application behave before and after the migration?"

That gives the team measurable evidence instead of relying on assumptions.

Check the Production Environment

The development machine is not the production environment.

Before deployment, verify the infrastructure that actually runs the application.

Check:

• Operating system
• CPU architecture
• Container runtime
• Memory limits
• Native libraries
• Certificates
• File permissions
• Environment variables
• Secret providers
• Cloud identity
• Network configuration
• Database connectivity

This becomes especially important for applications running on older servers, specialized infrastructure, self-hosted CI runners, or platform-specific environments.

A local build can succeed while the production environment is missing a required runtime dependency.

Update Docker Images

If the application runs inside containers, the Dockerfile must be reviewed as part of the migration.

A Dockerfile might currently contain:

FROM mcr.microsoft.com/dotnet/aspnet:10.0

WORKDIR /app

COPY . .

ENTRYPOINT ["dotnet", "MyApp.dll"]

The runtime image should be changed to the appropriate .NET 11 image:

FROM mcr.microsoft.com/dotnet/aspnet:11.0

WORKDIR /app

COPY . .

ENTRYPOINT ["dotnet", "MyApp.dll"]

If the application uses a multi-stage Docker build, update the SDK image as well.

For example:

FROM mcr.microsoft.com/dotnet/sdk:11.0 AS build

WORKDIR /src

COPY . .

RUN dotnet restore

RUN dotnet publish \
    -c Release \
    -o /app/publish \
    --no-restore

FROM mcr.microsoft.com/dotnet/aspnet:11.0

WORKDIR /app

COPY --from=build /app/publish .

ENTRYPOINT ["dotnet", "MyApp.dll"]

After updating the Dockerfile, test the actual container.

Do not consider the migration complete just because dotnet run works on a developer machine.

Review the CI/CD Pipeline

The CI/CD pipeline is another part of the application.

A typical deployment path looks like this:

Developer machine
        ↓
Restore
        ↓
Build
        ↓
Test
        ↓
Container build
        ↓
Security checks
        ↓
Deployment
        ↓
Staging
        ↓
Production

Every stage needs to understand the new framework version.

Review:

• Build images
• SDK installation
• Test runners
• Docker images
• Deployment scripts
• Infrastructure definitions
• Environment configuration
• Package caching
• Artifact publishing
• Runtime health checks

A common migration mistake is updating the application repository while leaving the CI environment on the previous SDK or runtime.

The result can be confusing because the source code appears correct while the pipeline fails for infrastructure-related reasons.

Test the Database and External Integrations

A framework migration should also include integration testing.

If the application communicates with a database, message broker, cache, payment provider, storage service, or external API, test those integrations against realistic environments.

For database applications, verify:

Application startup
        ↓
Database connection
        ↓
Queries
        ↓
Transactions
        ↓
Migrations
        ↓
Connection pooling
        ↓
Error handling

Do not test only simple read operations.

Test transactions, timeouts, connection failures, retries, and application shutdown.

The same principle applies to external services.

A successful application startup tells you very little about how the application behaves when a dependency becomes slow or unavailable.

Avoid Combining Too Many Changes

One of the easiest ways to make a migration difficult is to change everything at the same time.

For example, avoid combining:

.NET upgrade
+
Database provider change
+
Major ORM upgrade
+
Authentication rewrite
+
Logging change
+
Infrastructure migration

If something breaks, finding the cause becomes unnecessarily difficult.

A more controlled migration looks like:

.NET framework
      ↓
Required package updates
      ↓
Application fixes
      ↓
Tests
      ↓
Infrastructure updates
      ↓
Performance validation
      ↓
Production deployment

Unrelated modernization work can be handled separately unless there is a strong technical reason to combine it.

A Practical Migration Process

A production application can follow this sequence:

1. Create a dedicated migration branch.
2. Verify the required .NET SDK.
3. Review global.json, if present.
4. Change the target framework to net11.0.
5. Restore dependencies.
6. Review NuGet package compatibility.
7. Resolve compilation errors.
8. Review .NET and ASP.NET Core compatibility changes.
9. Run unit tests.
10. Run integration and end-to-end tests.
11. Update Docker images.
12. Update CI/CD environments.
13. Deploy to staging.
14. Run functional and performance tests.
15. Monitor logs, metrics, and traces.
16. Deploy to production using the normal rollout process.
17. Continue monitoring after deployment.

This approach makes it easier to isolate problems because each stage has a specific purpose.

Common Migration Mistakes

Treating a successful build as a successful migration

A successful build only confirms that the source code compiles.

It does not confirm that runtime behavior, integrations, infrastructure, or performance remain correct.

Updating every NuGet package

Unnecessary package upgrades increase the number of variables involved in the migration.

Upgrade what is required and validate each significant dependency change.

Forgetting Docker and CI/CD

The application can work locally while the production build still uses an older SDK or runtime image.

Infrastructure should be included in the migration plan.

Testing only the happy path

Authentication failures, database outages, background-worker exceptions, network timeouts, and graceful shutdown behavior often reveal problems that normal functional tests miss.

Skipping performance baselines

Without before-and-after measurements, it is difficult to determine whether the migration improved or degraded application behavior.

Final Thoughts

Moving an existing application to .NET 11 is usually not a rewrite. In many applications, the source-code changes are relatively small. The larger task is validating everything around that code.

The SDK, NuGet dependencies, ASP.NET Core behavior, authentication, background services, databases, containers, CI/CD pipelines, and production infrastructure all form part of the migration.

The most important distinction is between an application that builds and an application that continues to behave correctly.

A successful migration should therefore answer several questions:

Does it build?
Does it pass tests?
Does it behave correctly?
Do integrations still work?
Does it perform acceptably?
Does it deploy correctly?
Can the team monitor and roll it back safely?

If the answer to all of these is yes, the migration is much more than a target-framework change. It is a controlled upgrade of the application's runtime environment with the necessary validation around it.