Compartilhar via

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

Instruções de atualização personalizadas são arquivos Markdown que orientam a modernização do GitHub Copilot 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

Configurar a modernização do GitHub Copilot no seu ambiente de desenvolvimento antes de criar instruções personalizadas. Para obter as etapas de instalação, consulte Modernização do GitHub Copilot.

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

A modernização do GitHub Copilot recupera instruções de upgrade personalizadas em formato de arquivos Markdown, quando necessário, durante os estágios de avaliação e planejamento de um upgrade. 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 ampliar a modernização do GitHub Copilot por meio do sistema padrão de habilidades e instruções. 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.

  1. Na janela Gerenciador de Soluções, clique com o botão direito do mouse na solution>Modernize.

    - ou -

    Abra o painel de chat Copilot e digite @Modernize para iniciar uma conversa com o agente.

    Observação

    Estas etapas se aplicam a Visual Studio. Em Visual Studio Code e em outros ambientes, invoque o agente modernize-dotnet diretamente do painel de chat Copilot. Em Visual Studio, o agente é nomeado Modernize.

  2. No chat, digite: 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 que Copilot crie o arquivo.

  4. Quando 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.

  5. 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 Copilot podem 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.

  1. Na janela Gerenciador de Soluções, clique com o botão direito do mouse na solution>Modernize.

    Observação

    Estas etapas se aplicam a Visual Studio. Em Visual Studio Code e em outros ambientes, invoque o agente modernize-dotnet diretamente do painel de chat Copilot.

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

  3. 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.

  4. 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.

  1. Na janela Gerenciador de Soluções, clique com o botão direito do mouse na solution>Modernize.

    Observação

    Estas etapas se aplicam a Visual Studio. Em Visual Studio Code e em outros ambientes, invoque o agente modernize-dotnet diretamente do painel de chat Copilot.

  2. No chat, escolha Upgrade to a newer version of .NET. Responda às perguntas do Copilot até que ele inicie a avaliação.

  3. Monitore o chat para ver se 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.

  4. 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.

  5. 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 do System.Text.Json.
    • Dependências a serem removidas ou substituídas.

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

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

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

  9. Continue para a fase de execução dizendo ao Copilot para prosseguir. 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 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