Solução de problemas na modernização do GitHub Copilot

Este artigo aborda problemas comuns que você pode encontrar ao usar GitHub Copilot modernização para .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 a pasta tiver sido excluída acidentalmente, 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 de travamento persistir, informe o agente para "marcar a tarefa atual como pendente e reiniciá-la" ou "reavaliar e continuar a partir da última etapa concluída".
3. Verifique o arquivo correspondente progress-details.md para que a tarefa entenda 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 migrar de Newtonsoft.Json para System.Text.Json."
• "Converter meu projeto em formato estilo SDK."

Adicione também preferências de cenário a 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 os 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 quais alterações o agente fez 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ê consegue 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 aprenderá com sua correção manual e aplicará padrões semelhantes se o mesmo problema aparecer em outro lugar.

Problemas do Git

O agente não pode criar um branch

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

Solution:

1. Confirme ou esconda suas alterações pendentes antes de iniciar um cenário.
2. Verifique se o Git foi inicializado: execute 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. Volte para o seu branch original: git checkout main (ou para aquele que for o seu branch base).
2. O ramo de trabalho do agente contém todas as alterações que estão isoladas do ramo principal.
3. Para remover totalmente o branch do agente: git branch -D <agent-branch-name>.
4. Para manter algumas alterações, escolha commits específicos: 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 muito 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 ou tem metadados ausentes ou inválidos ou o formato de habilidade está 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. Verifique 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 que o agente encontrou.
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