Appliquer des instructions de mise à niveau personnalisées pour les mises à niveau .NET

Les instructions de mise à niveau personnalisées sont des fichiers Markdown qui guident GitHub Copilot mise à niveau pour appliquer des transformations spécifiques lors d’une mise à niveau. Créez ces fichiers pour automatiser les modifications répétitives, telles que le remplacement d’une bibliothèque par une autre ou l’application d’une mise à niveau d’API spécifique.

Cet article explique comment créer et structurer un fichier d’instructions de mise à niveau personnalisé, le tester en isolation et l’intégrer à l’étape d’évaluation d’un workflow de mise à niveau.

Prerequisites

Configurez GitHub Copilot mise à niveau dans votre environnement de développement avant de créer des instructions personnalisées. Pour connaître les étapes d’installation, consultez Installer GitHub Copilot mise à niveau.

Comprendre les instructions de mise à niveau personnalisées

GitHub Copilot mise à niveau récupère des instructions de mise à niveau personnalisées en tant que fichiers Markdown à la demande pendant les étapes d’évaluation et de planification d’une mise à niveau. Les instructions de mise à niveau personnalisées diffèrent de celles-ci copilot-instructions.md , car elles sont les suivantes :

  • Destiné à automatiser les modifications de code et de dépendance.
  • Récupéré uniquement en cas de pertinence pour l’évaluation ou le plan de mise à niveau actuel.
  • Réutilisable pour différentes solutions lorsqu'il est copié dans chaque référentiel.

Structurez vos fichiers d’instructions avec :

  • Titre court décrivant l’action. Par exemple, « remplacez Newtonsoft.Json par System.Text.Json ».
  • Énoncé du problème concis ou section des prérequis.
  • Logique d’étape explicite (« Si X est trouvé, do Y »). Évitez la langue vague.
  • (Recommandé) Un ou plusieurs exemples de différences capturés à partir de modifications locales réelles pour guider les transformations.

Au-delà des instructions de mise à niveau personnalisées, vous pouvez étendre GitHub Copilot mise à niveau par le biais des compétences et du système d’instructions standard. Les compétences ajoutent des fonctionnalités à l’agent et des fichiers d’instructions (comme copilot-instructions.md) fournissent des conseils globaux.

Créer une instruction de mise à niveau personnalisée

Suivez ces étapes pour générer et affiner un nouveau fichier d’instructions. Ces sections se concentrent sur le remplacement de Newtonsoft.Json par System.Text.Json à titre d'exemple.

Lancer la mise à niveau

Pour démarrer une mise à niveau, procédez comme suit :

  1. Démarrez l’agent à l’aide de l’une des méthodes suivantes :

    • Visual Studio : cliquez avec le bouton droit sur la solution ou le projet dans Explorateur de solutions et sélectionnez Modernize. Vous pouvez également ouvrir la fenêtre gitHub Copilot Chat et taper @Modernize.
    • Visual Studio Code : ouvrez le panneau GitHub Copilot Chat et tapez @upgrade.
    • GitHub Copilot CLI : tapez @upgrade suivi de votre demande de mise à niveau ou de migration.
    • GitHub application Copilot : dans le sélecteur d’agent, sélectionnez Upgrade.

  2. Indiquez à l’agent ce qu’il faut mettre à niveau ou migrer.

Créer le fichier d’instructions

  1. Dans la conversation, tapez : I want to generate a custom upgrade instruction.

  2. Lorsqu'on vous le demande, fournissez un scénario tel que I want to replace Newtonsoft with System.Text.Json pour que Copilot crée le fichier.

  3. Lorsque Copilot crée le nouveau fichier, tel que replace_newtonsoft_with_system_text_json.md, passez en revue le contenu et affinez-le dans la conversation. Par exemple, demandez à Copilot de  » clarifier les critères de détection" ou "ajouter une section requise."

    Tip

    Ajoutez le fichier à la solution pour une visibilité s’il n’est pas déjà inclus.

  4. Renforcer l’instruction avec des exemples réels de différences.

    1. Apportez manuellement les modifications de code souhaitées dans un projet. Par exemple, « supprimez le Newtonsoft.Json package, mettez à jour à l’aide de directives et remplacez JsonConvert le code par JsonSerializer».
    2. Dans la conversation, avec le fichier d’instruction ouvert, tapez : Check my git changes and add diffs as examples to my instruction file.
    3. Veuillez confirmer que Copilot a utilisé un diff git et a ajouté un bloc de diff bordé ou un exemple structuré au fichier Markdown.

