Atualize um aplicativo do Windows Forms para o .NET com a modernização do GitHub Copilot

Este artigo explica como atualizar um aplicativo da área de trabalho Windows Forms para .NET usando o agente de modernização do GitHub Copilot. O agente é executado no seu editor, analisa o projeto e orienta um fluxo de trabalho de três etapas: avaliação, planejamento e execução.

O exemplo usa o exemplo de Jogo Correspondente, um pequeno aplicativo .NET Framework Windows Forms composto por um projeto principal e uma biblioteca de classes.

Pré-requisitos

• Windows sistema operacional.
• Visual Studio 2026.
• Baixe e extraia o aplicativo de demonstração usado com este artigo.
• O SDK do .NET para a versão de destino. Este artigo tem como destino .NET 10.
• Um repositório Git para a solução. O agente confirma seu progresso, portanto, o projeto deve estar sob controle do código-fonte.
• Modernização do GitHub Copilot habilitada para o Visual Studio. Para obter mais informações, consulte Instalar a modernização do GitHub Copilot.

Abrir a solução

Os projetos de Jogos Correspondentes têm como destino .NET Framework 4.5. Visual Studio solicita que você redirecione os projetos para uma versão compatível do .NET Framework ao abrir a solução.

1. Abra a solução MatchingGame em Visual Studio.
2. Visual Studio exibe a caixa de diálogo Estrutura de Destino Não Instalada.
3. Selecione Atualizar o destino para .NET Framework 4.8 (Recomendado) e selecione Continuar.
4. Abra a janela Alterações do Git e confirme as alterações de redirecionamento.

Notas importantes para Visual Basic

O agente de modernização do GitHub Copilot não dá suporte total a projetos Visual Basic .NET. O agente inclui proteções desenvolvidas especificamente para garantir que os projetos em C# sejam atualizados de forma confiável, e essas proteções interferem na análise e na execução de projetos em VB. Se sua solução contiver projetos de VB, use uma destas alternativas em vez disso:

• GitHub Copilot (agente padrão): Use o agente regular do Copilot — sem o agente de modernização — para orientar a atualização de forma interativa.
• Assistente de Atualização: uma ferramenta de migração dedicada com suporte para VB.

Se você usar o agente do Copilot padrão ou atualizar manualmente, siga estas etapas:

1. Se o projeto tiver como destino uma versão sem suporte do .NET Framework, redirecione-o para .NET Framework 4.8 primeiro. Visual Studio solicita que você faça isso quando abrir a solução ou pode alterá-la nas propriedades do projeto.

2. Atualize todos os pacotes NuGet desatualizados para suas versões compatíveis mais recentes.

3. Criar um novo projeto de Windows Forms VB usando um modelo de Visual Studio ou dotnet new winforms -lang vb. O modelo gera um arquivo de projeto no estilo do SDK e configurações que são diferentes dos do .NET Framework.

4. Copie os .vb arquivos de origem da pasta de projeto antiga para a nova pasta do projeto.

5. Copiar todos os arquivos sem código dos quais o projeto depende, como app.config.settings arquivos, imagens, ícones e outros recursos inseridos.

6. Abra o arquivo de projeto antigo (ou packages.config) e anote cada referência de pacote NuGet. Adicione esses mesmos pacotes ao novo projeto usando o nuGet Gerenciador de Pacotes ou dotnet add package <name>.

7. Se o projeto fizer referência a outros projetos na solução, adicione novamente essas referências no novo projeto.

8. Tente criar a solução. Não corrija os erros ainda — a saída da compilação dá ao Copilot uma lista concreta de problemas para trabalhar.

9. Confirme o estado atual no controle do código-fonte para que você tenha uma linha de base limpa antes que Copilot faça alterações.

10. Abra o GitHub Copilot Chat e peça que ele resolva os problemas restantes. Por exemplo:

    Este projeto Visual Basic Windows Forms foi migrado do .NET Framework 4.8 para o .NET 10. O arquivo de projeto e os arquivos-fonte estão no lugar, mas a solução não compila. Examine os erros de build e corrija incompatibilidades de API, referências ausentes e quaisquer problemas de migração de configuração.

11. Examine as alterações Copilot propõe, recompile e teste o projeto.

Iniciar a atualização

A solução Correspondente de Jogos contém o aplicativo MatchingGame e a biblioteca de classes MatchingGame.Logic . O agente descobre o grafo do projeto por conta própria, portanto, inicie a atualização no nível da solução.

1. Em Gerenciador de Soluções, clique com o botão direito do mouse na solução e selecione Modernizar.

   A janela Copilot Chat do GitHub é aberta e inicia uma conversa com o agente de modernização.

2. Selecione um modelo com recursos de raciocínio e codificação fortes.

