Atualize uma aplicação Windows Forms para .NET com a modernização do GitHub Copilot

Este artigo explica como atualizar uma aplicação de ambiente de trabalho Windows Forms para .NET utilizando o agente de modernização GitHub Copilot. O agente executa o seu editor, analisa o projeto e gere um fluxo de trabalho em três fases: avaliação, planeamento e execução.

O exemplo utiliza o exemplo Matching Game, uma pequena aplicação .NET Framework para Windows Forms composta por um projeto principal e uma biblioteca de classes.

Pré-requisitos

Tip

Certifique-se de que tem uma cópia de segurança do seu código, por exemplo no controlo de código-fonte ou numa cópia, antes de começar.

Abra a solução

Os projetos Matching Game visam o .NET Framework 4.5. O Visual Studio pede que devas redirecionar os projetos para uma versão suportada do .NET Framework quando abres a solução.

  1. Abra a solução MatchingGame no Visual Studio.
  2. O Visual Studio mostra o diálogo Framework de Alvo Não Instalado.
  3. Selecione Atualizar o destino para .NET Framework 4.8 (Recomendado) e depois selecione Continuar.
  4. Abra a janela Alterações do Git e confirme as alterações de redirecionamento.

Notas importantes para o Visual Basic

O agente de modernização GitHub Copilot não apoia totalmente Visual Basic .NET projetos. O agente inclui guardaguardas especificamente desenhadas para garantir que os projetos C# sejam atualizados de forma fiável, e essas barreiras interferem com a análise e execução do projeto VB. Se a sua solução contém projetos VB, use uma destas alternativas:

  • GitHub Copilot (agente padrão): Use o agente do Copilot normal — sem o agente de modernização — para orientar a atualização de forma interativa.
  • Upgrade Assistant: Uma ferramenta dedicada de migração com suporte para VB.

Tip

Se a sua solução contiver projetos em C# e VB, ainda pode usar o agente de modernização para os projetos em C#. Atualize os projetos VB separadamente usando uma das alternativas listadas.

Se usar o agente do Copilot padrão ou atualizar manualmente, siga estes passos:

  1. Se o projeto tiver como objetivo uma versão não suportada do .NET Framework, redireciona-o primeiro para o .NET Framework 4.8. O Visual Studio pede para fazer isto quando abre a solução, ou pode alterá-lo nas propriedades do projeto.

  2. Atualize quaisquer pacotes NuGet desatualizados para as versões compatíveis mais recentes.

  3. Crie um novo projeto VB Windows Forms usando um modelo do Visual Studio ou dotnet new winforms -lang vb. O modelo produz um ficheiro de projeto do tipo SDK e definições que são diferentes dos do .NET Framework.

  4. Copie os seus .vb ficheiros de origem da pasta do projeto antigo para a pasta do projeto novo.

  5. Copie quaisquer ficheiros que não sejam código dos quais o projeto depende, como app.configficheiros , .settings imagens, ícones e outros recursos incorporados.

  6. Abre o ficheiro antigo do projeto (ou packages.config) e anota todas as referências de pacotes NuGet. Adicione esses mesmos pacotes ao novo projeto usando o NuGet Gestor de Pacotes ou dotnet add package <name>.

  7. Se o projeto referenciar outros projetos na solução, volte a adicionar essas referências no novo projeto.

  8. Tenta construir a solução. Não corrija ainda os erros — a saída da compilação fornece ao Copilot uma lista concreta de problemas com que trabalhar.

  9. Faz um commit do estado atual no controlo de versões para teres uma linha de base limpa antes de o Copilot fazer alterações.

  10. Abre o GitHub Copilot Chat e pede-lhe para resolver os problemas restantes. Por exemplo:

    Este projeto Visual Basic Windows Forms foi migrado do .NET Framework 4.8 para .NET 10. O ficheiro do projeto e os ficheiros de origem estão no lugar, mas a solução não compila. Revise os erros de compilação e corrija incompatibilidades da API, referências em falta e quaisquer problemas de migração de configuração.

  11. Revise as alterações que o Copilot propõe, depois reconstrua e teste o projeto.

Iniciar a atualização

