Visão geral da portabilidade do .NET Framework para o .NET

2025-06-03

Este artigo fornece uma visão geral do que você deve considerar ao portar seu código do .NET Framework para o .NET (anteriormente chamado .NET Core). A portabilidade do .NET Framework para o .NET é relativamente simples para muitos projetos. A complexidade de seus projetos dita quanto trabalho você precisará fazer após a migração inicial dos arquivos de projeto.

Projetos em que o modelo de aplicativo está disponível no .NET, como bibliotecas, aplicativos de console e aplicativos de área de trabalho, geralmente exigem poucas alterações. Projetos que exigem um novo modelo de aplicativo, como a mudança do ASP.NET para o ASP.NET Core, exigem mais trabalho. Muitos padrões do modelo de aplicativo antigo têm equivalentes que podem ser usados durante a conversão.

Tecnologias de ambiente de trabalho do Windows

Muitos aplicativos criados para o .NET Framework usam uma tecnologia de área de trabalho, como Windows Forms ou Windows Presentation Foundation (WPF). O Windows Forms e o WPF estão disponíveis no .NET, mas continuam a ser tecnologias apenas para Windows.

Considere as seguintes dependências antes de migrar um aplicativo Windows Forms ou WPF:

Os arquivos de projeto para .NET usam um formato diferente do .NET Framework.
Seu projeto pode usar uma API que não está disponível no .NET.
Controles e bibliotecas de terceiros podem não ter sido portados para o .NET e permanecer disponíveis apenas para o .NET Framework.
Seu projeto usa uma tecnologia que não está mais disponível no .NET.

O .NET usa as versões de código aberto do Windows Forms e do WPF e inclui aprimoramentos sobre o .NET Framework.

Para obter tutoriais sobre como migrar seu aplicativo da área de trabalho para o .NET, consulte um dos seguintes artigos:

APIs específicas do Windows

As aplicações ainda podem usar bibliotecas nativas de P/Invoke em plataformas que o .NET suporta. Esta tecnologia não se limita ao Windows. No entanto, se a biblioteca que você está referenciando for específica do Windows, como um user32.dll ou kernel32.dll, o código só funciona no Windows. Para cada plataforma em que você deseja que seu aplicativo seja executado, você precisa encontrar versões específicas da plataforma ou tornar seu código genérico o suficiente para ser executado em todas as plataformas.

Quando você está portando um aplicativo do .NET Framework para o .NET, seu aplicativo provavelmente usou uma biblioteca fornecida pelo .NET Framework. Muitas APIs que estavam disponíveis no .NET Framework não foram portadas para o .NET porque dependiam de tecnologia específica do Windows, como o Registro do Windows ou o modelo de desenho GDI+.

O Pacote de Compatibilidade do Windows fornece uma grande parte da superfície da API do .NET Framework para o .NET e é fornecido por meio do pacote NuGet Microsoft.Windows.Compatibilidade.

Para obter mais informações, consulte Usar o Pacote de Compatibilidade do Windows para portar código para o .NET.

Modo de compatibilidade do .NET Framework

O modo de compatibilidade do .NET Framework foi introduzido no .NET Standard 2.0. O modo de compatibilidade permite que projetos .NET Standard e .NET façam referência a bibliotecas do .NET Framework como se fossem compiladas para a estrutura de destino do projeto. No entanto, algumas implementações .NET podem oferecer suporte a uma parte maior do .NET Framework do que outras. Por exemplo, o .NET Core 3.0 estende o modo de compatibilidade do .NET Framework para Windows Forms e WPF. A referência a bibliotecas do .NET Framework não funciona para todos os projetos, como se a biblioteca usa APIs do WPF, mas desbloqueia muitos cenários de portabilidade. Para obter mais informações, consulte Analisar suas dependências para portar código do .NET Framework para o .NET.

Referenciar bibliotecas do .NET Framework não funciona em todos os casos, pois depende de quais APIs do .NET Framework foram usadas e se essas APIs são ou não suportadas pela estrutura de destino do projeto. Além disso, algumas das APIs do .NET Framework só funcionarão no Windows. O modo de compatibilidade do .NET Framework desbloqueia muitos cenários de portabilidade, mas você deve testar seus projetos para garantir que eles também funcionem em tempo de execução. Para obter mais informações, consulte Analisar suas dependências para portar o código do .NET Framework para.

Alterações no framework de destino em projetos estilo SDK

