Partilhar via

Aplicar instruções de atualização personalizadas para atualizações do .NET

As instruções personalizadas de atualização são ficheiros Markdown que orientam a modernização do GitHub Copilot para aplicar transformações específicas durante uma atualização. Crie estes ficheiros para automatizar alterações repetitivas, como substituir uma biblioteca por outra ou aplicar uma atualização específica da API.

Este artigo explica como criar e estruturar um ficheiro de instruções de atualização personalizado, testá-lo isoladamente e integrá-lo na fase de avaliação de um fluxo de trabalho de atualização.

Pré-requisitos

Configura a modernização do GitHub Copilot no teu ambiente de desenvolvimento antes de criares instruções personalizadas. Para as instruções de instalação, veja modernização do GitHub Copilot.

Compreender as instruções de atualização personalizadas

A modernização do GitHub Copilot recupera instruções de atualização personalizadas como ficheiros Markdown sob demanda durante as fases de avaliação e planeamento de uma atualização. As instruções de atualização personalizadas diferem de copilot-instructions.md porque são:

  • Direcionado para automatizar alterações de código e dependência.
  • Consultado apenas quando relevante para a avaliação ou plano de atualização atual.
  • Reutilizável em várias soluções quando é copiado para cada repositório.

Estruture seus arquivos de instruções com:

  • Um título curto que descreve a ação. Por exemplo, "substitua Newtonsoft.Json por System.Text.Json."
  • Uma declaração concisa do problema ou uma seção de pré-requisitos.
  • Lógica de passos explícita ("Se X for encontrado, faça Y"). Evite linguagem vaga.
  • (Recomendado) Um ou mais exemplos de diff capturados de edições locais reais para orientar transformações.

Para além das instruções personalizadas de atualização, pode estender a modernização do GitHub Copilot através do sistema padrão de competências e instruções. As competências acrescentam capacidades ao agente, e os ficheiros de instruções (como copilot-instructions.md) fornecem orientação global.

Criar uma instrução de atualização personalizada

Siga estas etapas para gerar e refinar um novo arquivo de instruções. Estas secções focam-se em substituir Newtonsoft.Json por System.Text.Json exemplo.

  1. Na janela Explorador de Soluções, clique com o botão direito no solution>Modernize.

    -ou-

    Abre o painel de chat Copilot e escreve @Modernize para iniciar uma conversa com o agente.

    Observação

    Estes passos aplicam-se ao Visual Studio. Em Visual Studio Code e outros ambientes, invoca o agente modernize-dotnet diretamente a partir do painel de chat Copilot. Em Visual Studio, o agente é chamado Modernize.

  2. No chat, escreva: I want to generate a custom upgrade instruction.

  3. Quando solicitado, forneça um cenário como I want to replace Newtonsoft with System.Text.Json para Copilot criar o ficheiro.

  4. Quando o Copilot criar o novo ficheiro, como replace_newtonsoft_with_system_text_json.md, reveja o conteúdo e refine-o na conversa. Por exemplo, peça Copilot para "clarificar critérios de deteção" ou "adicionar uma secção de pré-requisito."

    Sugestão

    Adicione o ficheiro à solução para visibilidade, caso ainda não esteja incluído.

  5. Reforça a instrução com exemplos reais e diferentes.

    1. Faça as alterações de código desejadas manualmente em um projeto. Por exemplo, "remova o Newtonsoft.Json pacote, atualize as diretivas de uso e substitua o JsonConvert código por JsonSerializer".
    2. No chat, com o arquivo de instruções aberto, digite: Check my git changes and add diffs as examples to my instruction file.
    3. Confirme que o Copilot usou um diferencial git e anexou um bloco de diferencial cercado ou um exemplo estruturado ao ficheiro Markdown.

Dicas de criação

Siga estas orientações para escrever instruções de atualização personalizadas claras e eficazes que o Copilot possa interpretar de forma fiável:

  • Use uma formulação condicional clara: If code references X, then do Y.
  • Manter uma transformação por ficheiro; Use pré-requisitos quando vários arquivos devem ser executados em sequência.
  • Forneça pelo menos um exemplo concreto, como um diferencial ou um excerto antes/depois, para melhorar a precisão das transformações.
  • Evite verbos ambíguos como "melhorar" ou "corrigir"; Use ações explícitas como "substituir", "remover" e "atualizar".

Testar uma instrução de atualização personalizada (execução única)

Antes de executar a instrução durante uma atualização, valide-a isoladamente. Testes isolados ajudam-no a refinar a deteção e a verificar alterações no código.

  1. Na janela Explorador de Soluções, clique com o botão direito no solution>Modernize.

    Observação

    Estes passos aplicam-se ao Visual Studio. Em Visual Studio Code e outros ambientes, invoca o agente modernize-dotnet diretamente a partir do painel de chat Copilot.

  2. No chat, invoca a instrução com uma redação semelhante ao nome do ficheiro. Por exemplo, replace Newtonsoft with System.Text.Json.

  3. Confirma na janela de chat que o Copilot recuperou o ficheiro de instruções:

    > Getting instructions for 'replace Newtonsoft with System.Text.Json'.

