Compartilhar via

Introdução à migração incremental do ASP.NET para o ASP.NET Core

Important

Antes de começar: este artigo pressupõe que você leu a visão geral da migração do ASP.NET Core. Se você ainda não leu, comece a entender os conceitos, a abordagem e os benefícios da migração incremental.

Para uma migração grande, recomendamos configurar um aplicativo ASP.NET Core que faz proxies para o aplicativo .NET Framework original. O novo aplicativo habilitado para proxy é mostrado na seguinte imagem:

Iniciar a migração de rotas

Este artigo fornece as etapas práticas para prosseguir com uma migração incremental depois que você entender a abordagem.

Prerequisites

Antes de iniciar a migração incremental, verifique se você tem:

  1. Leia a visão geral: Migração incremental de ASP.NET para ASP.NET Core
  2. Um aplicativo ASP.NET Framework em funcionamento que você deseja migrar
  3. Visual Studio 2022 com as atualizações mais recentes
  4. SDK do .NET 8 ou posterior instalado
  5. Noções básicas sobre as dependências do aplicativo e bibliotecas de terceiros

Visão geral das etapas de migração

O processo de migração incremental segue estas etapas principais:

  1. Configurar o projeto do ASP.NET Core
  2. Corrigir dívida técnica
  3. Identificar e resolver preocupações transversais
  4. Atualizar bibliotecas de suporte

Configurar o projeto do ASP.NET Core

A primeira etapa é criar o novo aplicativo ASP.NET Core que servirá como seu proxy.

O que você fará:

  • Criar um novo projeto ASP.NET Core junto com seu aplicativo ASP.NET Framework existente
  • Configure-a para solicitações de proxy para seu aplicativo original usando YARP (Yet Another Reverse Proxy)
  • Configurar a infraestrutura básica para migração incremental

Instruções detalhadas:

Corrigir dívida técnica

Quando fazer esta etapa: Antes de atualizar as bibliotecas de suporte, resolva a dívida técnica que poderia complicar o processo de migração.

Antes de começar a atualizar suas bibliotecas de suporte, é importante limpar a dívida técnica que pode interferir no processo de migração. Esta etapa deve ser concluída primeiro para garantir uma experiência de atualização mais suave.

Atualizar dependências de pacote

Examine e atualize seus pacotes NuGet para suas versões compatíveis mais recentes:

  1. Auditar pacotes existentes: use o Gerenciador de Pacotes NuGet do Visual Studio, pois a dotnet CLI não funciona para aplicativos ASP.NET Framework
  2. Atualizar pacotes de forma incremental: atualizar pacotes um de cada vez para evitar problemas de compatibilidade
  3. Teste após cada atualização: verifique se seu aplicativo ainda funciona corretamente após cada atualização de pacote
  4. Resolver alterações interruptivas: algumas atualizações de pacote podem introduzir alterações interruptivas que precisam ser resolvidas

Modernizar ferramentas de build

Atualize as ferramentas de build e a configuração do projeto:

  1. Ferramentas de atualização: verifique se você está usando uma versão recente do MSBuild/Visual Studio
  2. Migrar para PackageReference para dependências: considere migrar do formato packages.config para PackageReference, caso ainda não o tenha feito isso no projeto do aplicativo Web
  3. Limpar referências não utilizadas: Remover quaisquer referências de assembly não utilizadas ou pacotes NuGet não utilizados
  4. Migrar para arquivos de projeto no estilo SDK: converta os arquivos de projeto existentes no formato de estilo SDK moderno. Isso é essencial para compatibilidade com projetos modernos do .NET e oferece melhor suporte a ferramentas
  5. Atualizar scripts de build: revisar e atualizar scripts de build personalizados ou configurações de CI/CD

Resolver problemas de qualidade do código

Corrija problemas conhecidos de qualidade de código que podem complicar a migração:

  1. Corrigir avisos do compilador: endereçar quaisquer avisos do compilador, especialmente aqueles relacionados a APIs preteridas
  2. Remover código morto: limpar classes, métodos e outros elementos de código não utilizados
  3. Atualizar o uso preterido da API: substitua o uso de APIs preteridas por seus equivalentes modernos sempre que possível

Esse trabalho de preparação tornará o processo de atualização da biblioteca muito mais suave e reduzirá a probabilidade de encontrar problemas complexos durante a migração.

Identificar e resolver preocupações transversais

Quando fazer esta etapa: Ao corrigir o déficit técnico, mas antes de atualizar as bibliotecas de suporte, identifique e configure preocupações transversais que afetam o aplicativo inteiro.

Questões transversais são aspectos do seu aplicativo que abrangem várias camadas ou componentes, como autenticação, gestão de sessão, log e cache. Elas precisam ser tratadas no início do processo de migração porque afetam a forma como seus aplicativos ASP.NET Framework e ASP.NET Core se comunicam e compartilham o estado durante a migração incremental.

As seções a seguir abordam as preocupações de corte cruzado mais comuns. Configure somente os que se aplicam ao seu aplicativo:

Configuração de suporte de sessão

Configure isso se: Seu aplicativo ASP.NET Framework usa o estado de sessão.

Consulte a documentação geral de migração de sessão para obter diretrizes aqui.