Como mencionado anteriormente, os arquivos de projeto para .NET usam um formato diferente do .NET Framework, conhecido como o formato de projeto no estilo SDK. Mesmo que você não esteja mudando do .NET Framework para o .NET, você ainda deve atualizar o arquivo de projeto para o formato mais recente. A maneira de especificar uma estrutura de destino é diferente em projetos no estilo SDK. No .NET Framework, a <TargetFrameworkVersion> propriedade é usada com um moniker que especifica a versão do .NET Framework. Por exemplo, o .NET Framework 4.7.2 se parece com o seguinte trecho:

<PropertyGroup>
  <TargetFrameworkVersion>v4.7.2</TargetFrameworkVersion>
</PropertyGroup>

Um projeto no estilo SDK usa uma propriedade diferente para identificar a estrutura de destino, a <TargetFramework> propriedade. Ao direcionar o .NET Framework, o moniker começa com net e termina com a versão do .NET Framework sem pontos finais. Por exemplo, o identificador para selecionar o .NET Framework 4.7.2 é net472:

<PropertyGroup>
  <TargetFramework>net472</TargetFramework>
</PropertyGroup>

Para obter uma lista de todos os monikers de destino, consulte Estruturas de destino em projetos no estilo SDK.

Tecnologias indisponíveis

Existem algumas tecnologias no .NET Framework que não existem no .NET:

Domínios de aplicação

Não há suporte para a criação de domínios de aplicativo adicionais. Para isolamento de código, use processos ou contêineres separados como alternativa.
Acesso Remoto

A comunicação remota é usada para comunicação entre domínios de aplicativos, que não são mais suportados. Para uma comunicação simples entre processos, considere mecanismos de comunicação entre processos (IPC) como uma alternativa à comunicação remota, como a classe System.IO.Pipes ou a classe MemoryMappedFile. Para cenários mais complexos, considere estruturas como StreamJsonRpc ou ASP.NET Core (usando serviços de API Web gRPC ou RESTful).

Como a comunicação remota não é suportada, as chamadas para BeginInvoke() e EndInvoke() em objetos delegados gerarão PlatformNotSupportedException.
Segurança de acesso ao código (CAS)

O CAS era uma técnica de sandboxing suportada pelo .NET Framework, mas preterida no .NET Framework 4.0. Ele foi substituído pela Transparência de Segurança e não é suportado no .NET. Em vez disso, use limites de segurança fornecidos pelo sistema operacional, como virtualização, contêineres ou contas de usuário.
Transparência da segurança

Semelhante ao CAS, a técnica de sandboxing de transparência de segurança não é mais recomendada para aplicativos .NET Framework e não é suportada no .NET. Em vez disso, use limites de segurança fornecidos pelo sistema operacional, como virtualização, contêineres ou contas de usuário.
System.EnterpriseServices

System.EnterpriseServices (COM+) não é suportado no .NET.
Windows Workflow Foundation (WF)

WF não é suportado no .NET. Para obter uma alternativa, consulte CoreWF.

Para obter mais informações sobre essas tecnologias sem suporte, consulte Tecnologias do .NET Framework não disponíveis no .NET 6+.

Multiplataforma

O .NET (anteriormente conhecido como .NET Core) foi projetado para ser multiplataforma. Se o seu código não depender de tecnologias específicas do Windows, ele poderá ser executado em outras plataformas, como macOS, Linux e Android. Esse código inclui tipos de projeto como:

Bibliotecas
Ferramentas baseadas em console
Automação
Sítios ASP.NET

O .NET Framework é um componente somente do Windows. Quando seu código usa tecnologias ou APIs específicas do Windows, como Windows Forms e WPF, o código ainda pode ser executado no .NET, mas não é executado em outros sistemas operacionais.

É possível que sua biblioteca ou aplicativo baseado em console possa ser usado entre plataformas sem mudar muito. Ao fazer a portabilidade para o .NET, convém levar isso em consideração e testar seu aplicativo em outras plataformas.

O futuro do .NET Standard

O .NET Standard é uma especificação formal de APIs do .NET que estão disponíveis em várias implementações do .NET. A motivação por trás do .NET Standard era estabelecer uma maior uniformidade no ecossistema .NET. A partir do .NET 5, uma abordagem diferente para estabelecer a uniformidade foi adotada, e essa nova abordagem elimina a necessidade do .NET Standard em muitos cenários. Para obter mais informações, consulte .NET 5+ e .NET Standard.

O .NET Standard 2.0 foi a última versão a oferecer suporte ao .NET Framework.

Ferramentas para ajudar na portabilidade

