Atualização incremental do ASP.NET para o ASP.NET Core

Atualizar um aplicativo do ASP.NET Framework para ASP.NET Core não é algo trivial para a maioria dos aplicativos de produção. Esses aplicativos geralmente incorporam novas tecnologias à medida que elas se tornam disponíveis e geralmente são compostos por muitas decisões herdadas. Este artigo fornece diretrizes e links para ferramentas para atualizar aplicativos do ASP.NET Framework para o ASP.NET Core com o mínimo de alterações possível.

Um dos maiores desafios é o uso generalizado de HttpContext em toda uma base de código. Sem a abordagem incremental e as ferramentas, uma reescrita em grande escala é necessária para remover a dependência do HttpContext. Os adaptadores em dotnet/systemweb-adapters fornecem um conjunto de auxiliares de runtime para acessar os tipos usados no aplicativo ASP.NET Framework de uma maneira que funciona no ASP.NET Core com alterações mínimas.

Uma migração completa pode exigir um esforço considerável dependendo do tamanho do aplicativo, das dependências e das APIs não portáteis usadas. Para continuar implantando um aplicativo em produção enquanto trabalha na atualização, o melhor padrão é seguir o padrão Strangler Fig. O padrão Strangler Fig (figo estrangulador) permite o desenvolvimento contínuo no sistema antigo com uma abordagem incremental para substituir partes específicas da funcionalidade por novos serviços. Este documento descreve como aplicar o padrão Strangler Fig a um aplicativo ASP.NET atualizando para ASP.NET Core.

Se você quiser ignorar este artigo de visão geral e começar a atualizar, consulte Introdução.

Migração de aplicativo para o ASP.NET Core

Antes de iniciar a migração, o aplicativo tem como destino o ASP.NET Framework e é executado no Windows com suas bibliotecas de suporte:

A migração começa introduzindo um novo aplicativo com base no ASP.NET Core que se torna o ponto de entrada. As solicitações de entrada vão para o aplicativo ASP.NET Core, que manipula a solicitação ou faz proxies da solicitação para o aplicativo .NET Framework via YARP. No início, a maioria dos códigos que fornecem respostas está no aplicativo .NET Framework, mas o aplicativo ASP.NET Core agora está configurado para iniciar a migração de rotas:

Para migrar a lógica de negócios que depende do HttpContext , as bibliotecas precisam ser criadas com Microsoft.AspNetCore.SystemWebAdapters. Criar as bibliotecas com SystemWebAdapters permite:

• As bibliotecas serem criadas no .NET Framework, no .NET Core ou no .NET Standard 2.0.
• Garante que as bibliotecas estejam usando APIs disponíveis no ASP.NET Framework e no ASP.NET Core.

Depois que o aplicativo ASP.NET Core usando YARP for configurado, você poderá começar a atualizar rotas do ASP.NET Framework para o ASP.NET Core. Por exemplo, métodos de ação do controlador WebAPI ou MVC, manipuladores ou alguma outra implementação de uma rota. Se a rota estiver disponível no aplicativo ASP.NET Core, ela será correspondida e atendida.

Durante o processo de migração, são identificados os serviços e infraestrutura adicionais que devem ser atualizados para serem executados no .NET Core. As opções listadas em ordem de manutenção incluem:

1. Mover o código para bibliotecas compartilhadas
2. Vincular o código ao novo projeto
3. Duplicar o código

Eventualmente, o aplicativo ASP.NET Core lida com mais rotas do que o aplicativo .NET Framework:

Depois que o aplicativo ASP.NET Framework não for mais necessário e for excluído:

• O aplicativo está em execução na pilha do aplicativo ASP.NET Core, mas ainda está usando os adaptadores.
• O trabalho de migração restante é a remoção do uso de adaptadores.

O Assistente de Atualização do .NET da extensão do Visual Studio pode ajudar a atualizar aplicativos Web do ASP.NET Framework para ASP.NET Core. Para obter mais informações, confira o blog Atualizando seus projetos do .NET com o Visual Studio.

Adaptadores System.Web

O namespace Microsoft.AspNetCore.SystemWebAdapters é uma coleção de auxiliares de runtime que facilitam o uso de código escrito em System.Web durante a mudança para ASP.NET Core. Há alguns pacotes que podem ser usados para usar recursos desses adaptadores:

• Microsoft.AspNetCore.SystemWebAdapters: esse pacote é usado em bibliotecas de suporte e fornece as APIs System.Web nas quais você pode ter usado uma dependência, como HttpContext e outras. Esse pacote tem como destino o .NET Standard 2.0, o .NET 4.5+e o .NET 6+.
• Microsoft.AspNetCore.SystemWebAdapters.FrameworkServices: esse pacote destina-se apenas ao .NET Framework e visa fornecer serviços para aplicativos do ASP.NET Framework que podem precisar fornecer migrações incrementais. Isso geralmente não é esperado que seja referenciado de bibliotecas, mas sim dos próprios aplicativos.
• Microsoft.AspNetCore.SystemWebAdapters.CoreServices: esse pacote destina-se apenas ao .NET 6+ e visa fornecer serviços para ASP.NET Core aplicativos para configurar o comportamento das APIs do System.Web, bem como optar por quaisquer comportamentos para migração incremental. Isso geralmente não é esperado que seja referenciado de bibliotecas, mas sim dos próprios aplicativos.
• Microsoft.AspNetCore.SystemWebAdapters.Abstractions: esse pacote é um pacote de suporte que fornece abstrações para serviços usados pelos aplicativos ASP.NET Core e ASP.NET Framework, como serialização de estado de sessão.

Para obter exemplos de cenários em que isso é útil, consulte o artigo sobre adaptadores.

Para obter diretrizes sobre o uso, consulte o artigo de diretrizes de uso.

Recursos adicionais

• Exemplo de migração do eShop para ASP.NET Core
• Vídeo: ferramentas para migrações incrementais do ASP.NET Core
• Testes de Unidade