A sessão é um recurso comumente usado de ASP.NET que compartilha o nome com um recurso no ASP.NET Core, mas as APIs são muito diferentes. Ao atualizar bibliotecas que usam o estado de sessão, você precisará configurar o suporte à sessão. Consulte a documentação sobre o suporte à sessão remota para obter diretrizes detalhadas sobre como habilitar o compartilhamento de estado de sessão entre seus aplicativos.

Configuração de autenticação

Configure isso se: Seu aplicativo ASP.NET Framework usa autenticação e você deseja compartilhar o estado de autenticação entre os aplicativos antigos e novos.

Consulte a documentação geral de migração de autenticação para obter diretrizes aqui.

É possível compartilhar a autenticação entre o aplicativo ASP.NET original e o novo aplicativo ASP.NET Core usando o recurso de autenticação remota dos adaptadores System.Web. Esse recurso permite que o aplicativo ASP.NET Core adie a autenticação para o aplicativo de ASP.NET original. Consulte a documentação sobre autenticação remota para obter mais detalhes.

Outras preocupações transversais a serem consideradas

Dependendo do aplicativo, talvez você também precise resolver:

  • Registro em log: Garanta que o registro em log seja consistente em ambos os aplicativos. Considere usar um provedor de log compartilhado ou garantir que os logs sejam agregados corretamente.
  • Cache: se o aplicativo usar o cache (cache na memória, distribuído ou de saída), planeje como manter a consistência do cache entre aplicativos.
  • Tratamento de erros: estabeleça o tratamento de erros e relatórios consistentes em ambos os aplicativos ASP.NET Framework e ASP.NET Core.
  • Gerenciamento de Configuração: planeje como as configurações serão compartilhadas ou gerenciadas entre os dois aplicativos.
  • Monitoramento de Integridade: configure verificações de integridade e monitoramento para ambos os aplicativos durante o processo de migração.
  • Injeção de dependência: Se estiver usando um contêiner de DI em seu aplicativo ASP.NET Framework, planeje a migração para o contêiner de DI interno do ASP.NET Core.

Atualizar bibliotecas de suporte

Quando fazer esta etapa: Somente quando você precisar migrar rotas específicas que dependem de bibliotecas de classes que contenham lógica de negócios, você precisará compartilhar entre os aplicativos antigos e novos.

Note

Abordagem incremental: com o processo de migração incremental, você não precisa atualizar todas as bibliotecas de suporte ao mesmo tempo. Você só precisa atualizar as bibliotecas necessárias para as rotas específicas que você está migrando no momento. Isso permite que você enfrente a migração em partes menores e mais gerenciáveis.

Processo de atualização da biblioteca

Important

As bibliotecas de suporte devem ser atualizadas em uma ordem de pesquisa em profundidade pós-fixada. Isso significa:

  1. Comece com dependências de folha: comece com bibliotecas que não tenham dependências de outras bibliotecas em sua solução
  2. Trabalhe para cima por meio da árvore de dependência: atualize apenas uma biblioteca depois que todas as suas dependências tiverem sido atualizadas com êxito
  3. Terminar com o aplicativo principal: o aplicativo principal do ASP.NET Framework deve ser o último item a ser modificado

Essa ordenação é essencial porque:

  • Ele garante que, ao atualizar uma biblioteca, todas as suas dependências já sejam compatíveis
  • Ele impede problemas de dependência circular durante o processo de atualização
  • Ele permite que você teste cada biblioteca de forma independente antes de migrar para seus dependentes

OBSERVAÇÃO: você só precisa seguir essa ordenação para o subconjunto de bibliotecas exigido pelas rotas que você está migrando no momento, não toda a sua solução.

Processo de atualização para cada biblioteca:

Se você tiver bibliotecas de suporte em sua solução que precisará usar para as rotas que está migrando, elas deverão ser atualizadas para o .NET Standard 2.0, se possível. A modernização do aplicativo GitHub Copilot pode ajudá-lo com isso. Se as bibliotecas não puderem ter como destino o .NET Standard, você poderá ter como destino o .NET 8 ou posterior, juntamente com o destino do .NET Framework no projeto original ou em um novo projeto junto com o original.

Os adaptadores System.Web podem ser usados nessas bibliotecas para permitir o suporte ao uso de HttpContext em bibliotecas de classes. Para habilitar HttpContext o uso em uma biblioteca:

  1. Remover referência a System.Web no arquivo de projeto
  2. Adicionar o Microsoft.AspNetCore.SystemWebAdapters pacote
  3. Habilite o direcionamento múltiplo e adicione um destino .NET 8 ou posterior ou converta o projeto no .NET Standard 2.0.

Essa etapa pode exigir que vários projetos sejam alterados dependendo da estrutura da solução e das rotas que você está migrando. A modernização do aplicativo GitHub Copilot pode ajudá-lo a identificar quais deles precisam alterar e automatizar várias etapas no processo.

Próximas etapas

Depois de concluir as etapas de instalação e atualização da biblioteca acima:

  1. Comece pequeno: Comece por migrar primeiro os pontos finais simples e sem estado
  2. Teste minuciosamente: verifique se cada componente migrado funciona corretamente em ambos os ambientes
  3. Monitorar o desempenho: observe os impactos de desempenho da configuração do proxy
  4. Iterar: continuar migrando componentes incrementalmente até que a migração seja concluída
  • Last updated on