Freigeben über

Anwenden von benutzerdefinierten Upgradeanweisungen für .NET Upgrades

Benutzerdefinierte Upgrade-Anweisungen sind Markdown-Dateien, die die Modernisierung von GitHub Copilot anleiten, um während eines Upgrades bestimmte Transformationen anzuwenden. Erstellen Sie diese Dateien, um sich wiederholende Änderungen zu automatisieren, z. B. das Ersetzen einer Bibliothek durch eine andere oder das Anwenden eines bestimmten API-Upgrades.

In diesem Artikel wird erläutert, wie Sie eine benutzerdefinierte Upgradeanweisungsdatei erstellen und strukturieren, sie isoliert testen und in die Bewertungsphase eines Upgradeworkflows integrieren.

Voraussetzungen

Richten Sie GitHub Copilot Modernisierung in Ihrer Entwicklungsumgebung ein, bevor Sie benutzerdefinierte Anweisungen erstellen. Installationsschritte finden Sie unter Installieren GitHub Copilot Modernisierung.

Verstehen Sie benutzerdefinierte Anweisungen zum Upgrade

Der GitHub Copilot Modernisierungsprozess holt bei Bedarf benutzerdefinierte Upgradeanweisungen als Markdown-Dateien während der Bewertungs- und Planungsphase eines Upgrades ab. Benutzerdefinierte Upgrade-Anweisungen unterscheiden sich von copilot-instructions.md in folgenden Punkten:

  • Gezielt auf die Automatisierung von Code- und Abhängigkeitsänderungen.
  • Wird nur abgerufen, wenn es für die aktuelle Upgradebewertung oder den aktuellen Plan relevant ist.
  • Wiederverwendbar über Lösungen hinweg, wenn in jedes Repository kopiert.

Strukturieren Sie Ihre Anweisungsdateien mit:

  • Ein kurzer Titel, der die Aktion beschreibt. Beispiel: "Newtonsoft.Json durch System.Text.Json ersetzen"
  • Eine präzise Problemausweisung oder ein abschnitt mit Voraussetzungen.
  • Explizite Schrittlogik ("Wenn X gefunden wird, do Y"). Vermeiden Sie vage Sprache.
  • (Empfohlen) Ein oder mehrere Diff-Beispiele, die aus tatsächlichen lokalen Bearbeitungen erfasst wurden, als Leitfaden für Transformationen.

Über benutzerdefinierte Upgrade-Anweisungen hinaus können Sie die Modernisierung von GitHub Copilot durch das System der Standardfähigkeiten und Anweisungen erweitern. Fähigkeiten fügen dem Agenten Funktionen hinzu, und Anleitungsdateien (wie copilot-instructions.md) bieten globale Anleitung.

Erstellen einer benutzerdefinierten Upgradeanweisung

Führen Sie die folgenden Schritte aus, um eine neue Anweisungsdatei zu generieren und zu verfeinern. Diese Abschnitte konzentrieren sich darauf, Newtonsoft.Json durch System.Text.Json zu ersetzen, als Beispiel.

  1. Klicken Sie im Fenster Projektmappen-Explorer mit der rechten Maustaste auf die solution>Modernize.

    - oder -

    Öffnen Sie den Copilot Chatbereich, und geben Sie @Modernize ein, um eine Unterhaltung mit dem Agent zu beginnen.

    Hinweis

    Diese Schritte gelten für Visual Studio. Rufen Sie in Visual Studio Code und anderen Umgebungen den modernize-dotnet-Agent direkt über den Copilot-Chatbereich auf. In Visual Studio heißt der Agent Modernize.

  2. Geben Sie im Chat Folgendes ein: I want to generate a custom upgrade instruction.

  3. Wenn Sie gefragt werden, geben Sie ein Szenario wie I want to replace Newtonsoft with System.Text.Json an, damit Copilot die Datei erstellt.

  4. Wenn Copilot die neue Datei erstellt, z. B. replace_newtonsoft_with_system_text_json.md, überprüfen Sie den Inhalt, und verfeinern Sie sie im Chat. Bitte fragen Sie z. B. Copilot, "Erkennungskriterien klarzustellen" oder "einen Abschnitt über Voraussetzungen hinzuzufügen."

    Tipp

    Fügen Sie die Datei zur Sichtbarkeit hinzu, wenn sie noch nicht enthalten ist.

  5. Stärken Sie die Anweisung mit echten Diff-Beispielen.

    1. Nehmen Sie die gewünschten Codeänderungen manuell in einem Projekt vor. Beispiel: "Entfernen Sie das Newtonsoft.Json Paket, aktualisieren Sie das Paket mithilfe von Direktiven, und ersetzen Sie JsonConvert Code durch JsonSerializer."
    2. Geben Sie im Chat mit geöffneter Anweisungsdatei Folgendes ein: Check my git changes and add diffs as examples to my instruction file.
    3. Bestätigen Sie, Copilot einen Git-Diff verwendet und einen eingezäunten Diff-Block oder ein strukturiertes Beispiel an die Markdown-Datei angefügt hat.

