Problembehandlung bei der Modernisierung von GitHub Copilot

In diesem Artikel werden häufig auftretende Probleme behandelt, die bei der Verwendung der GitHub Copilot-Modernisierung für .NET nach Kategorie auftreten können. Jeder Eintrag folgt einem Problem, einer Ursache und einem Lösungsformat, damit Sie Probleme schnell finden und beheben können.

Workflowprobleme

Diese Probleme beziehen sich auf die Szenarioermittlung, das Fortsetzen von Arbeit und den Aufgabenstatus.

Agent sagt "keine Szenarien gefunden"

Cause: Der Agent erkennt den Arbeitsbereich nicht als .NET Projekt.

Lösung:

1. Stellen Sie sicher, dass der Arbeitsbereichsstamm eine .sln, eine .csproj oder eine .vbproj Datei enthält.
2. Fragen Sie den Agenten: "Welche Projektdatei oder Projektmappe verwenden Sie?"
3. Wenn sich Ihre Lösung oder Projektdatei in einem Unterverzeichnis befindet, öffnen Sie dieses Verzeichnis als Stamm des Arbeitsbereichs oder verweisen Sie den Agenten explizit auf die Datei.

Der Agent kann die vorherige Arbeit nicht fortsetzen.

Ursache: Der .github/upgrades/ Ordner, in dem der Agent den gesamten Status speichert, fehlt oder ist beschädigt.

Lösung:

1. Überprüfen Sie, ob der .github/upgrades/ Ordner im Repositorystamm vorhanden ist.
2. Wenn der Ordner versehentlich gelöscht wurde, starten Sie das Szenario neu. Ohne seine Zustandsdateien kann der Agent nicht wiederhergestellt werden.
3. Wenn der Ordner vorhanden ist, aber Dateien beschädigt sind, bitten Sie den Agent, diese neu zu überprüfen und neu zu planen.

Vorgänge, die in Bearbeitung hängen bleiben

Ursache: Die vorherige Sitzung wurde beendet, während der Agent mit der Aufgabe beschäftigt war.

Lösung:

1. Der Agent erkennt veraltete Aufgaben in den meisten Fällen automatisch. Informieren Sie den Agent "fortsetzen" oder "den aktuellen Vorgang neu starten".
2. Wenn der hängen gebliebene Zustand weiterhin besteht, weisen Sie dem Agent an, "die aktuelle Aufgabe als ausstehend zu markieren und neu zu starten" oder "neu zu bewerten und vom letzten abgeschlossenen Schritt fortzusetzen".
3. Überprüfen Sie die entsprechende progress-details.md Datei für die Aufgabe, um zu verstehen, wo die vorherige Sitzung beendet wurde.

Agent schlägt weiterhin das falsche Szenario vor

Ursache: Die Analyse des Agents hat unerwartete Projektmerkmale aufgenommen und ein anderes Szenario als beabsichtigt abgeleitet.

Lösung:

Seien Sie explizit darüber informiert, was Sie wollen. Statt "Mein Projekt aktualisieren", sagen Sie:

• "Ich möchte ein Upgrade auf .NET 10."
• "Ich möchte von Newtonsoft.Json zu System.Text.Json migrieren."
• "Mein Projekt in das SDK-Format konvertieren."

Fügen Sie außerdem Szenariopräferenzen zu scenario-instructions.md hinzu, um zukünftige Konflikte zu verhindern.

Build- und Kompilierungsprobleme

Diese Probleme beziehen sich auf Buildfehler, NuGet-Wiederherstellungsprobleme und Codegenerierungsfehler.

Build schlägt fehl nach Änderungen des Agenten.

Ursache: Upgrades können unterbrechungswidrige API-Änderungen, fehlende Pakete oder inkompatible Codemuster verursachen.

Lösung:

1. Informieren Sie den Agent über den Fehler. Der Agent analysiert die Fehler automatisch.
2. Wenn der Agent das Problem nicht beheben kann, setzen Sie den letzten Commit (git revert HEAD) zurück, und bitten Sie den Agent, einen anderen Ansatz zu versuchen.
3. Überprüfen Sie execution-log.md bei komplexen Fehlern, welche Änderungen der Agent vorgenommen hat und in welcher Reihenfolge.

Fehler bei der NuGet-Wiederherstellung

Ursache: Paketinkompatibilität mit dem Zielframework oder Authentifizierungsfehlern mit privaten NuGet-Feeds.

Lösung:

• Für private Feeds: Authentifizieren Sie sich beim Feed, bevor Sie das Upgrade starten.
• Für inkompatible Pakete: Informieren Sie den Agent, welches Paket problematisch ist. Der Agent kann nach kompatiblen Versionen suchen oder alternative Pakete vorschlagen.
• Bei Problemen mit der Feed-Konnektivität: Überprüfen Sie, ob Sie dotnet restore manuell ausführen können. Beheben Sie zuerst alle Feedprobleme, und lassen Sie den Agent erneut versuchen.

Agent generiert Code, der nicht kompiliert wird

Ursache: KI-generierter Code kann Fehler enthalten, insbesondere in Edgefällen oder mit ungewöhnlichen API-Mustern.

Lösung:

1. Der Agent erkennt Kompilierungsfehler automatisch. Wenn der Agent Probleme hat, stellen Sie Anleitung bereit oder korrigieren Sie den Code manuell und bitten Sie den Agenten, den Vorgang fortzusetzen.
2. Wenn der Agent nach mehreren Versuchen mit einem bestimmten Fix zu kämpfen hat, bearbeiten Sie den Code manuell, und teilen Sie dem Agent mit: "Ich habe den Kompilierungsfehler in MyClass.cs behoben, markieren Sie diese Aufgabe als abgeschlossen".
3. Der Agent lernt von Ihrem manuellen Fix und wendet ähnliche Muster an, wenn dasselbe Problem an anderer Stelle angezeigt wird.

Git-Probleme

Der Agent kann keine Verzweigung erstellen

Ursache: Nicht übernommene Änderungen im Arbeitsbaum, ein Verzweigungsbenennungskonflikt oder Git ist nicht im Arbeitsbereich initialisiert.

Lösung:

1. Führen Sie vor dem Starten eines Szenarios einen Commit durch, oder stashen Sie die ausstehenden Änderungen.
2. Überprüfen Sie, ob Git initialisiert ist: im Arbeitsbereichsstamm git status ausführen.
3. Wenn eine Verzweigung mit dem beabsichtigten Namen des Agents bereits vorhanden ist, löschen Sie die vorhandene Verzweigung, oder bitten Sie den Agent, einen anderen Verzweigungsnamen zu verwenden.

Rückgängigmachen aller Agent-Änderungen

Ursache: Das Upgrade wurde nicht wie geplant durchgeführt, und Sie möchten von vorn beginnen.

Lösung:

1. Wechseln Sie zurück zu Ihrem ursprünglichen Branch: git checkout main (oder was auch immer Ihr Basis-Branch ist).
2. Der Arbeitszweig des Agents enthält alle Änderungen, die von Ihrem Hauptbranch isoliert sind.
3. So entfernen Sie die Zweigstelle des Agents vollständig: git branch -D <agent-branch-name>.
4. Um einige Änderungen beizubehalten, cherry-picken Sie bestimmte Commits: git cherry-pick <commit-hash>.

Leistungsprobleme

Diese Probleme beziehen sich auf die Upgradegeschwindigkeit und die Bewertungsdauer.

Der Agent ist langsam oder nimmt viel Zeit in Anspruch.

Ursache: Große Lösungen mit vielen Projekten, komplexen Abhängigkeitsdiagrammen oder zahlreichen bahnbrechenden Änderungen dauern natürlich länger.

Lösung:

Für sehr große Lösungen (50+ Projekte) sollten Sie ein Upgrade in Batches in Betracht ziehen. Gruppieren Sie verwandte Projekte, und aktualisieren Sie sie zusammen.

