Visão geral da atualização de aplicativos Windows Forms

Este artigo ajuda você a entender o que está envolvido na atualização de um aplicativo Windows Forms do .NET Framework para o .NET. Windows Forms tem suporte em .NET e recebe investimentos ativos, incluindo controles mais recentes, aprimoramentos de alto DPI e atualizações de acessibilidade. Se você mantiver um aplicativo Windows Forms existente e quiser aproveitar essas melhorias ou mudar para uma versão de .NET com suporte, este artigo será para você.

O artigo aborda os motivos para atualizar, os caminhos de atualização disponíveis e o trabalho de preparação que torna a atualização tranquila. Ele também explica quais tecnologias do .NET Framework não têm equivalente em .NET, como preencher lacunas de API usando o Pacote de Compatibilidade Windows e como alterações interruptivas podem afetar seu aplicativo.

Para ver um exemplo de como atualizar, consulte Atualizar um aplicativo Windows Forms para o .NET com a modernização do GitHub Copilot.

Por que atualizar

.NET Framework é um runtime de código fechado exclusivo do Windows que não recebe mais atualizações de novos recursos. Embora continue recebendo patches de segurança para versões com suporte, ele não se beneficia do trabalho de desempenho, melhorias de linguagem ou investimento ativo que .NET faz. Se você estiver mantendo um aplicativo Windows no .NET Framework, a atualização para .NET fornecerá acesso a uma plataforma mais rápida e mais capaz que é desenvolvida ativamente ao ar livre.

Manter-se atualizado em .NET versões também é importante. Cada versão .NET tem uma janela de suporte definida e os aplicativos em execução em uma versão sem suporte param de receber correções e patches de segurança. Atualize antes do fim do suporte para permanecer protegido.

.NET oferece melhorias significativas de desempenho na inicialização do runtime, na taxa de transferência e no uso de memória. Os aplicativos para desktop no .NET também se beneficiam do investimento contínuo em funcionalidades:

  • Controles mais recentes, melhorias de acessibilidade e aprimoramentos de alta DPI.
  • Melhor integração com Windows. Alguns recursos, como o Modo Escuro no Windows 11, estão disponíveis apenas em .NET.
  • Recursos de linguagem C# e Visual Basic mais recentes e ferramentas aprimoradas.
  • Um ecossistema avançado de pacotes NuGet destinados a .NET.

.NET lança uma nova versão principal todos os anos, alternando entre versões com suporte de longo prazo (LTS) e suporte de prazo padrão (STS):

  • As versões lts têm suporte por três anos e normalmente são a melhor opção para aplicativos de produção que preferem estabilidade.
  • As versões sts têm suporte por 24 meses e são úteis quando você deseja adotar novos recursos mais cedo.

Planeje sua cadência de atualização em torno dessas datas para que seu aplicativo esteja sempre em uma versão com suporte. Para versões atuais com suporte e datas de fim de suporte, consulte .NET versões, patches e suporte.

Caminhos de atualização

A maioria das atualizações se enquadra em uma das duas categorias. Identifique qual caminho se aplica ao seu aplicativo e use as diretrizes e ferramentas neste artigo para concluir o trabalho.

  • De .NET Framework para .NET: a alteração mais significativa.

    O formato do arquivo de projeto, algumas APIs e determinadas tecnologias são diferentes. Examine os pré-requisitos, avalie suas dependências e planeje as lacunas de API antes de começar.

    Depois que o aplicativo for criado e executado no .NET, opcionalmente, você poderá adotar padrões mais recentes, como appsettings.json configuração, injeção de dependência ou serviços de nuvem. A adoção desses padrões é separada da modernização para .NET e não é necessária para concluir a atualização. Para obter ideias e diretrizes, consulte Modernizar depois de atualizar para .NET do .NET Framework.

  • De uma versão de .NET mais antiga para uma mais recente: uma atualização de escopo menor.

    As principais tarefas são atualizar o moniker da plataforma de destino, revisar as alterações significativas das versões pelas quais você está passando e atualizar as dependências do NuGet.

Atualizar do .NET Framework para o .NET

A atualização do .NET Framework para .NET é o caminho de atualização mais significativo e o foco principal desta seção.

Importante

Embora o .NET seja uma tecnologia multiplataforma, os aplicativos de desktop do Windows para .NET continuam sendo exclusivos do Windows.