Tipps zur Inhaltserstellung

Befolgen Sie diese Richtlinien, um klare, effektive benutzerdefinierte Upgradeanweisungen zu schreiben, die Copilot zuverlässig interpretieren können:

  • Verwenden Sie klare bedingte Ausdrücke: If code references X, then do Y.
  • Behalten Sie eine Transformation pro Datei bei; Verwenden Sie voraussetzungen, wenn mehrere Dateien in Sequenz ausgeführt werden müssen.
  • Stellen Sie mindestens ein konkretes Beispiel bereit, z. B. einen Diff- oder Before/After-Codeausschnitt, um die Transformationsgenauigkeit zu verbessern.
  • Vermeiden Sie mehrdeutige Verben wie "verbessern" oder "korrigieren"; Verwenden Sie explizite Aktionen wie "Ersetzen", "Entfernen" und "Aktualisieren".

Testen einer benutzerdefinierten Upgradeanweisung (einmalige Ausführung)

Bevor Sie die Anweisung während eines Upgrades ausführen, überprüfen Sie sie isoliert. Isolierte Tests helfen Ihnen, die Erkennung zu verfeinern und Codeänderungen zu überprüfen.

  1. Klicken Sie im Fenster Projektmappen-Explorer mit der rechten Maustaste auf die solution>Modernize.

    Hinweis

    Diese Schritte gelten für Visual Studio. Rufen Sie in Visual Studio Code und anderen Umgebungen den modernize-dotnet-Agent direkt über den Copilot-Chatbereich auf.

  2. Rufen Sie im Chat die Anweisung mit einer Wortwahl ähnlich dem Dateinamen auf. Beispiel: replace Newtonsoft with System.Text.Json.

  3. Bestätigen Sie im Chatfenster, dass Copilot die Anweisungsdatei abgerufen hat:

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

    Wenn Copilot nicht angibt, dass sie die Anweisungen gefunden hat, versuchen Sie es erneut mit Schlüsselwörtern aus dem Namen der Datei, z. B. dasselbe Verb und die gleichen Substantivkombinationen.

  4. Überprüfen Sie die vorgeschlagenen Änderungen (Lösungs-Diffs, ausstehende Commits oder vorgesehene Änderungen), um sicherzustellen, dass sich die benutzerdefinierte Upgrade-Anweisung wie erwartet verhält.

Überprüfungstipps

Wenn die Testausführung nicht zu den erwarteten Ergebnissen führt, verwenden Sie diese Tipps zur Problembehandlung, um Ihre Anweisungsdatei zu verfeinern:

  • Wenn Copilot nur Paketversionen aktualisiert, anstatt das Paket zu ersetzen, stellen Sie sicher, dass die Anweisung explizit angibt, das alte Paket zu entfernen oder zu ersetzen.
  • Verwenden Sie eine konsistente Benennung, sodass die Aktivierung in natürlicher Sprache übereinstimmt. Starten Sie z. B. den Dateinamen mit replace_ und beginnen Sie mit Ihrer Chatanfrage mit "Ersetzen ...".
  • Fügen Sie während des Tests fehlende Codemuster als Beispiele hinzu, um die Abdeckung zu verbessern.

Anwenden von benutzerdefinierten Anweisungen während eines Upgrades

