Guia prático: migrando do .NET 8 para o .NET 10

O .NET 10 chegou e trouxe melhorias significativas em performance, APIs mínimas e suporte a cloud-native. Se você tem projetos rodando em .NET 8 LTS, este guia mostra o caminho para uma migração segura e sem surpresas.

Por que migrar?

O .NET 8 continua com suporte LTS até novembro de 2026, então não há urgência. Mas o .NET 10 traz vantagens concretas:

Performance: melhorias no JIT, menor alocação de memória e startup mais rápido
Minimal APIs: novos filtros, binding de parâmetros simplificado e suporte nativo a OpenAPI 3.1
Blazor: renderização estática aprimorada e interoperabilidade com componentes nativos
AOT nativo: compilação ahead-of-time mais estável para APIs e workers
Suporte LTS: .NET 10 é LTS — suporte garantido por 3 anos

Passo 1: Atualize o SDK

Baixe o SDK do .NET 10 e verifique a instalação:

dotnet --list-sdks
# 8.0.404 [/usr/share/dotnet/sdk]
# 10.0.100 [/usr/share/dotnet/sdk]

Atualize o global.json se você usa um na raiz do projeto:

{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestMinor"
  }
}

Passo 2: Atualize o Target Framework

Em cada .csproj, troque o TargetFramework:

<!-- Antes -->
<TargetFramework>net8.0</TargetFramework>

<!-- Depois -->
<TargetFramework>net10.0</TargetFramework>

Se o projeto é multi-target, adicione:

<TargetFrameworks>net8.0;net10.0</TargetFrameworks>

Passo 3: Atualize os pacotes NuGet

Atualize todos os pacotes Microsoft.AspNetCore.*, Microsoft.Extensions.* e Microsoft.EntityFrameworkCore.* para as versões 10.x:

dotnet outdated --upgrade

Dica: Se você não tem o dotnet-outdated, instale com dotnet tool install -g dotnet-outdated-tool.

Os pacotes mais comuns que precisam de bump:

Pacote	8.x → 10.x
`Microsoft.AspNetCore.Authentication.JwtBearer`	8.0.x → 10.0.x
`Microsoft.EntityFrameworkCore.SqlServer`	8.0.x → 10.0.x
`Microsoft.Extensions.Hosting`	8.0.x → 10.0.x
`Swashbuckle.AspNetCore`	Substituído por OpenAPI nativo

Passo 4: Breaking changes para ficar atento

Swashbuckle → OpenAPI nativo

O .NET 10 oficializou o suporte a OpenAPI sem Swashbuckle. Se você usa AddSwaggerGen(), migre para:

// Antes (.NET 8 com Swashbuckle)
builder.Services.AddSwaggerGen();

// Depois (.NET 10 nativo)
builder.Services.AddOpenApi();

// No pipeline
app.MapOpenApi();

Mudanças no EF Core 10

ExecuteUpdate e ExecuteDelete agora retornam o número de linhas afetadas como long em vez de int
Novas convenções de naming para tabelas — verifique suas migrations
HasConversion<> com value objects tem novo comportamento de null handling

Minimal APIs

TypedResults agora é o padrão recomendado em vez de Results
Binding de record em query strings funciona sem [AsParameters] em cenários simples

Passo 5: Compile e rode os testes

dotnet build --warnaserror
dotnet test --logger "console;verbosity=detailed"

Corrija warnings de obsolescência — eles geralmente indicam APIs que serão removidas na próxima versão.

Passo 6: Docker

Atualize a imagem base no Dockerfile:

# Antes
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build

# Depois
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build

Se usa AOT nativo:

FROM mcr.microsoft.com/dotnet/nightly/runtime-deps:10.0-noble-chiseled AS base

Passo 7: CI/CD

Atualize os pipelines para usar o SDK 10:

# GitHub Actions
- uses: actions/setup-dotnet@v4
  with:
    dotnet-version: "10.0.x"

Checklist de migração

Conclusão

A migração do .NET 8 para o .NET 10 é direta para a maioria dos projetos. Os maiores pontos de atenção são o Swashbuckle (agora obsoleto), mudanças no EF Core e atualização de imagens Docker. Reserve uma sprint focada, siga o checklist e valide bem em staging antes de ir para produção.

Precisa de ajuda com a migração do seu projeto? A DevPlus tem experiência em modernização de stacks .NET. Fale com a gente.