Résoudre les problèmes liés à la modernisation de GitHub Copilot

Cet article traite des problèmes courants que vous pouvez rencontrer lorsque vous utilisez GitHub Copilot modernisation pour .NET, organisé par catégorie. Chaque entrée suit un problème, une cause et un format de solution pour vous permettre de trouver et de résoudre rapidement les problèmes.

Problèmes de flux de travail

Ces problèmes concernent la découverte de scénarios, la reprise du travail et l’état des tâches.

L’agent indique « aucun scénario trouvé »

Cause : L'agent ne reconnaît pas l'espace de travail en tant que projet .NET.

Solution:

1. Vérifiez que la racine de l’espace de travail contient un fichier .sln, .csproj, ou .vbproj.
2. Demandez à l’agent : « Quelle solution ou fichier projet utilisez-vous ? »
3. Si votre solution ou fichier projet se trouve dans un sous-répertoire, ouvrez ce répertoire en tant que racine de l’espace de travail ou pointez l’agent vers le fichier explicitement.

L’agent ne peut pas reprendre le travail précédent

Cause : Le .github/upgrades/ dossier, où l’agent stocke tout son état, est manquant ou endommagé.

Solution:

1. Vérifiez si le .github/upgrades/ dossier existe dans votre racine de dépôt.
2. Si vous avez accidentellement supprimé le dossier, démarrez le scénario à nouveau. L’agent ne peut pas récupérer sans ses fichiers d’état.
3. Si le dossier existe mais que les fichiers apparaissent endommagés, demandez à l’agent de « réévaluer et de re-planifier » de les régénérer.

Tâches bloquées en cours

Cause : La session précédente s’est terminée alors que l’agent était à mi-tâche.

Solution:

1. L’agent détecte automatiquement les tâches obsolètes dans la plupart des cas. Indiquez à l’agent « reprendre » ou « redémarrer la tâche actuelle ».
2. Si l’état bloqué persiste, indiquez à l’agent « marquer la tâche actuelle comme étant en attente et redémarrée » ou « réévaluer et continuer à partir de la dernière étape terminée ».
3. Vérifiez le fichier correspondant progress-details.md pour comprendre où la session précédente s’est arrêtée.

Agent continue de suggérer le mauvais scénario

Cause : L’analyse de l’agent a récupéré des caractéristiques de projet inattendues et déduit un scénario différent de celui prévu.

Solution:

Soyez explicite sur ce que vous voulez. Au lieu de « mettre à niveau mon projet », dites :

• « Je veux effectuer une mise à niveau vers .NET 10.
• « Je souhaite effectuer une mise à niveau de Newtonsoft.Json vers System.Text.Json. »
• « Convertir mon projet en format de style SDK ».

Ajoutez des préférences de scénario à scenario-instructions.md pour empêcher les incompatibilités futures.

Problèmes de génération et de compilation

Ces problèmes concernent les échecs de génération, les problèmes de restauration NuGet et les erreurs de génération de code.

La compilation échoue après les modifications de l’agent

Cause : Les mises à niveau peuvent introduire des modifications d’API qui ne sont pas compatibles, des paquets manquants ou des patrons de code incompatibles.

Solution:

1. Indiquez à l’agent l’échec. L’agent analyse automatiquement les erreurs.
2. Si l’agent ne peut pas résoudre le problème, rétablissez la dernière validation (git revert HEAD) et demandez à l’agent d’essayer une autre approche.
3. En cas d’échec complexe, consultez le fichier execution-log.md pour comprendre quelles modifications l’agent a apportées et dans quel ordre.

Échec de la restauration NuGet

Cause : Incompatibilité de package avec l’infrastructure cible ou les échecs d’authentification avec des flux NuGet privés.

Solution:

• Pour les flux privés : Authentifiez-vous auprès du flux avant de commencer la mise à niveau.
• Pour les packages incompatibles : Indiquez à l’agent quel package est problématique. L’agent peut rechercher des versions compatibles ou suggérer d’autres packages.
• Pour les problèmes de connectivité de flux : Vérifiez que vous pouvez exécuter dotnet restore manuellement. Corrigez d’abord les problèmes de flux, puis laissez l’agent réessayer.

L’agent génère du code qui ne se compile pas

Cause : Le code généré par l’IA peut contenir des erreurs, en particulier dans des cas de périphérie ou avec des modèles d’API rares.

Solution:

1. L’agent détecte automatiquement les erreurs de compilation. Si l’agent rencontre des difficultés, fournissez des conseils ou corrigez le code manuellement et indiquez à l’agent de continuer.
2. Si l’agent rencontre un problème spécifique après plusieurs tentatives, modifiez le code manuellement et indiquez à l’agent : « J’ai résolu l’erreur de compilation dans MyClass.cs, marquez cette tâche comme terminée ».
3. L’agent apprend à partir de votre correctif manuel et applique des modèles similaires lorsque le même problème apparaît ailleurs.

