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

Este artigo explica como atualizar uma aplicação de ambiente de trabalho WPF para .NET usando 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 WPF 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.
  • Instalar o .NET 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 mencionadas acima.

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 WPF usando um template do Visual Studio ou dotnet new wpf -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 WPF 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: MatchingGame.slnx → target: net10.0

Compatibility Statistics:

- Projects: 2 (both currently on net48, legacy project format)
- Issues: 100 (Mandatory: 91, Potential: 9, Optional: 0)
- Affected Files: 6
- Affected Technologies: WPF (61 issues), Legacy Configuration System (2 issues)

Projects:

| Project                                      | Current TFM | Type                  |
|----------------------------------------------|-------------|-----------------------|
| MatchingGame.Logic\MatchingGame.Logic.csproj | net48       | Classic Class Library |
| MatchingGame\MatchingGame.csproj             | net48       | Classic WPF           |

Key issues found:

- Both projects use legacy (non-SDK-style) project format → must be converted to SDK-style
- Both project target frameworks need to change to net10.0
- WPF project (MatchingGame.csproj) has binary/source/behavioral API incompatibilities and Legacy Configuration System usage

No security vulnerabilities were detected, and no NuGet packages are referenced — this is a self-contained WPF + library solution.
Proceeding to planning now. You can ask me to pause and switch to Guided mode at any time.

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.
Tratamento de API não suportado Corrigir em linha. A maioria das alterações à API WPF 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 usa o registo e é inerentemente exclusiva para 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. 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 alterar a forma como os pacotes incompatíveis são tratados. 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 dos projetos, o identificador da framework de destino para cada projeto (net10.0-windows para projetos WPF), os caminhos de atualização de pacotes e as medidas de mitigação dos riscos associados às alterações interruptivas identificadas pela avaliação.

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 regista as alterações de acordo com a estratégia do Git que configurou durante a pré-inicialização: por tarefa, por grupo de tarefas ou no final.

Notas para projetos com Visual Basic

Os projetos WPF em Visual Basic no .NET Framework utilizam frequentemente ficheiros de definições System.Configuration 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 WPF. O <PropertyGroup> elemento deve assemelhar-se ao seguinte excerto:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0-windows</TargetFramework>
    <UseWPF>true</UseWPF>
    <OutputType>WinExe</OutputType>
    <MyType>Windows</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."

Verifique 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. Executa a aplicação e confirma se as janelas e as vistas carregam e se comportam como esperado. Reveja quaisquer diferenças visuais ou comportamentais nos controlos XAML e nos controlos personalizados entre o .NET Framework e o .NET.
  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 .NET pode confundir o designer do WPF sem necessidade de reiniciar.

O Exemplo de Jogo de Correspondência WPF foi agora atualizado para .NET 10.

Experiência pós-atualização

Se migrou a aplicação do .NET Framework para o .NET, consulte Modernize as suas aplicações .NET Framework atualizadas para obter ideias sobre como adotar padrões mais recentes, como a appsettings.json configuração, a injeção de dependências ou os serviços na 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