Compartilhar via

Atualizar para uma nova versão do .NET

Novas versões do .NET são lançadas a cada ano. Muitos desenvolvedores iniciam o processo de atualização assim que a nova versão está disponível, enquanto outros esperam até que a versão que estão usando não tenha mais suporte. Há vários aspectos que devem ser considerados no processo de atualização.

Motivos comuns para atualizar para uma nova versão do .NET:

  • Não há mais suporte para a versão do .NET usada no momento
  • A nova versão dá suporte a um novo sistema operacional
  • A nova versão tem um recurso importante de API, desempenho ou segurança

Atualizar ambiente de desenvolvimento

Para atualizar para uma nova versão do .NET, o SDK do .NET é o componente principal a ser instalado. Ele inclui uma versão da CLI do .NET atualizada, do sistema de build e do runtime.

O site do .NET oferece instaladores e arquivos que você pode baixar e usar em qualquer sistema operacional e arquitetura com suporte.

Alguns sistemas operacionais têm um gerenciador de pacotes que você também pode usar para instalar uma nova versão do .NET, que você pode preferir.

O Visual Studio instala novas versões do SDK do .NET automaticamente. Para usuários do Visual Studio, é suficiente atualizar para uma versão mais recente do Visual Studio.

Atualizar código-fonte

A única alteração necessária para atualizar um aplicativo é atualizar a propriedade TargetFramework em um arquivo de projeto para a versão mais recente do .NET.

Veja como fazer isso:

  • Abra o arquivo de projeto (o arquivo *.csproj, *.vbproj ou *.fsproj).
  • Altere o valor da propriedade <TargetFramework> de, por exemplo, net6.0 para net8.0.
  • O mesmo padrão se aplica à propriedade <TargetFrameworks> se ela estiver sendo usada.

Dica

A capacidade de modernização do aplicativo GitHub Copilot de atualização pode fazer essas alterações automaticamente.

A próxima etapa é criar o projeto (ou solução) com o novo SDK. Se forem necessárias alterações adicionais, o SDK fornecerá avisos e erros que o orientarão.

Talvez seja necessário executar dotnet workload restore para restaurar cargas de trabalho com a nova versão do SDK.

Mais recursos:

Fixação de versão

Ao atualizar ferramentas de desenvolvimento como o SDK do .NET, o Visual Studio ou outros componentes, você pode encontrar novos comportamentos, avisos do analisador ou alterações interruptivas que afetam o processo de build. Ao fixar uma versão, você pode atualizar seu ambiente de desenvolvimento, mantendo o controle sobre quando componentes específicos são atualizados em seus projetos.

A fixação de versão oferece vários benefícios:

  • Builds previsíveis: assegura resultados de builds consistentes em diferentes computadores e ambientes de CI/CD.
  • Adoção gradual: permite que você adote novos recursos incrementalmente, em vez de todos de uma vez.
  • Evite alterações inesperadas: impede que novas regras do analisador, comportamentos do SDK ou versões de pacote causem falhas de build.
  • Coordenação de equipe: permite que as equipes atualizem juntas em um momento planejado em vez de individualmente quando as ferramentas são atualizadas.
  • Depuração e solução de problemas: torna mais fácil isolar problemas quando você controla quais versões foram alteradas.

As seções a seguir descrevem vários mecanismos para controlar versões de diferentes componentes em seus projetos do .NET:

Controlar a versão do SDK com global.json

Você pode fixar a versão do SDK do .NET para um projeto ou solução usando um arquivo global.json . Este arquivo especifica qual versão do SDK usar ao executar comandos da CLI do .NET e é independente da versão de runtime que seu projeto visa.

Crie um arquivo global.json no diretório raiz da solução:

dotnet new globaljson --sdk-version 9.0.100 --roll-forward latestFeature

Esse comando cria o seguinte arquivo global.json que fixa o SDK na versão 9.0.100 ou qualquer patch ou faixa de recursos posterior na versão principal do 9.0:

{
  "sdk": {
    "version": "9.0.100",
    "rollForward": "latestFeature"
  }
}

A rollForward política controla como a versão do SDK é selecionada quando a versão exata não está disponível. Essa configuração garante que, ao atualizar o Visual Studio ou instalar um novo SDK, seu projeto continue a usar o SDK 9.0.x até que você atualize explicitamente o arquivo global.json .

Para obter mais informações, consulte global.json visão geral.

Controlar o comportamento do analisador

Os analisadores de código podem introduzir novos avisos ou alterar o comportamento entre versões. Você pode controlar as versões do analisador para manter builds consistentes usando a AnalysisLevel propriedade. Essa propriedade permite que você bloqueie uma versão específica das regras do analisador, impedindo que novas regras sejam introduzidas ao atualizar o SDK.

<PropertyGroup>
  <AnalysisLevel>9.0</AnalysisLevel>