Uma alteração é o formato do arquivo de projeto. .NET usa o formato de projeto no estilo SDK, que é mais conciso do que o formato herdado. Você pode converter o arquivo do seu projeto para o formato SDK-style enquanto ele ainda continua direcionado ao .NET Framework, o que reduz o escopo da mudança durante a migração propriamente dita e oferece uma base melhor para trabalhar.

Nem todas as APIs do .NET Framework estão disponíveis no .NET. Algumas APIs existem aparentemente, mas geram PlatformNotSupportedException em tempo de execução. O pacote de compatibilidade Windows (Microsoft.Windows.Compatibility pacote NuGet) preenche muitas dessas lacunas fornecendo acesso a APIs específicas de Windows, como o Registro de Windows, o Log de Eventos Windows e muito mais. Para obter detalhes, consulte Usar o pacote de compatibilidade Windows para portar o código para .NET.

Algumas tecnologias do .NET Framework não têm equivalente em .NET e exigem abordagens alternativas, como Domínios de Aplicativo, CAS (Segurança de Acesso ao Código) e Windows Workflow Foundation. Para obter mais informações, consulte a seção Tecnologias do .NET Framework indisponíveis.

Audite suas dependências de terceiros. Controles e bibliotecas destinados apenas ao .NET Framework podem não funcionar no .NET. Prefira pacotes NuGet destinados ao .NET Standard 2.0 ou diretamente ao .NET. Para pacotes que não foram portados, procure alternativas de comunidade ou verifique se o pacote de compatibilidade do Windows abrange as APIs necessárias.

Atualizar entre versões do .NET

Passar de uma versão .NET para outra, por exemplo, de .NET 9 para .NET 10, normalmente é um esforço menor do que modernizar do .NET Framework. A tarefa principal é atualizar a propriedade <TargetFramework> no arquivo do projeto para o novo identificador da estrutura de destino. Por exemplo, alterando net9.0-windows para net10.0-windows.

Antes de atualizar o destino, examine a documentação de alterações interruptivas para cada versão que você estiver cruzando. Alterações significativas podem ser comportamentais, afetar a compatibilidade binária ou de origem ou alterar o comportamento de tempo de design. Mesmo pequenas lacunas de versão podem introduzir alterações que afetam seu aplicativo. Examine as alterações interruptivas no .NET e filtre para o intervalo de versões em que você está atualizando.

Depois de atualizar a estrutura de destino, atualize suas dependências do NuGet. Pacotes destinados a versões de .NET mais antigas podem ter versões mais recentes que aproveitam o runtime atual. Verifique se há atualizações e prefira pacotes destinados à versão para a qual você está migrando. Alguns pacotes também podem ter preterido APIs ou comportamento alterado em versões mais recentes, portanto, examine as notas de versão ao atualizar.

Modernização do aplicativo GitHub Copilot

O agente de modernização do GitHub Copilot é a ferramenta recomendada para atualizar aplicativos Windows Forms e WPF. É uma experiência de ponta a ponta com tecnologia de IA, integrada ao GitHub Copilot, que cuida de todo o processo de atualização.

O agente segue um fluxo de trabalho de três estágios:

  • Avaliação. Copilot examina a estrutura do projeto, as dependências e os padrões de código. Ele identifica mudanças incompatíveis, problemas de compatibilidade de API, padrões obsoletos e o escopo geral da atualização. Em seguida, ele apresenta decisões de estratégia, como ordem de atualização e tratamento de compatibilidade, para que você examine antes de prosseguir.

  • Planejamento. Copilot converte a avaliação e suas opções confirmadas em um plano de atualização detalhado, documentando estratégias de atualização, abordagens de refatoração, caminhos de dependência e mitigações de risco.

  • Execução. Copilot divide o plano em tarefas sequenciais com critérios de validação, aplica correções de código e confirma alterações incrementalmente. Se ele encontrar um problema que não pode ser resolvido automaticamente, ele solicitará sua ajuda e aprenderá com a correção.

Todo o estado de atualização é armazenado em .github/upgrades/ seu repositório, para que você possa pausar e retomar entre sessões ou alternar entre ambientes de desenvolvimento sem perder o progresso.