Führen Sie diese Schritte aus, um eine vorhandene benutzerdefinierte Upgradeanweisung in die Bewertungsphase eines Upgrades zu integrieren.

  1. Klicken Sie im Fenster Projektmappen-Explorer mit der rechten Maustaste auf die solution>Modernize.

    Hinweis

    Diese Schritte gelten für Visual Studio. Rufen Sie in Visual Studio Code und anderen Umgebungen den modernize-dotnet-Agent direkt über den Copilot-Chatbereich auf.

  2. Wählen Sie im Chat Upgrade to a newer version of .NET aus. Beantworten Sie die Fragen des Copiloten, bis er mit der Bewertung beginnt.

  3. Überwachen Sie den Chat, um festzustellen, ob Copilot Ihre benutzerdefinierte Anweisungsdatei während der Bewertung automatisch abruft. Suchen Sie nach einer Nachricht, die angibt, dass sie die Markdown-Anweisungsdatei geöffnet hat.

    Wenn Copilot die benutzerdefinierten Anweisungen nicht automatisch anwendet, fordern Sie sie explizit an. Verwenden Sie die Formulierung ähnlich dem Dateinamen. Beispiel: use the custom instructions to replace Newtonsoft with System.Text.Json during the assessment.

  4. Warten Sie, bis Copilot die Markdown-Datei abgerufen hat. Wenn kein Verweis auf die Anweisungsdatei angezeigt wird, sollten Sie die Anforderung mit den Schlüsselverben der Datei (Ersetzen, Aktualisieren, Entfernen) und Paketnamen erneut aufrufen.

  5. Überprüfen Sie die generierte assessment.md Datei im .github/upgrades Ordner. Bestätigen Sie, dass die Bewertung Probleme und Änderungen enthält, die ihre benutzerdefinierte Anweisung identifiziert hat.

    Beim Ersetzen von Newtonsoft identifiziert die Bewertung beispielsweise Folgendes:

    • Projekte, die Newtonsoft.Json Pakete verwenden.
    • Codemuster zum Umgestalten für System.Text.Json.
    • Abhängigkeiten, die entfernt oder ersetzt werden sollen.

  6. Bearbeiten Sie bei Bedarf die assessment.md Datei, um Kontext hinzuzufügen oder die identifizierten Probleme anzupassen, bevor Sie fortfahren.

  7. Sagen Sie Copilot, dass es zur Planungsphase weitergeht, sobald die Bewertung Ihre benutzerdefinierte Anweisung widerspiegelt.

  8. Überprüfen Sie die plan.md Datei, die Copilot generiert. Diese Datei enthält Strategien zur Behandlung der Probleme aus der Bewertung.

  9. Fahren Sie mit der Ausführungsphase fort, indem Sie Copilot mitteilen, den Vorgang fortzusetzen. Überwachen Sie die Datei tasks.md, da Copilot die Transformationen anwendet.

Tipps für eine bessere Aktivierung

Wie Sie benutzerdefinierte Upgrade-Anweisungen benennen und aufrufen, beeinflusst, ob Copilot diese automatisch abruft. Befolgen Sie die folgenden Richtlinien, um die Zuverlässigkeit der Aktivierung zu verbessern:

  • Vergleichen Sie das Verb der Datei. Wenn der Dateiname replace verwendet wird, nutzen Sie diese Formulierung (nicht upgrade oder fix).
  • Behalten Sie eine Transformation pro Datei für Klarheit und Wiederverwendung bei. Mehrere Dateien sequenzieren, indem Sie die Voraussetzungen in jeder Datei auflisten.
  • Fordern Sie während der Bewertungsphase benutzerdefinierte Anweisungen an, um optimale Ergebnisse zu erzielen, anstatt bis zur Planung oder Ausführung zu warten.
  • Vermeiden Sie mehrdeutige Anforderungen wie "Verbessern der Bewertung". Seien Sie explizit: "Wenden Sie die replace_newtonsoft_with_system_text_json Anweisungen während der Bewertung an.".

Überprüfen der angewendeten Änderungen

Nach Abschluss des Upgrades:

  1. Überprüfen Sie die tasks.md-Datei in .github/upgrades, um den Status der Aufgaben zu Ihrer benutzerdefinierten Anweisung zu sehen.
  2. Überprüfen Sie die Git-Commits, die während der Ausführungsphase erstellt wurden, auf Änderungen im Zusammenhang mit der benutzerdefinierten Anweisung.
  3. Führen Sie Ihre Tests aus, um sicherzustellen, dass das Funktionsverhalten korrekt bleibt.
  4. Optional: Erfassen Sie ein Diff-Beispiel aus der erfolgreichen Änderung, und fügen Sie es der Anweisungsdatei hinzu, um die zukünftige Automatisierung zu stärken.

Bereinigen von Ressourcen

Entfernen oder konsolidieren Sie temporäre Anweisungsdateien, um überlappende Transformationen in zukünftigen Upgrades zu vermeiden.

Verwandte Inhalte

  • Last updated on