Problèmes Git

L’agent ne peut pas créer de branche

Cause : Il y a des modifications non validées dans l’arborescence de travail, un conflit de nommage de branche, ou Git ne peut être initialisé dans l’espace de travail.

Solution:

1. Validez ou mettez en attente vos modifications avant de lancer un scénario.
2. Vérifiez que Git est initialisé en exécutant git status dans la racine de l’espace de travail.
3. Si une branche portant le nom prévu de l’agent existe déjà, supprimez la branche existante ou demandez à l’agent d’utiliser un autre nom de branche.

Annuler toutes les modifications de l’agent

Cause : La mise à niveau n’a pas été prévue et vous souhaitez recommencer.

Solution:

1. Revenez à votre branche d’origine avec git checkout main (ou votre branche de base).
2. La branche de travail de l’agent contient toutes les modifications séparées de votre branche principale.
3. Pour supprimer entièrement la branche de l’agent, exécutez git branch -D <agent-branch-name>.
4. Pour conserver certaines modifications, utilisez git cherry-pick <commit-hash> afin de sélectionner des commits spécifiques.

Problèmes de performance

Ces problèmes concernent la vitesse de mise à niveau et la durée d’évaluation.

L’agent est lent ou prend beaucoup de temps

Cause : de grandes solutions avec de nombreux projets, des graphes de dépendance complexes ou de nombreuses modifications cassantes prennent naturellement plus de temps.

Solution:

Pour les solutions volumineuses (50 projets), envisagez de procéder à une mise à niveau par lots. Regroupez les projets associés et mettez-les à niveau ensemble.

L’évaluation prend beaucoup de temps

Cause : l’évaluation analyse les dépendances de chaque projet, les packages NuGet, les frameworks cibles et les changements cassants applicables. Pour les grandes solutions, l’évaluation prend naturellement plus de temps.

Solution:

1. Les temps d’évaluation longs sont normaux pour les grandes solutions. Aucune action n’est nécessaire.
2. Surveillez la progression dans le panneau Output (sélectionnez AppModernizationExtension dans la liste déroulante dans Visual Studio).
3. L’évaluation ne s’exécute qu’une seule fois par scénario. Les phases suivantes utilisent les résultats mis en cache.

Problèmes de personnalisation

Ces problèmes concernent les compétences personnalisées et les fichiers d’instructions de scénario.

La compétence personnalisée n’est pas détectée

Cause : Le fichier de compétence se trouve à un emplacement incorrect, a des métadonnées manquantes ou non valides ou a un format incorrect.

Solution:

1. Vérifiez que le fichier de compétence se trouve dans l’un des emplacements pris en charge :
   • .github/skills/ (niveau du référentiel, à l’échelle de l’équipe)
   • .github/upgrades/skills/ (niveau scénario)
   • %UserProfile%/.copilot/skills/ (niveau utilisateur, personnel)
2. Vérifiez que les métadonnées de compétence incluent au moins les champs name et description.
3. Vérifiez que le discovery champ (si défini) est l’un des éléments suivants : lazy, preloadou scenario.
4. Vérifiez que les compétences description correspondent au type de tâche auquel vous vous attendez qu’elle s’applique. L’agent utilise la description correspondante pour sélectionner des compétences.

Les modifications apportées à scenario-instructions.md ne prennent pas effet

Cause : L’agent peut ne pas relire le fichier midsession, ou vos modifications se trouvent dans la mauvaise section.

Solution:

1. Demandez à l’agent de « recharger les instructions » ou de démarrer une nouvelle session de conversation pour forcer une relecture.
2. Vérifiez que vos modifications se trouvent dans les sections correctes du fichier :
   • Préférences utilisateur : Pour les préférences générales et les contraintes.
   • Décisions clés : Pour enregistrer les décisions importantes prises pendant la mise à niveau.
   • Instructions personnalisées : Pour les remplacements comportementaux spécifiques.
3. Vérifiez que le fichier est enregistré et dans le chemin attendu : .github/upgrades/{scenarioId}/scenario-instructions.md.

Obtenir de l’aide

Lorsque quelque chose ne fonctionne pas comme prévu :

1. Demandez à l’agent : Demandez « Qu’est-ce qui s’est passé avec la dernière tâche ? » L’agent peut souvent expliquer ce qui s’est passé et suggérer les étapes suivantes.
2. Passez en revue le journal d’exécution : Ouvrir execution-log.md dans .github/upgrades/{scenarioId}/. Le journal affiche un enregistrement chronologique de ce que l’agent a fait, y compris les erreurs qu’il a rencontrées.
3. Fichier un problème : Si vous avez trouvé un bogue ou que l'agent échoue constamment à quelque chose, faites un problème dans le référentiel @modernize-dotnet GitHub.

Contenu connexe

• Quelle est la modernisation GitHub Copilot ?
• Bonnes pratiques
• Concepts de base
• FAQ sur la modernisation de GitHub Copilot