Criar um plano de portabilidade

Antes de entrar diretamente no código, reserve um tempo para percorrer as etapas recomendadas de pré-migração. Este artigo fornece informações sobre os tipos de problemas que você pode encontrar e ajuda você a decidir sobre uma abordagem que faz mais sentido.

Importante

A porta da API foi preterida em favor da análise binária com a ferramenta .NET Upgrade Assistant . O serviço de back-end da Porta de API foi desligado; portanto, para usar a ferramenta, você deve estar offline. Para obter mais informações, confira o README do .NET API Port.

Migrar o código

Verifique se você segue os pré-requisitos para portar o código antes de continuar. Prepare-se para escolher a melhor abordagem para você e comece a migrar código.

Importante

O Assistente de Atualização do .NET foi oficialmente preterido. Use o agente de chat de modernização do GitHub Copilot , que está incluído no Visual Studio 2026 e no Visual Studio 2022 17.14.16 ou posterior. Esse agente analisa seus projetos e dependências, produz um plano de migração passo a passo com recomendações direcionadas e correções de código automatizadas e confirma cada alteração para que você possa validar ou reverter. Ele automatiza tarefas comuns de portabilidade, atualizando arquivos de projeto, substituindo APIs preteridas e resolvendo problemas de build, para que você possa se modernizar mais rapidamente com menos esforço manual.

Lidar principalmente com o compilador

Essa abordagem funciona bem para projetos pequenos ou projetos que não usam muitas APIs do .NET Framework. A abordagem é simples:

  1. Opcionalmente, execute o ApiPort no projeto. Se você executar o ApiPort, aprenda sobre os problemas que você precisará resolver no relatório.
  2. Copie todo o código para um novo projeto do .NET.
  3. Ao consultar o relatório de portabilidade (se um for gerado), resolva os erros do compilador até que o projeto seja totalmente compilado.

Embora não seja estruturada, essa abordagem focada em código geralmente resolve problemas rapidamente. Um projeto que contém somente os modelos de dados pode ser um candidato ideal para esta abordagem.

Permanecer no .NET Framework até que os problemas de portabilidade sejam resolvidos

Essa abordagem pode ser a melhor se você preferir que o código seja compilado durante todo o processo. A abordagem é a seguinte:

  1. Execute o ApiPort em um projeto.
  2. Trate os problemas usando diferentes APIs portáteis.
  3. Anote todas as áreas nas quais está impedido de usar uma alternativa direta.
  4. Repita as etapas anteriores para todos os projetos que estão passando por portabilidade até ter certeza de que todos estejam prontos para serem copiados em um novo projeto do .NET.
  5. Copie o código em um novo projeto do .NET.
  6. Solucione os problemas para os quais não exista uma alternativa direta, de acordo com suas anotações.

Essa abordagem cuidadosa é mais estruturada do que simplesmente tratar os erros do compilador, mas ainda é relativamente focada em código e tem a vantagem de sempre ter código que pode ser compilado. A maneira de resolver certos problemas que não puderam ser tratados usando apenas outra API varia muito. Talvez você precise desenvolver um plano mas abrangente para certos projetos, o que é tratado na próxima abordagem.

Desenvolver um plano de ação abrangente

Essa abordagem pode ser a melhor para projetos maiores e mais complexos, nos quais a reestruturação do código ou a recriação completa de determinadas áreas pode ser necessária para dar suporte ao .NET. A abordagem é a seguinte:

  1. Execute o ApiPort em um projeto.

  2. Compreenda os pontos em que cada tipo não portátil está sendo usado e como isso afeta a portabilidade geral.

    • Entenda a natureza desses tipos. Eles são poucos, mas usados com frequência? Eles são muitos, mas usados com pouca frequência? O uso deles é concentrado ou está espalhado por todo o seu código?
    • É fácil isolar o código que não é portátil para lidar com ele mais efetivamente?
    • Você precisa refatorar seu código?
    • Para esses tipos não portáteis, há APIs alternativas que realizam a mesma tarefa? Por exemplo, se você estiver usando a classe WebClient, use a classe HttpClient.
    • Existem diferentes APIs portáteis disponíveis para realizar uma tarefa, mesmo que não seja uma substituição direta? Por exemplo, se você estiver usando XmlSchema para analisar XML, mas não precisa de descoberta de esquema XML, use APIs System.Xml.Linq e implemente a análise por conta própria, em vez de depender de uma API.

  3. Se você tiver assemblies que são de difícil portabilidade, vale a pena deixá-los no .NET Framework por enquanto? Estas são algumas coisas que você deve considerar:

    • Talvez haja alguma funcionalidade na biblioteca que seja incompatível com o .NET por ser muito dependente de funcionalidades específicas do .NET Framework ou do Windows. Vale a pena deixar essa funcionalidade de lado por enquanto e lançar uma versão .NET temporária da sua biblioteca com menos recursos, até que os recursos estejam disponíveis para portar as funcionalidades?
    • Uma refatoração ajudaria?

  4. Seria razoável criar sua própria implementação de uma API do .NET Framework indisponível?

    Você pode considerar copiar, modificar e usar o código da origem de referência do .NET Framework. O código-fonte de referência é licenciado sob a Licença do MIT, portanto, você tem uma liberdade considerável para usar a fonte como base para seu próprio código. Certifique-se de dar os devidos créditos à Microsoft em seu código.

  5. Repita esse processo conforme necessário para os diferentes projetos.

A fase de análise pode demorar algum tempo dependendo do tamanho de sua base de código. Dedique tempo a essa fase para compreender totalmente o escopo das alterações necessárias, pois o desenvolvimento de um plano economiza tempo, principalmente no caso de uma base de código complexa.

O plano pode envolver alterações significativas na base de código, mantendo o direcionamento ao .NET Framework 4.7.2. Essa é uma versão mais estruturada da abordagem anterior. A maneira de executar o plano depende de sua base de código.

Abordagem combinada

É provável que você combine as abordagens acima para cada projeto. Use a opção mais adequada para você e a base de código.

Portar seus testes

A melhor maneira de garantir que tudo funcione ao portar seu código é testá-lo à medida que o adapta para o .NET. Para isso, você precisará usar uma estrutura de teste que crie e execute testes para o .NET. No momento, você tem três opções:

Por fim, o esforço de portabilidade depende muito de como seu código do .NET Framework está estruturado. Uma boa forma de portar o seu código é começar com a base da sua biblioteca, que são os componentes fundamentais do seu código. Ela pode ser os modelos de dados ou alguma outra classe e método fundamental que todos os demais elementos usam direta ou indiretamente.

  1. Migre o projeto de teste que testa a camada da sua biblioteca que você está migrando no momento.
  2. Copie a base da biblioteca para um novo projeto do .NET e selecione a versão do .NET Standard à qual deseja dar suporte.
  3. Faça as alterações necessárias para que o código seja compilado. Uma boa parte disso pode exigir a adição de dependências de pacotes NuGet para o arquivo csproj.
  4. Execute os testes e faça os ajustes necessários.
  5. Selecione a próxima camada de código para portar e repita as etapas anteriores.

Se você começar a partir da base de sua biblioteca, progredir externamente e testar cada camada conforme necessário, a portabilidade será um processo sistemático no qual os problemas ficam isolados a uma camada de código por vez.

Próximas etapas

  • Last updated on