O agente dá suporte a esses caminhos de atualização:

  • .NET Framework (qualquer versão) para .NET 8 ou posterior
  • .NET Core 1.x–3.x para .NET 8 ou posterior
  • .NET 5-7 para .NET 8 ou posterior
  • Migração para serviços de Azure

Ele está disponível em Visual Studio 2026, Visual Studio 2022 17.14.16+, Visual Studio Code e GitHub CLI. Para iniciar uma atualização de versão no Visual Studio, clique com o botão direito do mouse na sua solução ou projeto no Gerenciador de Soluções e selecione Modernizar, ou abra a janela do GitHub Copilot Chat e digite @Modernize. Em Visual Studio Code, abra o painel de Copilot Chat do GitHub e digite @modernize-dotnet.

Para obter detalhes sobre configuração e uso, consulte O que é modernização com o GitHub Copilot?.

Tecnologias do .NET Framework indisponíveis

Várias tecnologias do .NET Framework não têm equivalente em .NET e exigem abordagens alternativas antes que seu aplicativo possa ser executado no novo runtime. Identifique se seu aplicativo depende de qualquer uma dessas tecnologias antecipadamente, pois elas representam a categoria mais disruptiva do trabalho de migração. Para obter a referência completa, consulte as tecnologias do .NET Framework indisponíveis no .NET.

  • Domínios de aplicativo

    Não há suporte para AppDomain. Use AssemblyLoadContext para carregamento dinâmico de assembly e use processos ou contêineres separados para isolamento. Alguns AppDomain membros da API estão presentes, mas geram PlatformNotSupportedException em tempo de execução.

  • Controle remoto

    Não há suporte para o .NET Remoting. Use System.IO.Pipes ou MemoryMappedFile para IPC local ou gRPC e ASP.NET Core para comunicação entre máquinas. Chamadas a BeginInvoke() e EndInvoke() em objetos delegados também geram PlatformNotSupportedException.

  • CAS (Segurança de Acesso ao Código)

    O CAS não tem suporte e não é mais um limite de segurança. Use limites de segurança no nível do sistema operacional, como virtualização, contêineres ou contas de usuário.

  • Transparência de segurança

    A transparência de segurança, que separava o código em área restrita do código crítico de segurança, não tem mais suporte como um limite de segurança. Assim como o CAS, esse recurso se baseava na imposição de runtime que .NET não fornece. Em vez disso, use mecanismos de isolamento no nível do sistema operacional.

  • Windows Workflow Foundation (WF)

    O WF não tem suporte no .NET. Se o aplicativo hospeda ou usa fluxos de trabalho, considere o CoreWF, uma porta de software livre do runtime do Windows Workflow Foundation que tem como destino .NET.

  • System.EnterpriseServices (COM+)

    Não há suporte para System.EnterpriseServices. Aplicativos que usam serviços COM+, como pooling de objetos, transações ou segurança baseada em funções, por meio de System.EnterpriseServices, precisam ser redesenhados para usar alternativas. Para transações distribuídas, considere System.Transactions. Para cenários de hospedagem de serviço, considere ASP.NET Core ou serviços de trabalho.

Esteja ciente de que algumas APIs nessas áreas estão presentes no .NET, mas lançam PlatformNotSupportedException em tempo de execução, em vez de falharem em tempo de compilação. Teste seu aplicativo em .NET logo no início da migração para identificar esses problemas antes de investir em uma migração completa.

Antes de começar a fazer upgrade do .NET Framework

