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

Instruções de atualização personalizadas são arquivos Markdown que orientam GitHub Copilot atualização para aplicar transformações específicas durante uma atualização. Crie esses arquivos para automatizar alterações repetitivas, como substituir uma biblioteca por outra ou aplicar uma atualização de API específica.

Este artigo explica como criar e estruturar um arquivo de instrução de atualização personalizado, testá-lo isoladamente e integrá-lo ao estágio de avaliação de um fluxo de trabalho de atualização.

Pré-requisitos

Configure GitHub Copilot atualização em seu ambiente de desenvolvimento antes de criar instruções personalizadas. Para obter as etapas de instalação, consulte Instalar GitHub Copilot atualização.

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

GitHub Copilot atualização recupera instruções de atualização personalizadas como arquivos markdown sob demanda durante os estágios de avaliação e planejamento de uma atualização. As instruções de atualização personalizadas diferem de copilot-instructions.md porque são:

  • Voltado para a automação de alterações de código e dependências.
  • Recuperado somente 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.

Estruturar seus arquivos de instrução com:

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

Além das instruções de atualização personalizadas, você pode estender GitHub Copilot atualização por meio do sistema de instruções e habilidades padrão. As habilidades adicionam recursos ao agente e os arquivos de instrução (como copilot-instructions.md) fornecem diretrizes globais.

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

Siga estas etapas para gerar e refinar um novo arquivo de instrução. Essas seções se concentram na substituição de Newtonsoft.Json por System.Text.Json como um exemplo.

Iniciar a atualização

Use as seguintes etapas para iniciar uma atualização:

  1. Inicie o agente usando um destes métodos:

    • Visual Studio: clique com o botão direito do mouse na solução ou projeto em Gerenciador de Soluções e selecione Modernize. Como alternativa, abra a janela Copilot Chat do GitHub e digite @Modernize.
    • Visual Studio Code: abra o painel GitHub Copilot Chat e digite @upgrade.
    • GitHub Copilot CLI: digite @upgrade seguido de sua solicitação de atualização ou migração.
    • GitHub aplicativo Copilot: No seletor do Agente, selecione Upgrade.

  2. Diga ao agente o que deve ser atualizado ou migrado.

Criar o arquivo de instrução

  1. No chat, digite: I want to generate a custom upgrade instruction.

  2. Quando solicitado, forneça um cenário como I want to replace Newtonsoft with System.Text.Json para que o Copilot crie o arquivo.

  3. Quando o Copilot cria o novo arquivo, como replace_newtonsoft_with_system_text_json.md, examine o conteúdo e refina-o no chat. Por exemplo, peça a Copilot para "esclarecer critérios de detecção" ou "adicionar uma seção de pré-requisitos."

    Dica

    Adicione o arquivo à solução para visibilidade se ele ainda não estiver incluído.

  4. Fortaleça a instrução com exemplos de diferenciação reais.

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

Dicas de criação

Siga estas diretrizes para escrever instruções de atualização personalizadas claras e eficazes que o Copilot pode interpretar de forma confiável:

  • Use frases condicionais claras: If code references X, then do Y.
  • Manter uma transformação por arquivo; use os pré-requisitos quando vários arquivos devem ser executados em sequência.
  • Forneça pelo menos um exemplo concreto, como um trecho de código de comparação ou antes/depois, para melhorar a precisão da transformação.
  • 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. O teste isolado ajuda você a refinar a detecção e verificar as alterações de código.

Iniciar a atualização

Use as seguintes etapas para iniciar uma atualização:

  1. Inicie o agente usando um destes métodos:

    • Visual Studio: clique com o botão direito do mouse na solução ou projeto em Gerenciador de Soluções e selecione Modernize. Como alternativa, abra a janela Copilot Chat do GitHub e digite @Modernize.
    • Visual Studio Code: abra o painel GitHub Copilot Chat e digite @upgrade.
    • GitHub Copilot CLI: digite @upgrade seguido de sua solicitação de atualização ou migração.
    • GitHub aplicativo Copilot: No seletor do Agente, selecione Upgrade.

  2. Diga ao agente o que deve ser atualizado ou migrado.

