Solucionar problemas da modernização do GitHub Copilot

Este artigo aborda problemas comuns que você pode encontrar ao usar o GitHub Copilot para modernização no .NET, organizados por categoria. Cada entrada segue um problema, uma causa e um formato de solução para que você possa encontrar e resolver problemas rapidamente.

Problemas de fluxo de trabalho

Esses problemas estão relacionados à descoberta de cenários, à retomada do trabalho e ao estado da tarefa.

Agente diz "nenhum cenário encontrado"

Cause: O agente não reconhece o workspace como um projeto .NET.

Solution:

1. Verifique se a raiz do workspace contém um arquivo .sln, .csproj ou .vbproj.
2. Pergunte ao agente: "Qual solução ou arquivo de projeto você está usando?"
3. Se a solução ou o arquivo de projeto estiver em um subdiretório, abra esse diretório como a raiz do workspace ou aponte o agente para o arquivo explicitamente.

O agente não pode retomar o trabalho anterior

Causa: A .github/upgrades/ pasta, na qual o agente armazena todo o seu estado, está ausente ou corrompida.

Solution:

1. Verifique se a .github/upgrades/ pasta existe na raiz do repositório.
2. Se você excluiu acidentalmente a pasta, inicie o cenário novamente. O agente não pode se recuperar sem seus arquivos de estado.
3. Se a pasta existir, mas os arquivos parecerem corrompidos, peça ao agente para "reavaliar e planejar novamente" para regenerá-los.

Tarefas paralisadas em andamento

Causa: A sessão anterior terminou enquanto o agente estava no meio da tarefa.

Solution:

1. O agente detecta automaticamente tarefas obsoletas na maioria dos casos. Informe ao agente "retomar" ou "reiniciar a tarefa atual".
2. Se o estado travado persistir, diga ao agente "marcar a tarefa atual como pendente e reiniciá-la" ou "reavaliar e continuar da última etapa concluída".
3. Verifique o arquivo correspondente progress-details.md para entender onde a sessão anterior foi interrompida.

O agente continua sugerindo o cenário errado

Causa: A análise do agente pegou características inesperadas do projeto e inferiu um cenário diferente do que você pretendia.

Solution:

Seja explícito sobre o que você quer. Em vez de "atualizar meu projeto", diga:

• "Quero atualizar para .NET 10."
• "Quero atualizar de Newtonsoft.Json para System.Text.Json."
• "Converter meu projeto em formato estilo SDK."

Adicione preferências de cenário ao scenario-instructions.md para evitar incompatibilidades futuras.

Problemas de build e compilação

Esses problemas estão relacionados a falhas de build, problemas de restauração do NuGet e erros de geração de código.

O build falha após as alterações do agente

Causa: As atualizações podem introduzir alterações de API interruptivas, pacotes ausentes ou padrões de código incompatíveis.

Solution:

1. Conte ao agente sobre a falha. O agente analisa erros automaticamente.
2. Se o agente não puder resolver o problema, reverta a última confirmação (git revert HEAD) e peça ao agente para tentar uma abordagem diferente.
3. Para falhas complexas, verifique execution-log.md para entender o que o agente alterou e em qual ordem.

Falha na restauração do NuGet

Causa: Incompatibilidade de pacotes com a estrutura de destino ou falhas de autenticação com feeds NuGet privados.

Solution:

• Para feeds privados: Autentique-se no feed antes de iniciar a atualização.
• Para pacotes incompatíveis: Diga ao agente qual pacote é problemático. O agente pode pesquisar versões compatíveis ou sugerir pacotes alternativos.
• Para problemas de conectividade de feed: Verifique se você pode executar dotnet restore manualmente. Corrija os problemas de feed primeiro e, em seguida, deixe o agente tentar novamente.

O agente gera um código que não é compilado

Causa: O código gerado por IA pode conter erros, especialmente em casos de borda ou com padrões de API incomuns.

Solution:

1. O agente detecta erros de compilação automaticamente. Se o agente estiver em dificuldades, forneça diretrizes ou corrija o código manualmente e diga ao agente para continuar.
2. Se o agente tiver dificuldades com uma correção específica após várias tentativas, edite o código manualmente e diga ao agente: "Corrigi o erro de compilação em MyClass.cs, marque esta tarefa concluída".
3. O agente aprende com a sua correção manual e aplica padrões semelhantes quando o mesmo problema ocorre em outro lugar.

