Partilhar 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 seja mais suportada. O processo de atualização tem vários aspetos a considerar.

Razões comuns para atualizar para uma nova versão do .NET:

  • A versão .NET usada atualmente não é mais suportada
  • A nova versão suporta um novo sistema operacional
  • A nova versão tem uma API, desempenho ou recurso de segurança importante

Atualizar o 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 CLI .NET atualizada, sistema de compilação e versão de tempo de execução.

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

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 TargetFramework propriedade em um arquivo de projeto para a versão mais recente do .NET.

Saiba como o fazer a seguir:

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

Sugestão

A modernização do aplicativo GitHub Copilot - o recurso 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, Visual Studio ou outros componentes, você pode encontrar novos comportamentos, avisos do analisador ou alterações significativas que afetam seu processo de compilação. Ao fixar em uma versão, você pode atualizar seu ambiente de desenvolvimento enquanto mantém o controle sobre quando componentes específicos são atualizados em seus projetos.

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

  • Compilações previsíveis: Garante resultados de compilação consistentes em diferentes máquinas e ambientes de CI/CD.
  • Adoção gradual: Permite que você adote novos recursos de forma incremental, em vez de todos de uma só vez.
  • Evite alterações inesperadas: impede que novas regras do analisador, comportamentos do SDK ou versões de pacotes causem falhas de compilação.
  • 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: facilita o isolamento de problemas quando você controla quais versões foram alteradas.

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

Controle a versão do SDK com o global.json

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

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

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

Este comando cria o seguinte arquivo global.json que fixa o SDK na versão 9.0.100 ou em qualquer patch ou faixa de recursos posterior dentro da versão principal 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, quando você atualiza o Visual Studio ou instala um novo SDK, seu projeto continua 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 compilações 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 quando você atualiza o SDK.

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

Quando definido como 9.0, somente as regras do analisador fornecidas com o .NET 9 são habilitadas, mesmo se você estiver usando o SDK do .NET 10. Isso evita que novas regras do analisador .NET 10 afetem sua compilação até que você esteja pronto para resolvê-las.

Para obter mais informações, consulte AnalysisLevel.

Controlar versões de pacotes NuGet

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

Arquivos de bloqueio de pacote

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

Habilite os arquivos de bloqueio em seu arquivo de projeto:

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

Para garantir que as compilações falhem se o arquivo de bloqueio estiver desatualizado:

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

Depois de ativar os arquivos de bloqueio, execute dotnet restore para gerar o arquivo packages.lock.json . Confirme este arquivo no controle do código-fonte.

Gerenciamento central de pacotes

O gerenciamento central de pacotes (CPM) permite gerenciar versões de pacotes em um único local para todos os projetos em uma solução. Essa abordagem simplifica o gerenciamento de versões e garante a consistência entre os 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, pacotes de referência 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 de pacotes permite controlar quais feeds NuGet são usados para pacotes específicos, melhorando a segurança e a confiabilidade.

Configure o mapeamento de origem em seu 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 a partir do feed contoso, enquanto outros pacotes vêm do nuget.org.

Para obter mais informações, consulte Restauração de pacotes NuGet.

Controlar a versão do MSBuild

O Visual Studio oferece 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 na mesma máquina. Cada versão do Visual Studio inclui um SDK .NET correspondente. Quando você atualiza o Visual Studio, a versão incluída do SDK 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, está a usar a versão do MSBuild incluída no SDK especificado por global.json ou no SDK instalado mais recente.

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

  • Use dotnet build com uma versão definida do SDK no global.json.
  • Inicie o prompt de comando apropriado do Visual Studio Developer, que configura o ambiente para o MSBuild dessa 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 SDK do .NET, MSBuild e controle de versão do Visual Studio.

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

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

Atualizar ambiente de hospedagem

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

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

O exemplo 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, uma alteração de configuração é necessária.

Consulte também

  • Last updated on