Em vez de portar manualmente um aplicativo do .NET Framework para o .NET, você pode usar diferentes ferramentas para ajudar a automatizar alguns aspetos da migração. Portar um projeto complexo é, em si mesmo, um processo complexo. As ferramentas podem ajudar nessa jornada.

Mesmo se você usar uma ferramenta para ajudar a portar seu aplicativo, você deve revisar a seção Considerações ao portar neste artigo.

Assistente de atualização do .NET

O Assistente de Atualização do .NET é uma ferramenta de linha de comando que pode ser executada em diferentes tipos de aplicativos do .NET Framework. Ele foi projetado para ajudar na atualização de aplicativos do .NET Framework para o .NET. Depois de executar a ferramenta, na maioria dos casos, o aplicativo exigirá mais esforço para concluir a migração. A ferramenta inclui a instalação de analisadores que podem ajudar a concluir a migração. Essa ferramenta funciona nos seguintes tipos de aplicativos .NET Framework:

Formulários do Windows
WPF (Windows Presentation Foundation)
ASP.NET MVC
Consola
Bibliotecas de classes

Essa ferramenta usa as outras ferramentas listadas neste artigo, como try-convert, e orienta o processo de migração. Para obter mais informações sobre a ferramenta, consulte Visão geral do Assistente de atualização do .NET.

`try-convert`

A try-convert ferramenta é uma ferramenta global do .NET que pode converter um projeto ou uma solução inteira para o SDK do .NET, incluindo mover aplicativos da área de trabalho para o .NET. No entanto, essa ferramenta não é recomendada se seu projeto tiver um processo de compilação complicado, como tarefas personalizadas, destinos ou importações.

Para obter mais informações, consulte o try-convert repositório GitHub.

Analisador de compatibilidade de plataforma

O analisador de compatibilidade de plataforma analisa se você está ou não usando uma API que lança um PlatformNotSupportedException em tempo de execução. Embora seja improvável encontrar uma dessas APIs se você estiver mudando do .NET Framework 4.7.2 ou superior, é bom verificar. Para obter mais informações sobre APIs que lançam exceções no .NET, consulte APIs que sempre lançam exceções no .NET Core.

Para obter mais informações, consulte Analisador de compatibilidade de plataforma.

Considerações ao migrar

Ao portar seu aplicativo para .NET, considere as seguintes sugestões na ordem:

✔️ CONSIDERE usar o Assistente de Atualização do .NET para migrar seus projetos. Embora essa ferramenta esteja em visualização, ela automatiza a maioria das etapas manuais detalhadas neste artigo e oferece um ótimo ponto de partida para continuar seu caminho de migração.

✔️ CONSIDERE examinar suas dependências primeiro. Suas dependências devem ter como destino .NET, .NET Standard ou .NET Core.

✔️ FAÇA a migração de um arquivo depackages.config do NuGet para as configurações PackageReference no ficheiro de projeto. Use o Visual Studio para converter o package.config arquivo.

✔️ CONSIDERE atualizar para o formato de arquivo de projeto mais recente, mesmo que você ainda não possa portar seu aplicativo. Os projetos do .NET Framework usam um formato de projeto desatualizado. Embora o formato de projeto mais recente, conhecido como projetos no estilo SDK, tenha sido criado para o .NET Core e além, o formato também funciona com o .NET Framework. Ter seu arquivo de projeto no formato mais recente oferece uma boa base para portar seu aplicativo no futuro.

✔️ REDIRECIONE seu projeto do .NET Framework para pelo menos o .NET Framework 4.7.2. Isso garante a disponibilidade das alternativas de API mais recentes para casos em que o .NET Standard não oferece suporte a APIs existentes.

✔️ CONSIDERE focar o .NET 8, que é uma versão de suporte prolongado (LTS).

✔️ Faça o direcionamento para o .NET 6+ em projetos Windows Forms e WPF. O .NET 6 e versões posteriores contêm muitas melhorias para aplicativos da área de trabalho.

✔️ CONSIDERE direcionar o .NET Standard 2.0 se você estiver migrando uma biblioteca que também pode ser usada com projetos do .NET Framework. Você também pode destinar a sua biblioteca para múltiplos destinos, visando o .NET Framework e o .NET Standard.

✔️ ADICIONE uma referência ao pacote NuGet Microsoft.Windows.Compatibility se, após a migração, receber erros de APIs ausentes. Uma grande parte da superfície da API do .NET Framework está disponível para o .NET por meio do pacote NuGet.