Problemas do Git

O agente não pode criar uma ramificação

Causa: Alterações não confirmadas na árvore de trabalho, um conflito de nomenclatura de ramificação ou o Git não está inicializado no espaço de trabalho.

Solution:

1. Confirme ou armazene suas alterações pendentes antes de iniciar um cenário.
2. Verifique se o Git é inicializado executando git status na raiz do workspace.
3. Caso já exista um ramo com o nome desejado pelo agente, exclua o ramo existente ou peça ao agente que use um nome de ramo diferente.

Desfazer todas as alterações do agente

Causa: A atualização não foi conforme o planejado e você deseja recomeçar.

Solution:

1. Retorne à ramificação original com git checkout main (ou à sua ramificação base).
2. A ramificação de trabalho do agente contém todas as alterações que estão isoladas da ramificação principal.
3. Para remover totalmente a ramificação do agente, execute git branch -D <agent-branch-name>.
4. Para manter algumas alterações, selecione commits específicos com git cherry-pick <commit-hash>.

Problemas de desempenho

Esses problemas estão relacionados à velocidade de atualização e à duração da avaliação.

O agente está lento ou leva muito tempo

Causa: Soluções grandes com muitos projetos, grafos de dependência complexos ou várias alterações interruptivas naturalmente levam mais tempo.

Solution:

Para soluções grandes (mais de 50 projetos), considere a atualização em lotes. Agrupe projetos relacionados e atualize-os juntos.

A avaliação leva muito tempo

Causa: A avaliação analisa as dependências de cada projeto, pacotes NuGet, frameworks de destino e alterações de ruptura aplicáveis. Para soluções grandes, a avaliação naturalmente leva mais tempo.

Solution:

1. Tempos de avaliação longos são normais para soluções grandes. Nenhuma ação é necessária.
2. Monitore o progresso no painel Output (selecione AppModernizationExtension na lista suspensa em Visual Studio).
3. A avaliação é executada apenas uma vez por cenário. As fases subsequentes usam os resultados armazenados em cache.

Problemas de personalização

Esses problemas estão relacionados a habilidades personalizadas e arquivos de instrução de cenário.

A habilidade personalizada não é detectada

Causa: O arquivo de habilidade está no local errado, tem metadados ausentes ou inválidos ou tem um formato incorreto.

Solution:

1. Verifique se o arquivo de habilidade está em um dos locais com suporte:
   • .github/skills/ (nível de repositório, a nível de toda a equipe)
   • .github/upgrades/skills/ (nível de cenário)
   • %UserProfile%/.copilot/skills/ (nível do usuário, pessoal)
2. Verifique se os metadados de habilidade incluem pelo menos name e description campos.
3. Confirme se o discovery campo (se definido) é um dos seguintes: lazy, preloadou scenario.
4. Verifique se a habilidade corresponde description ao tipo de tarefa à qual você espera que ela se aplique. O agente usa a correspondência de descrições para selecionar habilidades.

As alterações no scenario-instructions.md não entrarão em vigor

Causa: O agente pode não reler o arquivo durante a sessão, ou suas edições estão na seção errada.

Solution:

1. Peça ao agente para "recarregar instruções" ou iniciar uma nova sessão de chat para forçar uma releitura.
2. Verifique se as edições estão nas seções corretas do arquivo:
   • Preferências do usuário: Para preferências e restrições gerais.
   • Principais decisões: Para registrar decisões importantes tomadas durante a atualização.
   • Instruções personalizadas: Para ajustes comportamentais específicos.
3. Verifique se o arquivo foi salvo e no caminho esperado: .github/upgrades/{scenarioId}/scenario-instructions.md.

Obter ajuda

Quando algo não está funcionando conforme o esperado:

1. Pergunte ao agente: Pergunte "O que deu errado com a última tarefa?" O agente geralmente pode explicar o que aconteceu e sugerir as próximas etapas.
2. Examine o log de execução: Abra execution-log.md em .github/upgrades/{scenarioId}/. O log mostra um registro cronológico do que o agente fez, incluindo os erros encontrados.
3. File um problema: Se você encontrou um bug ou o agente falha consistentemente em algo, registre um problema no repositório @modernize-dotnet GitHub.

Conteúdo relacionado

• O que é a modernização do GitHub Copilot?
• Práticas recomendadas
• Conceitos básicos
• Perguntas frequentes sobre a modernização do GitHub Copilot