3. Diga ao agente o que você quer fazer. Por exemplo:

   Atualize tudo para .NET 10.

   O agente relata o estado atual da base de código e o que planeja fazer:

   • Framework de destino: indica que o agente atualiza os projetos para .NET 10.
   • Modo de Fluxo: o padrão é Automático. Para aplicativos complexos, peça ao agente para mudar para o modo Guiado .
   • Controle de código-fonte: indica que o agente cria uma nova ramificação de trabalho.

   O agente grava seu trabalho em .github/upgrades/scenarios/dotnet-version-upgrade/ no seu repositório. Se essa pasta já existir de uma tentativa anterior, o agente perguntará se deseja continuar ou iniciar novamente.

4. Diga ao agente start para iniciar o processo de atualização.

Examinar a avaliação

No estágio de avaliação, o agente examina a estrutura do projeto, as dependências e os padrões de código para identificar o que precisa ser alterado. Grava os resultados em assessment.md em .github/upgrades/scenarios/dotnet-version-upgrade/.

Quando o Copilot concluir a avaliação, revise o resultado da conversa. Geralmente, ele começa com algo semelhante ao seguinte:

Assessment Complete

I've analyzed the solution and created a full assessment — see .github/upgrades/scenarios/dotnet-version-upgrade/assessment.md.

Solution summary:
• Target: net48 → net10.0
• Projects: 2
• MatchingGame.Logic (Class Library)
• MatchingGame (Windows Forms)
• Issues: 883 (673 mandatory, 210 potential)
• Affected Technologies: Windows Forms (666), GDI+ / System.Drawing (208), Legacy Configuration System (2)

Key concerns:
• Both projects are legacy-format .csproj files — need conversion to SDK-style
• MatchingGame.csproj has API incompatibilities (binary + source) and an incompatible NuGet package
• WinForms remains supported on .NET 10 (Windows-only TFM)
• No reported security vulnerabilities

Detalhamento da avaliação

Copilot abre o .github/upgrades/scenarios/dotnet-version-upgrade/assessment.md arquivo no editor de Visual Studio. Role para baixo até a MatchingGame\MatchingGame.csproj seção para ver uma tabela de problemas:

Tecnologia	Problemas	Porcentagem	Caminho de migração
Sistema de Configuração Herdado	2	0.2%	Sistema de configuração baseado em XML herdado (app.config/web.config) que foi substituído por um modelo de configuração mais flexível no .NET Core. O sistema antigo era rígido e baseado em XML. Migre para Microsoft. Extensions.Configuration com variáveis JSON/ambiente; use o pacote NuGet System.Configuration.ConfigurationManager como ponte provisória, se necessário.
GDI+/System.Drawing	208	23.7%	APIs de System.Drawing para gráficos 2D, imagens e impressão disponíveis por meio do pacote NuGet System.Drawing.Common. Observação: não recomendado para cenários de servidor devido a dependências Windows; considere alternativas multiplataforma como SkiaSharp ou ImageSharp para novo código.
Windows Forms	621	76.0%	Windows Forms APIs para criar aplicativos da área de trabalho Windows com a interface do usuário tradicional baseada em Formulários que estão disponíveis em .NET no Windows. Habilite o suporte ao Windows Forms: Opção 1 (Recomendado): use net10.0-windows como destino; Opção 2: Adicione <UseWindowsForms>true</UseWindowsForms>; Opção 3 (Legado): Use o SDK Microsoft.NET.Sdk.WindowsDesktop.

A maioria desses problemas não são problemas reais. Observe a coluna "Caminho de Migração" na linha GDI+, que lista 208 problemas. A avaliação sinaliza essas APIs porque elas estão disponíveis no .NET Framework, mas não em .NET. A coluna explica a correção: adicione o System.Drawing.Common pacote NuGet para restaurar as APIs.

A linha Windows Forms lista 621 problemas de API pelo mesmo motivo. As APIs do Windows Forms não estão disponíveis no .NET por padrão, mas você pode restaurá-las ao direcionar para um framework específico do Windows, como net10.0-windows, e definir <UseWindowsForms>true</UseWindowsForms> no arquivo de projeto. A Opção 3 sugere uma opção incorreta. Versões mais antigas do .NET exigiam que um projeto do Windows Forms tivesse como destino especificamente o SDK Microsoft.NET.Sdk.WindowsDesktop, mas agora o SDK é referenciado automaticamente quando <UseWindowsForms>true</UseWindowsForms> for definido.

Examinar as opções de atualização

Após a avaliação, o agente apresenta decisões sobre a estratégia de atualização e as salva em upgrade-options.md, em .github/upgrades/scenarios/dotnet-version-upgrade/. Para o exemplo de Jogo Correspondente, o agente seleciona as seguintes opções:

O agente também destaca os riscos que exigem sua atenção. Para o exemplo Matching Game, o agente sinaliza os pacotes MetroFramework porque estão disponíveis apenas para o .NET Framework. O resultado provável é remover MetroFramework e voltar aos controles de Windows Forms padrão, o que altera o estilo visual do aplicativo.

Examine as opções propostas e informe ao agente o que você deseja alterar. Por exemplo, diga ao agente para habilitar tipos de referência anuláveis ou fazer uma pausa para discutir primeiro as substituições de MetroFramework. Quando terminar, responda com confirm para confirmar as seleções e seguir para o planejamento.