Perfect! I've retrieved the scenario instructions for upgrading from Newtonsoft.Json to System.Text.Json. Now I'll begin the analysis following the scenario-specific instructions.

    Se o Copilot não indicar que encontrou as instruções, tente novamente com palavras-chave do nome do ficheiro, como as mesmas combinações de verbo e substantivo.

  4. Revise as alterações propostas (diferenças de solução, commits pendentes ou modificações pré-visualizadas) para confirmar que a instrução de atualização personalizada se comporta como esperado.

Dicas de validação

Se o teste não produzir os resultados esperados, use estas dicas de resolução de problemas para refinar o seu ficheiro de instruções:

  • Se o Copilot apenas atualizar as versões dos pacotes em vez de substituir o pacote, certifique-se de que a instrução diz explicitamente para remover ou substituir o pacote antigo.
  • Use nomes consistentes para que a ativação em linguagem natural corresponda. Por exemplo, inicia o nome do ficheiro com replace_ e começa o teu pedido de chat com "Substituir ...".
  • Durante os testes, adicione quaisquer padrões de código em falta como exemplos para melhorar a cobertura.

Aplicar instruções personalizadas durante uma atualização

Utilize estes passos para incorporar uma instrução de atualização personalizada existente na fase de avaliação de uma atualização.

  1. Na janela Explorador de Soluções, clique com o botão direito no solution>Modernize.

    Observação

    Estes passos aplicam-se ao Visual Studio. Em Visual Studio Code e outros ambientes, invoca o agente modernize-dotnet diretamente a partir do painel de chat Copilot.

  2. No chat, escolhe Upgrade to a newer version of .NET. Responda às perguntas do Copilot até começar a avaliação.

  3. Monitorize o chat para ver se o Copilot recupera automaticamente o seu ficheiro de instruções personalizadas durante a avaliação. Procura uma mensagem a indicar que abriu o ficheiro de instruções Markdown.

    Se o Copilot não aplicar automaticamente as instruções personalizadas, pede-as explicitamente. Use uma redação semelhante ao nome do ficheiro. Por exemplo, use the custom instructions to replace Newtonsoft with System.Text.Json during the assessment.

  4. Espera que o Copilot confirme que recuperou o ficheiro Markdown. Se não vires referência ao ficheiro de instruções, reformula o pedido usando os verbos-chave do ficheiro (substituir, atualizar, remover) e os nomes dos pacotes.

  5. Revise o ficheiro gerado assessment.md na .github/upgrades pasta. Confirme que a avaliação inclui problemas e alterações que a sua instrução personalizada identificou.

    Por exemplo, ao substituir Newtonsoft, a avaliação identifica:

    • Projetos usando Newtonsoft.Json pacotes.
    • Padrões de código para a refatoração de System.Text.Json.
    • Dependências a remover ou substituir.

  6. Se necessário, edite o assessment.md ficheiro para adicionar contexto ou ajuste os problemas identificados antes de avançar.

  7. Diga ao Copilot para prosseguir para a fase de planeamento quando a avaliação refletir a sua instrução personalizada.

  8. Revise o ficheiro plan.md que Copilot gera. Este ficheiro inclui estratégias para abordar as questões da avaliação.

  9. Continua durante a fase de execução dizendo ao Copilot para continuar. Monitorize o ficheiro tasks.md à medida que Copilot aplica as transformações.

Dicas para uma melhor ativação

A forma como nomeias e invocas instruções de melhoria personalizadas afeta se o Copilot as recupera automaticamente. Siga estas orientações para melhorar a fiabilidade da ativação:

  • Combine o verbo do ficheiro. Se o nome do ficheiro usar replace, use essa expressão (não upgrade ou fix).
  • Mantém uma transformação por ficheiro para maior clareza e reutilização. Sequencie vários ficheiros listando os pré-requisitos em cada ficheiro.
  • Solicite instruções personalizadas durante a fase de avaliação para melhores resultados, em vez de esperar pelo planeamento ou execução.
  • Evite pedidos ambíguos como "melhorar a avaliação." Seja explícito: "aplique as instruções replace_newtonsoft_with_system_text_json durante a avaliação."

Validar as alterações aplicadas

Após a conclusão da atualização:

  1. Revise o tasks.md ficheiro .github/upgrades para ver o estado das tarefas relacionadas com a sua instrução personalizada.
  2. Verifique os commits Git criados durante a fase de execução para alterações relacionadas com a instrução personalizada.
  3. Execute os testes para garantir que o comportamento funcional permaneça correto.
  4. Opcional: Capturar um exemplo diferente da alteração bem-sucedida e adicioná-lo ao ficheiro de instruções para reforçar a automação futura.

Limpeza de recursos

Remover ou consolidar quaisquer ficheiros de instruções temporários para evitar transformações sobrepostas em futuras atualizações.

Conteúdo relacionado

  • Last updated on