Conseils de création

Suivez ces instructions pour écrire des instructions de mise à niveau personnalisée claires et efficaces que Copilot peut interpréter de manière fiable :

  • Utilisez une formulation conditionnelle claire : If code references X, then do Y.
  • Conserver une transformation par fichier ; utilisez les conditions préalables lorsque plusieurs fichiers doivent s’exécuter en séquence.
  • Fournissez au moins un exemple concret, tel qu'un diff ou un extrait de code avant/après, pour améliorer la précision de la transformation.
  • Évitez les verbes ambigus tels que « améliorer » ou « corriger » ; utilisez des actions explicites telles que « replace », « remove » et « update ».

Tester une instruction de mise à niveau personnalisée (exécution unique)

Avant d’exécuter l’instruction pendant une mise à niveau, validez-la en isolation. Les tests isolés vous aident à affiner la détection et à vérifier les modifications du code.

Lancer la mise à niveau

Pour démarrer une mise à niveau, procédez comme suit :

  1. Démarrez l’agent à l’aide de l’une des méthodes suivantes :

    • Visual Studio : cliquez avec le bouton droit sur la solution ou le projet dans Explorateur de solutions et sélectionnez Modernize. Vous pouvez également ouvrir la fenêtre gitHub Copilot Chat et taper @Modernize.
    • Visual Studio Code : ouvrez le panneau GitHub Copilot Chat et tapez @upgrade.
    • GitHub Copilot CLI : tapez @upgrade suivi de votre demande de mise à niveau ou de migration.
    • GitHub application Copilot : dans le sélecteur d’agent, sélectionnez Upgrade.

  2. Indiquez à l’agent ce qu’il faut mettre à niveau ou migrer.

Tester l’instruction de mise à niveau

  1. Dans la conversation, appelez l’instruction avec une formulation similaire au nom de fichier. Par exemple : replace Newtonsoft with System.Text.Json.

  2. Confirmez dans la fenêtre de conversation que Copilot a récupéré le fichier d’instructions :

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

    Si Copilot n'indique pas qu'elle a trouvé les instructions, réessayez avec des mots clés du nom du fichier, tels que le même verbe et les combinaisons de noms.

  3. Passez en revue les modifications proposées (différences de solution, validations en attente ou modifications en préversion) pour confirmer que l’instruction de mise à niveau personnalisée se comporte comme prévu.

Conseils de validation

Si l’exécution du test ne produit pas les résultats attendus, utilisez ces conseils de dépannage pour affiner votre fichier d’instructions :

  • Si Copilot met uniquement à jour les versions du package au lieu de remplacer le package, assurez-vous que l’instruction indique explicitement de supprimer ou de remplacer l’ancien package.
  • Utilisez une nomination cohérente afin que l'activation en langage naturel corresponde. Par exemple, démarrez le nom du fichier avec replace_ et commencez votre demande de conversation par « Remplacer... ».
  • Pendant le test, ajoutez des modèles de code manquants en tant qu’exemples pour améliorer la couverture.

Appliquer des instructions personnalisées pendant une mise à niveau

Utilisez ces étapes pour incorporer une instruction de mise à niveau personnalisée existante dans la phase d’évaluation d’une mise à niveau.

Lancer la mise à niveau