Die Bewertung dauert sehr lange.

Ursache: Die Bewertung analysiert die Abhängigkeiten jedes Projekts, NuGet-Pakete, Ziel-Frameworks und anwendbare Änderungen. Bei großen Lösungen dauert die Bewertung natürlich länger.

Lösung:

1. Lange Bewertungszeiten sind für große Lösungen normal. Es ist keine Aktion erforderlich.
2. Überwachen des Fortschritts im OutputBereich (wählen Sie AppModernizationExtension aus der Dropdownliste in Visual Studio aus).
3. Die Bewertung wird nur einmal pro Szenario ausgeführt. In nachfolgenden Phasen werden die zwischengespeicherten Ergebnisse verwendet.

Anpassungsprobleme

Diese Probleme beziehen sich auf benutzerdefinierte Fähigkeiten und Szenario-Anweisungsdateien.

Benutzerdefinierte Fähigkeiten werden nicht erkannt.

Ursache: Die Qualifikationsdatei befindet sich an dem falschen Speicherort oder hat fehlende oder ungültige Metadaten, oder das Qualifikationsformat ist falsch.

Lösung:

1. Überprüfen Sie, ob sich die Qualifikationsdatei an einem der unterstützten Speicherorte befindet:
   • .github/skills/ (Repository-Ebene, teamweit)
   • .github/upgrades/skills/ (Szenarioebene)
   • %UserProfile%/.copilot/skills/ (Nutzerebene, persönlich)
2. Überprüfen Sie, ob die Qualifikationsmetadaten mindestens name und description Felder enthalten.
3. Stellen Sie sicher, dass das discovery-Feld (falls festgelegt) eines von lazy, preload oder scenario ist.
4. Überprüfen Sie, ob die Fähigkeiten description mit der Art der Aufgabe übereinstimmen, auf die sie angewendet werden soll. Der Agent verwendet den Beschreibungsabgleich, um Fähigkeiten auszuwählen.

Änderungen an scenario-instructions.md werden nicht wirksam

Ursache: Der Agent liest die Datei möglicherweise nicht während der Sitzung neu, oder Ihre Bearbeitungen befinden sich im falschen Abschnitt.

Lösung:

1. Bitten Sie den Agenten, die "Anweisungen neu zu laden" oder eine neue Chatsitzung zu starten, um ein erneutes Lesen zu erzwingen.
2. Stellen Sie sicher, dass sich Ihre Bearbeitungen in den richtigen Abschnitten der Datei befinden:
   • Benutzereinstellungen: Für allgemeine Einstellungen und Einschränkungen.
   • Wichtige Entscheidungen: Zum Aufzeichnen wichtiger Entscheidungen, die während des Upgrades getroffen wurden.
   • Benutzerdefinierte Anweisungen: Für spezifische Verhaltensanpassungen.
3. Überprüfen Sie, ob die Datei gespeichert ist und im erwarteten Pfad: .github/upgrades/{scenarioId}/scenario-instructions.md.

Hilfe erhalten

Wenn etwas nicht wie erwartet funktioniert:

1. Fragen Sie den Agenten: Fragen Sie "Was hat mit der letzten Aufgabe nicht geklappt?" Der Agent kann häufig erklären, was passiert ist und nächste Schritte vorschlagen.
2. Überprüfen Sie das Ausführungsprotokoll: Öffnen execution-log.md in .github/upgrades/{scenarioId}/. Das Protokoll zeigt einen chronologischen Datensatz der Aktionen des Agents, einschließlich aller Fehler, die der Agent festgestellt hat.
3. Ein Problem melden: Wenn Sie einen Fehler gefunden haben oder der Agent bei etwas ständig versagt, melden Sie bitte ein Problem im @modernize-dotnet GitHub-Repository.

Verwandte Inhalte

• Was ist die Modernisierung von GitHub Copilot?
• Bewährte Methoden
• Kernkonzepte
• GitHub Copilot FAQ zur Modernisierung