</PropertyGroup>

Quando definido como 9.0, somente as regras do analisador que foram enviadas com o .NET 9 estão habilitadas, mesmo se você estiver usando o SDK do .NET 10. Isso impede que novas regras do analisador do .NET 10 afetem seu build até que você esteja pronto para resolvê-las.

Para obter mais informações, consulte AnalysisLevel.

Controlar versões do pacote NuGet

Ao gerenciar versões de pacote de forma consistente em projetos, você pode evitar atualizações inesperadas e manter builds confiáveis.

Arquivos de bloqueio de pacote

Os arquivos de bloqueio de pacote garantem que as operações de restauração de pacote usem exatamente as mesmas versões de pacote em ambientes diferentes. O arquivo de bloqueio (packages.lock.json) registra as versões exatas de todos os pacotes e suas dependências.

Habilite arquivos de bloqueio no arquivo de projeto:

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>

Para garantir que os builds falhem se o arquivo de bloqueio estiver desatualizado:

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
  <RestoreLockedMode>true</RestoreLockedMode>
</PropertyGroup>

Depois de habilitar arquivos de bloqueio, execute dotnet restore para gerar o arquivo packages.lock.json . Submeta este arquivo ao controle de versão.

Gerenciamento de pacote central

O CPM (gerenciamento central de pacotes) permite que você gerencie versões de pacote em um único local para todos os projetos em uma solução. Essa abordagem simplifica o gerenciamento de versão e garante a consistência entre projetos.

Crie um arquivo Directory.Packages.props na raiz da solução:

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Azure.Identity" Version="1.17.0" />
    <PackageVersion Include="Microsoft.Extensions.AI" Version="9.10.1" />
  </ItemGroup>
</Project>

Em seus arquivos de projeto, faça referência a pacotes sem especificar uma versão:

<ItemGroup>
  <PackageReference Include="Azure.Identity" />
  <PackageReference Include="Microsoft.Extensions.AI" />
</ItemGroup>

Mapeamento de origem do pacote

O mapeamento de origem do pacote permite controlar quais feeds do NuGet são usados para pacotes específicos, melhorando a segurança e a confiabilidade.

Configure o mapeamento de origem no arquivo nuget.config :

<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso" value="https://contoso.com/packages/" />
  </packageSources>

  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso">
      <package pattern="Contoso.*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Essa configuração garante que todos os pacotes que começam com Contoso. sejam restaurados apenas do contoso feed, enquanto outros pacotes são provenientes.nuget.org

Para obter mais informações, consulte restauração do pacote NuGet.

Controlar a versão do MSBuild

O Visual Studio dá suporte à instalação lado a lado de várias versões. Por exemplo, você pode instalar o Visual Studio 2026 e o Visual Studio 2022 no mesmo computador. Cada versão do Visual Studio inclui um SDK do .NET correspondente. Quando você atualiza o Visual Studio, a versão do SDK incluída também é atualizada. No entanto, você pode continuar usando versões mais antigas do SDK instalando-as separadamente da página de download do .NET.

As versões do MSBuild correspondem às versões do Visual Studio. Por exemplo, o Visual Studio 2022 versão 17.8 inclui o MSBuild 17.8. O SDK do .NET também inclui o MSBuild. Ao usar dotnet build, você está usando a versão do MSBuild incluída com o SDK especificado por global.json ou o SDK instalado mais recente.

Para usar uma versão específica do MSBuild:

  • Use dotnet build com uma versão do SDK fixada no global.json.
  • Inicie o Prompt de Comando do Desenvolvedor do Visual Studio preferencial, que configura o ambiente para o MSBuild daquela versão do Visual Studio.
  • Invoque diretamente o MSBuild de uma instalação específica do Visual Studio (por exemplo, "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe").

Para obter mais informações, consulte o SDK do .NET, o MSBuild e o controle de versão do Visual Studio.

Atualizar a CI (integração contínua)

Os pipelines de CI seguem um processo de atualização semelhante como arquivos de projeto e Dockerfiles. Normalmente, você pode atualizar pipelines de CI alterando apenas os valores de versão.

Atualizar o ambiente de hospedagem

Há muitos padrões que são usados para hospedar aplicativos. Se o ambiente de hospedagem incluir o runtime do .NET, a nova versão do runtime do .NET precisará ser instalada. No Linux, dependências precisam ser instaladas, no entanto, elas normalmente não são alteradas nas versões do .NET.

Para contêineres, instruções FROM precisam ser alteradas para incluir novos números de versão.

O exemplo do Dockerfile a seguir demonstra a extração de uma imagem do ASP.NET Core 9.0.

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

Em um serviço de nuvem como o Serviço de Aplicativo do Azure, é necessário alterar a configuração.

Consulte também

  • Last updated on