Pour démarrer la mise à niveau, procédez comme suit :

  1. Démarrez l’agent à l’aide de l’une des méthodes suivantes :

    • Visual Studio : cliquez avec le bouton droit sur la solution ou le projet dans Explorateur de solutions et sélectionnez Modernize. Vous pouvez également ouvrir la fenêtre gitHub Copilot Chat et taper @Modernize.
    • Visual Studio Code : ouvrez le panneau GitHub Copilot Chat et tapez @upgrade.
    • GitHub Copilot CLI : tapez @upgrade suivi de votre demande de mise à niveau ou de migration.
    • GitHub application Copilot : dans le sélecteur d’agent, sélectionnez Upgrade.

  2. Indiquez à l’agent ce qu’il faut mettre à niveau ou migrer.

Personnaliser la mise à niveau

Suivez ces étapes pendant la phase d’évaluation :

  1. Surveillez la conversation pour voir si Copilot récupère automatiquement votre fichier d’instructions personnalisé pendant l’évaluation. Recherchez un message indiquant qu’il a ouvert le fichier d’instructions Markdown.

    Si Copilot n'applique pas automatiquement les instructions personnalisées, demandez-les explicitement. Utilisez une formulation similaire au nom du fichier. Par exemple : use the custom instructions to replace Newtonsoft with System.Text.Json during the assessment.

  2. Attendez Copilot pour confirmer qu’elle a récupéré le fichier Markdown. Si vous ne voyez pas de référence au fichier d’instructions, reformulez la demande en utilisant les verbes clés du fichier (remplacer, mettre à jour, supprimer) et les noms des paquets.

  3. Passez en revue le fichier généré assessment.md dans le .github/upgrades dossier. Vérifiez que l’évaluation comprend des problèmes et des modifications identifiés par votre instruction personnalisée.

    Par exemple, lors du remplacement de Newtonsoft, l’évaluation identifie :

    • Projets utilisant Newtonsoft.Json packages.
    • Modèles de code à refactoriser pour System.Text.Json.
    • Dépendances à supprimer ou remplacer.

  4. Si nécessaire, modifiez le assessment.md fichier pour ajouter un contexte ou ajuster les problèmes identifiés avant de continuer.

  5. Demandez à Copilot de passer à l’étape de planification une fois que l’évaluation reflète votre instruction personnalisée.

  6. Passez en revue le fichier plan.md généré par Copilot. Ce fichier inclut des stratégies pour résoudre les problèmes de l’évaluation.

  7. Passez à l’étape d’exécution en indiquant à Copilot de continuer. Surveillez le fichier tasks.md, car Copilot applique les transformations.

Conseils pour une meilleure activation

La façon dont vous nommez et appelez des instructions de mise à niveau personnalisées affecte si Copilot les récupère automatiquement. Suivez ces instructions pour améliorer la fiabilité de l’activation :

  • Correspond au verbe du fichier. Si le nom de fichier utilise replace, utilisez cette formulation (pas upgrade ou fix).
  • Conservez une transformation par fichier pour la clarté et la réutilisation. Séquencez plusieurs fichiers en répertoriant les prérequis dans chaque fichier.
  • Demandez des instructions personnalisées pendant la phase d’évaluation pour obtenir les meilleurs résultats, plutôt que d’attendre la planification ou l’exécution.
  • Évitez les demandes ambiguës telles que « améliorer l’évaluation ». Soyez explicite : « appliquez les instructions replace_newtonsoft_with_system_text_json lors de l’évaluation ».

Valider les modifications appliquées

Une fois la mise à niveau terminée :

  1. Passez en revue le fichier tasks.md dans .github/upgrades pour voir l'état des tâches liées à votre instruction personnalisée.
  2. Vérifiez les validations Git créées pendant la phase d’exécution pour connaître les modifications liées à l’instruction personnalisée.
  3. Exécutez vos tests pour vous assurer que le comportement fonctionnel reste correct.
  4. Facultatif : Capturez un exemple de différences à partir de la modification réussie et ajoutez-le au fichier d’instructions pour renforcer l’automatisation future.

Nettoyer les ressources

Supprimez ou consolidez les fichiers d’instructions temporaires pour éviter les transformations qui se chevauchent dans les mises à niveau ultérieures.

Contenu connexe

  • Last updated on