Examinar o plano

No estágio de planejamento, o agente converte a avaliação e suas opções confirmadas em uma especificação detalhada. Ele grava o resultado plan.md e cria um scenario-instructions.md arquivo que armazena preferências, decisões e instruções personalizadas para a atualização.

O plano abrange itens como a ordem de atualização entre os projetos, o moniker da estrutura de destino para cada projeto (net10.0-windows para projetos dos Windows Forms), os caminhos de atualização dos pacotes e as mitigações de risco para as alterações incompatíveis identificadas na avaliação.

Para examinar e personalizar o plano:

1. Abra plan.md em .github/upgrades/scenarios/dotnet-version-upgrade/.
2. Analise as estratégias de atualização e as atualizações de dependência.
3. Edite o plano para ajustar as etapas ou adicionar contexto conforme necessário.
4. Diga ao agente para passar para a etapa de execução.

Executar a atualização

No estágio de execução, o agente divide o plano em tarefas sequenciais e concretas com critérios de validação. O agente registra a lista de tarefas em .github/upgrades/scenarios/dotnet-version-upgrade/tasks.md e acompanha o progresso geral neste arquivo. Para cada tarefa, o agente cria uma pasta sob .github/upgrades/scenarios/dotnet-version-upgrade/tasks/ a qual contém um arquivo Markdown que descreve a tarefa e um arquivo markdown que relata o progresso da tarefa.

Para o exemplo do Matching Game, a lista de tarefas normalmente inclui atualizar primeiro MatchingGame.Logic, depois MatchingGame, restaurar os pacotes, compilar a solução e fazer commit das alterações.

Para executar a atualização:

1. Diga ao agente para iniciar a atualização.
2. Monitore o progresso examinando tasks.md à medida que o agente atualiza os status da tarefa. Abra as pastas tasks/ por tarefa abaixo para a descrição da tarefa e um relatório de progresso detalhado.
3. Se o agente encontrar um problema que não pode resolver, forneça a ajuda solicitada. Por exemplo, o agente pode pedir que você escolha entre duas APIs de substituição ou confirme se deseja manter um pacote preterido.
4. Com base em suas respostas, o agente adapta sua estratégia para as tarefas restantes e continua.

O agente confirma alterações de acordo com a estratégia do Git configurada durante a pré-inicialização: por tarefa, por grupo de tarefas ou no final.

Notas para projetos de Visual Basic

Projetos do Visual Basic Windows Forms no .NET Framework geralmente usam arquivos de configuração System.Configuration e extensões My, como My.Computer e My.User. As My extensões foram removidas em .NET. O agente sinaliza esses padrões durante a avaliação e propõe correções durante a execução, mas talvez seja necessário confirmar alterações individuais durante uma execução guiada.

Se o agente migrar o projeto, mas ele não compilar, verifique se o arquivo de projeto tem o Windows como destino e faz referência ao Windows Forms. O elemento <PropertyGroup> deve ter a seguinte aparência:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0-windows</TargetFramework>
    <UseWindowsForms>true</UseWindowsForms>
    <OutputType>WinExe</OutputType>
    <MyType>WindowsForms</MyType>

    <!-- Other settings removed for brevity. -->
  </PropertyGroup>
</Project>

Verificar a atualização

Quando a atualização for concluída, o agente recomendará as próximas etapas na resposta do chat. Solicite ao agente que gere um relatório de alterações abrangente com "Gerar um relatório de alteração".

Examine o status tasks.md final da tarefa e confirme se cada etapa está concluída.

Para verificar a atualização:

1. Crie a solução e resolva os erros de compilação.

2. Execute o aplicativo e confirme se os formulários carregam e se comportam conforme o esperado.

   A fonte padrão do Windows Forms foi alterada entre o .NET Framework e o .NET; portanto, verifique os formulários e os controles personalizados para identificar diferenças de layout.

3. Execute todos os testes de unidade na solução e corrija falhas.

4. Confirme se os pacotes NuGet atualizados são compatíveis com seu aplicativo.

5. Teste o aplicativo minuciosamente para verificar se a atualização foi bem-sucedida.

O Windows Forms Exemplo de Jogo Correspondente agora é atualizado para .NET 10.

Experiência pós-atualização

Se você migrou o aplicativo do .NET Framework para o .NET, consulte Modernizar após atualizar do .NET Framework para o .NET para ver ideias de adoção de padrões mais modernos, como configuração, appsettings.json injeção de dependências ou serviços de nuvem. A adoção desses padrões é separada da atualização para .NET e não é necessária para concluir a atualização.

Conteúdo relacionado

• Visão geral da atualização de aplicativos Windows Forms
• Práticas recomendadas para modernização com o GitHub Copilot
• Portabilidade do .NET Framework para o .NET
• Modernizar após a atualização para o .NET a partir do .NET Framework
• Alterações significativas ao portar código