Antes de começar a portar seu aplicativo para .NET, conclua um conjunto de etapas preparatórias enquanto o projeto ainda tem como destino .NET Framework. Fazer esse trabalho preparatório primeiro reduz o escopo das mudanças durante o upgrade propriamente dito e dá a você uma base de referência mais limpa e validada para começar. Para obter uma referência completa, consulte Pré-requisitos para portar código do .NET Framework.

  • Atualize suas ferramentas.

    Verifique se você está executando uma versão do Visual Studio que dá suporte à versão do .NET que você pretende direcionar. As versões mais recentes do SDK incluem suporte aprimorado à migração, melhores analisadores e modelos de projeto atualizados. Para obter a relação entre as versões .NET SDK, MSBuild e Visual Studio, consulte a relação de controle de versão entre o SDK .NET, o MSBuild e o Visual Studio.

  • Use o .NET Framework 4.7.2 ou posterior.

    Redirecione seu projeto para .NET Framework 4.7.2 ou superior antes da portabilidade. Esta versão fornece a superfície de compatibilidade de API mais ampla com .NET Standard 2.0, o que reduz o número de lacunas de API que você encontrará durante a atualização.

    Em Visual Studio, clique com o botão direito do mouse no projeto, selecione Propriedades e altere a lista suspensa da Estrutura de destino para .NET Framework 4.7.2. Recompile e corrija quaisquer problemas antes de prosseguir.

  • Converter em formato PackageReference.

    Se o projeto usar um packages.config arquivo para gerenciar referências do NuGet, migre para o PackageReference formato. PackageReference é a abordagem moderna e se integra diretamente ao formato de projeto no estilo SDK que você adotará na próxima etapa.

    Em Visual Studio, clique com o botão packages.config direito do mouse em Gerenciador de Soluções e selecione Migrar packages.config para PackageReference. Revise a saída da migração e resolva quaisquer avisos antes de continuar.

  • Converter em formato de projeto no estilo SDK.

    Alterne o arquivo de projeto para o formato estilo SDK. Projetos no estilo SDK são mais concisos, dão suporte a vários direcionamentos e são necessários para .NET. Essa conversão pode ser feita mesmo tendo como destino o .NET Framework, por isso é uma etapa preparatória segura. Muitas ferramentas de conversão lidam com isso automaticamente ou você pode converter manualmente substituindo o conteúdo do arquivo de projeto pelo equivalente no estilo SDK e readicionando as propriedades necessárias.

  • Atualize as dependências do NuGet.

    Atualize todos os pacotes NuGet para suas versões mais recentes e prefira pacotes destinados .NET Standard 2.0, em vez de pacotes destinados apenas ao .NET Framework. Isso reduz o risco de bloqueadores de dependência quando você altera a estrutura de destino. Revise as notas de versão do pacote para identificar quaisquer alterações incompatíveis introduzidas em versões mais recentes.

Todas as sugestões anteriores garantem que seus projetos estejam em um bom estado antes de atualizar para .NET.

Pacote de Compatibilidade do Windows

Um dos problemas mais comuns ao migrar do .NET Framework é a ausência de APIs. .NET Standard exclui deliberadamente tecnologias que não podem funcionar em todas as plataformas, como o Registro Windows, o WMI e a emissão de reflexão, para que essas APIs não estejam disponíveis por padrão. O Microsoft.Windows.Compatibility pacote NuGet preenche essa lacuna. Ele fornece cerca de 20.000 APIs nas seguintes áreas de tecnologia:

  • Registro do Windows
  • Log de eventos do Windows
  • WMI (Instrumentação de Gerenciamento do Windows)
  • Contadores de desempenho do Windows
  • Serviços de Diretório
  • ACL (Listas de Controle de Acesso do Windows)
  • Serviços Windows
  • Criptografia do Windows
  • Windows Communication Foundation (WCF)
  • Portas, ODBC, CodeDom e muito mais

O pacote é baseado no .NET Standard 2.0 e é especialmente útil ao modernizar de forma incremental. Ele permite que você faça seu aplicativo compilar e rodar no .NET primeiro e deixe uma refatoração mais profunda para depois, sem precisar reescrever logo de cara o uso de APIs específicas do Windows.

Para adicioná-lo ao seu projeto, instale o Microsoft.Windows.Compatibility pacote NuGet:

dotnet add package Microsoft.Windows.Compatibility

Para obter detalhes completos, consulte Usar o pacote de compatibilidade Windows para portar o código para .NET.

Alterações críticas

Alterações significativas são uma parte esperada de qualquer atualização, seja migrando do .NET Framework ou entre versões do .NET. Revisá-los antes de começar evita surpresas no final da migração. Para obter a referência completa, consulte Alterações significativas ao portar código.

Alterações interruptivas se enquadram em várias categorias e nem todas causam erros de tempo de compilação:

  • As alterações comportamentais afetam como uma API funciona em runtime. A assinatura permanece a mesma, mas a saída, as exceções lançadas ou o comportamento interno mudam. Esses são os mais difíceis de identificar porque não produzem erros de compilação.
  • As alterações na compatibilidade binária afetam a possibilidade de os assemblies compilados existentes continuarem funcionando sem recompilação. Remover ou alterar uma superfície de API pública interrompe a compatibilidade binária.
  • Alterações na compatibilidade de código-fonte exigem que você modifique o código-fonte antes de ele ser compilado com êxito com a versão mais recente.
  • As alterações de compatibilidade no tempo de design afetam como os projetos são abertos e se comportam no Visual Studio ou em outros ambientes de design.