A solução Matching Game contém a aplicação MatchingGame e a biblioteca de classes MatchingGame.Logic . O agente determina automaticamente o grafo do projeto, por isso inicie a atualização ao nível da solução.

  1. No Explorador de Soluções, clique com o botão direito na solução e selecione Modernizar.

    A janela do GitHub Copilot Chat abre-se e inicia uma conversa com o agente de modernização.

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

  3. Diz ao agente o que queres fazer. Por exemplo:

    Atualiza tudo para .NET 10.

    O agente reporta o estado atual da base de código e o que planeia fazer:

    • Framework Target: Indica que o agente atualiza os projetos para .NET 10.
    • Modo de fluxo: Por predefinição, é Automático. Para aplicações complexas, peça ao agente para mudar para o modo Guiado .
    • Controlo de código-fonte: Indica que o agente cria uma nova ramificação de trabalho.

    O agente guarda o seu trabalho em .github/upgrades/scenarios/dotnet-version-upgrade/ no teu repositório. Se essa pasta já existir de uma tentativa anterior, o agente pergunta se deve continuar ou começar do zero.

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

Rever a avaliação

Na fase 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 de mudar. Escreve os resultados para assessment.md em .github/upgrades/scenarios/dotnet-version-upgrade/.

Quando o Copilot terminar a avaliação, reveja o resultado da conversa. Geralmente 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

Divisão da avaliação

O Copilot abre o .github/upgrades/scenarios/dotnet-version-upgrade/assessment.md ficheiro no editor do Visual Studio. Desça até à MatchingGame\MatchingGame.csproj secção para ver uma tabela de problemas:

Tecnologia Issues Percentagem Caminho de Migração
Sistema Legado de Configuração 2 0,2% Sistema de configuração baseado em XML legado (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. Migrar para Microsoft.Extensions.Configuration com JSON/variáveis de ambiente; utilizar o pacote NuGet System.Configuration.ConfigurationManager como solução de transição, se necessário.
GDI+ / System.Drawing 208 23,7% APIs System.Drawing para gráficos 2D, imagem e impressão disponíveis através do pacote NuGet System.Drawing.Common. Nota: Não recomendado para cenários de servidor devido a dependências do Windows; considere alternativas multiplataforma como SkiaSharp ou ImageSharp para novo código.
Windows Forms 621 76.0% APIs do Windows Forms para construir aplicações de ambiente de trabalho Windows com interface tradicional baseada em Forms que estão disponíveis em .NET no Windows. Ativar o suporte do Windows Forms: Opção 1 (recomendada): Definir como destino net10.0-windows; Opção 2: Adicionar <UseWindowsForms>true</UseWindowsForms>; Opção 3 (legado): Utilizar o SDK Microsoft.NET.Sdk.WindowsDesktop.

A maioria destes problemas não são problemas reais. Veja a coluna "Caminho de migração" na linha GDI+, onde estão listados 208 problemas. A avaliação assinala estas APIs porque estão disponíveis no .NET Framework, mas não no .NET. A coluna explica a correção: adicionar o System.Drawing.Common pacote NuGet para restaurar as APIs.

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

Tip

Para saber mais sobre uma opção, peça ao Copilot mais informações e contexto.

Revise as opções de atualização

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

Aspect Decisão Reason
Estratégia de atualização De baixo para cima. O agente melhora primeiro o MatchingGame.Logic porque o MatchingGame depende disso, depois valida cada nível antes de avançar.
Abordagem do projeto No lugar. Ambos os projetos migram juntos porque nenhum outro projeto do .NET Framework os consome.
Pacotes não suportados Resolva no local. A avaliação encontrou apenas alguns pacotes incompatíveis, pelo que o agente procura alternativas enquanto trabalha.
Tratamento de API não suportado Corrigir em linha. A maioria das alterações na API do Windows Forms e GDI+ para .NET são mecânicas e não requerem uma passagem de planeamento separada.
APIs nativas do Windows Pacote de Compatibilidade Windows. A aplicação utiliza muito o Windows Forms e o GDI+ e é inerentemente exclusiva do Windows.
Tipos de referência anuláveis Deixe desativado. O agente trata a ativação do nullable como um esforço separado após a migração.

O agente também aponta riscos que exigem a sua atenção. No exemplo de Matching Game, o agente assinala os MetroFramework pacotes porque só estão disponíveis para o .NET Framework. O resultado provável é remover MetroFramework e voltar aos controlos padrão do Windows Forms, o que altera o estilo visual da aplicação.

Revê as opções propostas e diz ao agente o que queres mudar. Por exemplo, diga ao agente para ativar os tipos de referência anuláveis ou para fazer uma pausa e discutir primeiro as substituições de MetroFramework. Quando terminares, seleciona confirm para confirmar as seleções e avançar para o planeamento.

Revise o plano

Na fase de planeamento, o agente converte a avaliação e as suas opções confirmadas numa especificação detalhada. Escreve o resultado em plan.md e cria um ficheiro scenario-instructions.md que armazena preferências, decisões e instruções personalizadas para a atualização.

Importante

Se Modo de fluxo estiver definido como Automático, o agente começa a executar o plano sem tempo para o rever.

O plano abrange itens como a ordem de atualização entre projetos, a designação de framework-alvo para cada projeto (net10.0-windowspara projetos Windows Forms), caminhos de atualização de pacotes e mitigações de risco para as alterações urgentes que a avaliação encontrou.

Para rever e personalizar o plano:

  1. Abrir plan.md em .github/upgrades/scenarios/dotnet-version-upgrade/.
  2. Revise as estratégias de atualização e as atualizações de dependências.
  3. Edite o plano para ajustar os passos ou adicionar contexto conforme necessário.
  4. Diz ao agente para avançar para a fase de execução.

Caution

O plano depende das interdependências do projeto. A melhoria não tem sucesso se modificares o plano de forma a impedir que o caminho da melhoria seja concluído. Por exemplo, se o MatchingGame depender do MatchingGame.Logic e retirares o MatchingGame.Logic do plano, a atualização do MatchingGame pode falhar.

Executar a atualização

Na fase de execução, o agente divide o plano em tarefas sequenciais e concretas com critérios de validação. O agente escreve a lista de tarefas em .github/upgrades/scenarios/dotnet-version-upgrade/tasks.md e acompanha o progresso geral nesse ficheiro. Para cada tarefa, o agente cria uma pasta em .github/upgrades/scenarios/dotnet-version-upgrade/tasks/ que contém um ficheiro Markdown que descreve a tarefa e um ficheiro Markdown que regista o progresso da tarefa.

Para o exemplo de Matching Game, a lista de tarefas normalmente inclui atualizar primeiro o MatchingGame.Logic , depois o MatchingGame, restaurar pacotes, construir a solução e confirmar as alterações.

Para executar a atualização:

  1. Diz ao agente para iniciar a atualização.
  2. Monitorize o progresso analisando tasks.md à medida que o agente atualiza os estados das tarefas. Abra as pastas por tarefa abaixo tasks/ para a descrição da tarefa e um relatório detalhado de progresso.
  3. Se o agente encontrar um problema que não consiga resolver, forneça a ajuda solicitada. Por exemplo, o agente pode pedir-lhe para escolher entre duas APIs de substituição ou confirmar se deve manter um pacote obsoleto.
  4. Com base nas suas respostas, o agente adapta a sua estratégia às tarefas restantes e continua.

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

Notas para projetos com Visual Basic

Os projetos do Visual Basic Windows Forms no .NET Framework utilizam frequentemente ficheiros System.Configuration de configuração e extensões My, como My.Computer e My.User. As My extensões foram removidas no .NET. O agente assinala estes padrões durante a avaliação e propõe correções durante a execução, mas pode ser necessário confirmar alterações individuais durante uma execução guiada.

Se o agente migrar o projeto mas este não compilar, verifica se o ficheiro do projeto tem como alvo o Windows e faz referência ao Windows Forms. O <PropertyGroup> elemento deve assemelhar-se ao seguinte excerto:

<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 termina, o agente recomenda os próximos passos na resposta do chat. Incentive o agente a gerar um relatório de alteração abrangente com "Gerar um relatório de alteração."

Reveja o estado final da tarefa em tasks.md e confirme que cada passo está concluído.

Para verificar a atualização:

  1. Construa a solução e resolva quaisquer erros de compilação.

  2. Abre a aplicação e confirma que os formulários carregam e se comportam como esperado.

    A fonte padrão no Windows Forms mudava entre o .NET Framework e o .NET, por isso verifique os formulários e controlos personalizados para diferenças de layout.

  3. Executa quaisquer testes unitários na solução e corrige as falhas.

  4. Confirma se os pacotes NuGet atualizados são compatíveis com a tua aplicação.

  5. Testa a aplicação cuidadosamente para confirmar que a atualização foi bem-sucedida.

Tip

Se o projeto não executar e não for possível anexar um depurador, tente reiniciar o Visual Studio. Migrar ficheiros de projeto do .NET Framework para o .NET pode confundir o designer do Windows Forms sem necessidade de reiniciar.

O Windows Forms Matching Game Sample está agora atualizado para .NET 10.

Experiência pós-atualização

Se migrou a aplicação do .NET Framework para o .NET, consulte Modernizar após atualizar do .NET Framework para o .NET para obter ideias sobre como adotar padrões mais recentes, como appsettings.json configuração, injeção de dependências ou serviços de cloud. Adotar estes padrões é separado da atualização para .NET e não é necessário para completar a atualização.

Conteúdo relacionado

  • Last updated on