Testar a instrução de atualização

  1. No chat, invoque a instrução com texto semelhante ao nome do arquivo. Por exemplo, replace Newtonsoft with System.Text.Json.

  2. Confirme na janela de chat que Copilot recuperou o arquivo de instrução:

    > 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 Copilot não indicar que encontrou as instruções, tente novamente com palavras-chave do nome do arquivo, como as mesmas combinações de verbo e substantivo.

  3. Examine as alterações propostas (diferenças de solução, confirmações pendentes ou modificações visualizadas) para confirmar se a instrução de atualização personalizada se comporta conforme o esperado.

Dicas de validação

Se a execução de teste não produzir os resultados esperados, use estas dicas de solução de problemas para refinar seu arquivo de instrução:

  • Se Copilot apenas atualizar as versões do pacote em vez de substituir o pacote, verifique se a instrução diz explicitamente para remover ou substituir o pacote antigo.
  • Use uma nomenclatura consistente para que a ativação por linguagem natural corresponda. Por exemplo, inicie o nome do arquivo com replace_ e comece sua solicitação de chat com "Substituir ...".
  • Durante o teste, adicione quaisquer padrões de código ausentes como exemplos para melhorar a cobertura.

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

Use estas etapas para incorporar uma instrução de atualização personalizada existente no estágio de avaliação de uma atualização.

Iniciar a atualização

Para iniciar a atualização, siga estas etapas:

  1. Inicie o agente usando um destes métodos:

    • Visual Studio: clique com o botão direito do mouse na solução ou projeto em Gerenciador de Soluções e selecione Modernize. Como alternativa, abra a janela Copilot Chat do GitHub e digite @Modernize.
    • Visual Studio Code: abra o painel GitHub Copilot Chat e digite @upgrade.
    • GitHub Copilot CLI: digite @upgrade seguido de sua solicitação de atualização ou migração.
    • GitHub aplicativo Copilot: No seletor do Agente, selecione Upgrade.

  2. Diga ao agente o que deve ser atualizado ou migrado.

Personalizar a atualização

Siga estas etapas durante o estágio de avaliação:

  1. Monitore o chat para ver se o Copilot recupera automaticamente o arquivo de instrução personalizado durante a avaliação. Procure uma mensagem indicando que ela abriu o arquivo de instrução Markdown.

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

  2. Aguarde o Copilot para confirmar se ele recuperou o arquivo Markdown. Se você não vir uma referência ao arquivo de instrução, reafirme a solicitação usando os verbos de chave do arquivo (substituir, atualizar, remover) e nomes de pacote.

  3. Examine o arquivo gerado assessment.md na .github/upgrades pasta. Confirme se a avaliação inclui problemas e alterações que 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 refatoração para System.Text.Json.
    • Dependências a serem removidas ou substituídas.

  4. Se necessário, edite o assessment.md arquivo para adicionar contexto ou ajustar os problemas identificados antes de continuar.

  5. Diga ao Copilot para continuar para o estágio de planejamento uma vez que a avaliação reflita suas instruções personalizadas.

  6. Examine o arquivo plan.md gerado por Copilot. Esse arquivo inclui estratégias para resolver os problemas da avaliação.

  7. Prossiga para a fase de execução instruindo o Copilot a avançar. Monitore o arquivo tasks.md à medida que Copilot aplica as transformações.

Dicas para melhor ativação

Como você nomeia e invoca instruções de atualização personalizadas afeta se o Copilot as recupera automaticamente. Siga estas diretrizes para melhorar a confiabilidade da ativação:

  • Corresponda ao verbo do arquivo. Se o nome do arquivo usar replace, use essa frase (não upgrade ou fix).
  • Mantenha uma transformação por arquivo para maior clareza e reutilização. Sequencia vários arquivos listando pré-requisitos em cada arquivo.
  • Solicite instruções personalizadas durante a fase de avaliação para obter melhores resultados, em vez de aguardar até o planejamento ou a execução.
  • Evite solicitações ambíguas, como "melhorar a avaliação". Seja explícito: "aplique as instruções de 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 arquivo tasks.md em .github/upgrades para ver o status das tarefas relacionadas à sua instrução personalizada.
  2. Verifique as confirmações do Git criadas durante o estágio de execução para obter alterações relacionadas à instrução personalizada.
  3. Execute seus testes para garantir que o comportamento funcional permaneça correto.
  4. Opcional: capture um exemplo de diferenciação da alteração bem-sucedida e adicione-o ao arquivo de instrução para fortalecer a automação futura.

Limpar os recursos

Remova ou consolide quaisquer arquivos de instrução temporários para evitar transformações sobrepostas em atualizações futuras.

Conteúdo relacionado

  • Last updated on