Anwenden von benutzerdefinierten Upgradeanweisungen für .NET-Upgrades

Benutzerdefinierte Upgradeanweisungen sind Markdown-Dateien, die GitHub Copilot Upgrade zur Anwendung bestimmter Transformationen während eines Upgrades führen. 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 Upgrade in Ihrer Entwicklungsumgebung ein, bevor Sie benutzerdefinierte Anweisungen erstellen. Installationsschritte finden Sie unter Installieren GitHub Copilot Upgrades.

Verstehen Sie benutzerdefinierte Anweisungen zum Upgrade

GitHub Copilot Upgrade ruft benutzerdefinierte Upgradeanweisungen als Markdown-Dateien bei Bedarf 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 Upgradeanweisungen hinaus können Sie GitHub Copilot Upgrade über das Standardfertigkeiten- und Anleitungssystem 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.

Starten des Upgrades

Führen Sie die folgenden Schritte aus, um ein Upgrade zu starten:

  1. Starten Sie den Agent mit einer der folgenden Methoden:

    • Visual Studio: Klicken Sie mit der rechten Maustaste auf die Lösung oder das Projekt im Projektmappen-Explorer und wählen Sie Modernize aus. Öffnen Sie alternativ das GitHub-Copilot Chat-Fenster, und geben Sie folgendes ein@Modernize.
    • Visual Studio Code: Öffnen Sie den Bereich GitHub Copilot Chat, und geben Sie @upgrade ein.
    • GitHub Copilot CLI: Geben Sie @upgrade gefolgt von Ihrer Upgrade- oder Migrationsanforderung ein.
    • GitHub-App Copilot: Wählen Sie in der Agentauswahl die Option Upgradeaus.

  2. Informieren Sie den Agent, was aktualisiert oder migriert werden soll.

Erstellen der Anweisungsdatei

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

  2. Wenn du gefragt wirst, gib ein Szenario wie I want to replace Newtonsoft with System.Text.Json an, damit Copilot die Datei erstellt.

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

    Tip

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

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

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

Starten des Upgrades

Führen Sie die folgenden Schritte aus, um ein Upgrade zu starten:

  1. Starten Sie den Agent mit einer der folgenden Methoden:

    • Visual Studio: Klicken Sie mit der rechten Maustaste auf die Lösung oder das Projekt im Projektmappen-Explorer und wählen Sie Modernize aus. Öffnen Sie alternativ das GitHub-Copilot Chat-Fenster, und geben Sie folgendes ein@Modernize.
    • Visual Studio Code: Öffnen Sie den Bereich GitHub Copilot Chat, und geben Sie @upgrade ein.
    • GitHub Copilot CLI: Geben Sie @upgrade gefolgt von Ihrer Upgrade- oder Migrationsanforderung ein.
    • GitHub-App Copilot: Wählen Sie in der Agentauswahl die Option Upgradeaus.

  2. Informieren Sie den Agent, was aktualisiert oder migriert werden soll.

Testen Sie die Anleitung zum Upgrade

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

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

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

Starten des Upgrades

Führen Sie die folgenden Schritte aus, um das Upgrade zu starten:

  1. Starten Sie den Agent mit einer der folgenden Methoden:

    • Visual Studio: Klicken Sie mit der rechten Maustaste auf die Lösung oder das Projekt im Projektmappen-Explorer und wählen Sie Modernize aus. Öffnen Sie alternativ das GitHub-Copilot Chat-Fenster, und geben Sie folgendes ein@Modernize.
    • Visual Studio Code: Öffnen Sie den Bereich GitHub Copilot Chat, und geben Sie @upgrade ein.
    • GitHub Copilot CLI: Geben Sie @upgrade gefolgt von Ihrer Upgrade- oder Migrationsanforderung ein.
    • GitHub-App Copilot: Wählen Sie in der Agentauswahl die Option Upgradeaus.

  2. Informieren Sie den Agent, was aktualisiert oder migriert werden soll.

Anpassen des Upgrades

Führen Sie die folgenden Schritte während der Bewertungsphase aus:

  1. Überwachen Sie den Chat, um festzustellen, ob Copilot während der Beurteilung automatisch Ihre benutzerdefinierte Anweisungsdatei 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

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

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

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

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

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

  7. Fahren Sie mit der Ausführungsphase fort, indem Sie Copilot anweisen, fortzufahren. Überwachen Sie die tasks.md Datei, während Copilot die Transformationen anwendet.

Tipps für eine bessere Aktivierung

Wie benutzerdefinierte Aktualisierungsanweisungen benannt und aufgerufen werden, beeinflusst, ob Copilot sie 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