Ao migrar do .NET Framework, você está lidando com uma grande diferença entre versões, portanto a lista de possíveis mudanças é mais longa. Ao atualizar entre .NET versões, por exemplo, de .NET 6 para .NET 9, o escopo é mais estreito, mas todas as versões entre eles podem introduzir alterações que afetam seu aplicativo. Revise as alterações significativas de cada versão que você ignorar, não apenas da versão de destino.

Alterações significativas específicas de Windows Forms estão documentadas em Alterações significativas para migração do .NET Framework para .NET. Filtre a referência de mudanças significativas pela faixa de versões entre as quais você está atualizando e revise as entradas que se aplicam às APIs usadas pelo seu aplicativo.

Tarefas pós-atualização

Depois que o aplicativo for criado e executado no .NET, conclua algumas tarefas de limpeza para remover artefatos que sobraram da atualização.

Examine os pacotes NuGet.

O processo de atualização pode ter atualizado pacotes para versões mais recentes. Algumas dessas versões mais recentes removem as dependências necessárias para versões mais antigas. Após a atualização, verifique cada pacote atualizado e remova as dependências transitivas que não são mais necessárias. Examine as notas de versão dos pacotes atualizados para capturar alterações comportamentais que não causam erros de build.

Limpe artefatos NuGet antigos.

Se o projeto usou um packages.config arquivo para gerenciar referências do NuGet, ele não será mais necessário após a migração para o PackageReference formato. Exclua-o do seu projeto. Você também pode excluir a pasta local packages em seu diretório de projeto ou solução — o NuGet agora armazena pacotes em uma pasta de cache global em .nuget\packages seu perfil de usuário.

Atualizar System.Configuration referências.

A maioria dos aplicativos do .NET Framework faz referência System.Configuration diretamente. Após a atualização, seu projeto ainda pode levar essa referência. A System.Configuration biblioteca lê o arquivo app.config para obter a configuração em tempo de execução. Em .NET, substitua-o pelo pacote NuGet System.Configuration.ConfigurationManager, que fornece a mesma API sem a referência direta ao assembly do framework.

Modernizar após a atualização

Depois que o aplicativo for executado no .NET, você poderá adotar padrões modernos que não estão disponíveis no .NET Framework. Essas alterações não são necessárias para concluir a atualização, mas melhoram a manutenção e aproveitam o investimento ativo em .NET. Para obter um conjunto mais amplo de ideias, consulte Modernização após atualizar do .NET Framework para o .NET.

Migrar de App.config para appsettings.json.

.NET Framework usa App.config para configurações de tempo de execução, como cadeias de conexão e configuração de log. Aplicativos .NET normalmente usam appsettings.json, fornecido pelo pacote NuGet Microsoft.Extensions.Configuration. Muitas bibliotecas — incluindo provedores de log — deixaram de oferecer suporte a App.config em favor de appsettings.json. A migração alinha seu aplicativo com o ecossistema e simplifica a configuração à medida que você adiciona novas dependências.

App.config arquivos continuam funcionando em .NET por meio do System.Configuration.ConfigurationManager pacote NuGet, para que você possa migrar incrementalmente. Para obter diretrizes, consulte Configuração em .NET.

Substitua o controle WebBrowser por WebView2 (WPF).

O WebBrowser controle é baseado em Internet Explorer, que não tem mais suporte. WPF para .NET pode usar, em vez disso, o controle WebView2 baseado no Microsoft Edge. WebView2 fornece um controle de navegador moderno e mantido ativamente com melhor desempenho, segurança e suporte a padrões da Web.

Adicione o pacote NuGet Microsoft.Web.WebView2 ao seu projeto. Dependendo da versão do Windows que o usuário estiver executando, talvez seja necessário instalar o runtime do WebView2 separadamente. Para obter mais informações, consulte Introdução ao Microsoft Edge WebView2.

Conteúdo relacionado

  • Last updated on