.NET アップグレードにカスタム アップグレード手順を適用する

カスタムアップグレード手順は、GitHub Copilotの最新化をガイドし、アップグレード中に特定の変換を適用するMarkdownファイルです。 これらのファイルを作成して、あるライブラリを別のライブラリに置き換えたり、特定の API アップグレードを適用したりするなど、繰り返し行う変更を自動化します。

この記事では、カスタム アップグレード命令ファイルを作成して構造化し、分離してテストし、アップグレード ワークフローの評価ステージに統合する方法について説明します。

[前提条件]

カスタム命令を作成する前に、開発環境でGitHub Copilotモダン化を設定します。 インストール手順については、「GitHub Copilot モダン化のインストール」を参照してください。

カスタム アップグレード手順を理解する

GitHub Copilotモダン化では、アップグレードの評価と計画の段階で、カスタム アップグレード手順が Markdown ファイルとしてオンデマンドで取得されます。 カスタム アップグレード手順は copilot-instructions.md とは異なります。

  • コードと依存関係の変更の自動化を対象とします。
  • 現在のアップグレード評価またはプランに関連する場合にのみ取得されます。
  • 各リポジトリにコピーすると、ソリューション間で再利用できます。

次を使用して命令ファイルを構成します。

  • アクションを説明する短いタイトル。 たとえば、"Newtonsoft.Json を System.Text.Json に置き換える" とします。
  • 簡潔な問題ステートメントまたは前提条件セクション。
  • 明示的なステップ ロジック ("X が見つかった場合は Y を実行")。 あいまいな言語は避けてください。
  • (推奨)変換をガイドするために、実際のローカル編集からキャプチャされた 1 つ以上の差分の例。

カスタム アップグレード手順以外にも、標準的なスキルと命令システムを通じてGitHub Copilotモダン化を拡張できます。 スキルによってエージェントに機能が追加され、命令ファイル ( copilot-instructions.md など) によってグローバルなガイダンスが提供されます。

カスタム アップグレード命令を作成する

新しい命令ファイルを生成して調整するには、次の手順に従います。 これらのセクションでは、例として Newtonsoft.Json を System.Text.Json に置き換えることに焦点を当てます。

  1. ソリューション エクスプローラー ウィンドウで、solution>Modernize を右クリックします。

    -又は-

    Copilotチャット パネルを開き、「@Modernize」と入力して、エージェントとの会話を開始します。

    注

    これらの手順は、Visual Studioに適用されます。 Visual Studio Codeやその他の環境では、Copilot チャット パネルから直接 modernize-dotnet エージェントを呼び出します。 Visual Studioでは、エージェントの名前は Modernize です。

  2. チャットで、「 I want to generate a custom upgrade instruction」と入力します。

  3. 要求されたら、I want to replace Newtonsoft with System.Text.Json などのシナリオを指定して、Copilot にファイルを作成させます。

  4. 新しいファイル（例: replace_newtonsoft_with_system_text_json.md）をCopilotが作成する時、コンテンツを確認し、チャットで洗練させます。 たとえば、"検出基準を明確にする" または "前提条件セクションの追加"をCopilotに依頼します

    ヒント

    ファイルがまだ含まれていない場合は、ファイルをソリューションに追加して表示します。

  5. 実際の差分の例を使用して、命令を強化します。

    1. 1 つのプロジェクトで必要なコード変更を手動で行います。 たとえば、「 Newtonsoft.Json パッケージを削除し、ディレクティブを使用して更新し、 JsonConvert コードを JsonSerializerに置き換える」などです。
    2. チャットで、命令ファイルを開き、「 Check my git changes and add diffs as examples to my instruction file」と入力します。
    3. Copilot で git diff を使用して、フェンスされた差分ブロックまたは構造化された例が Markdown ファイルに追加されていることを確認します。

作成に関するヒント

次のガイドラインに従って、Copilotが確実に解釈できる明確で効果的なカスタム アップグレード手順を記述します。

  • 明確な条件付き表現を使用する: If code references X, then do Y.
  • ファイルごとに 1 つの変換を保持します。複数のファイルを順番に実行する必要がある場合は、前提条件を使用します。
  • 変換の精度を向上させるために、差分や前後のスニペットなど、少なくとも 1 つの具体的な例を指定します。
  • 「改善」や「修正」などのあいまいな動詞を避けます。"replace"、"remove"、"update" などの明示的なアクションを使用します。

カスタム アップグレード命令をテストする (1 回限り実行)

アップグレード中に命令を実行する前に、分離して検証します。 分離テストは、検出を調整し、コードの変更を確認するのに役立ちます。

  1. ソリューション エクスプローラー ウィンドウで、solution>Modernize を右クリックします。

    注

    これらの手順は、Visual Studioに適用されます。 Visual Studio Codeやその他の環境では、Copilot チャット パネルから直接 modernize-dotnet エージェントを呼び出します。

  2. チャットで、ファイル名のような単語で命令を呼び出します。 たとえば、「 replace Newtonsoft with System.Text.Json 」のように入力します。

  3. チャットウィンドウで、Copilotが命令ファイルを取得したことを確認します。

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

    Copilotが命令を見つけたことを示していない場合は、同じ動詞と名詞の組み合わせなど、ファイル名のキーワードを使用して再試行してください。

  4. 提案された変更 (ソリューションの相違、保留中のコミット、またはプレビューされた変更) を確認して、カスタム アップグレード命令が期待どおりに動作することを確認します。

検証のヒント

テストの実行で期待される結果が得られない場合は、次のトラブルシューティングのヒントを使用して、命令ファイルを絞り込みます。

  • Copilotパッケージを置き換える代わりにパッケージのバージョンのみを更新する場合は、古いパッケージを削除または置き換える命令が明示的に指示されていることを確認します。
  • 自然言語によるアクティブ化が一致するように、一貫性のある名前付けを使用します。 たとえば、ファイル名を replace_ で開始し、"Replace ..." でチャット要求を開始します。
  • テスト中に、不足しているコードパターンを例として追加することで、カバレッジを改善します。

アップグレード中にカスタム命令を適用する

既存のカスタム アップグレード命令をアップグレードの評価ステージに組み込むには、次の手順を使用します。

  1. ソリューション エクスプローラー ウィンドウで、solution>Modernize を右クリックします。

    注

    これらの手順は、Visual Studioに適用されます。 Visual Studio Codeやその他の環境では、Copilot チャット パネルから直接 modernize-dotnet エージェントを呼び出します。

  2. チャットで、[Upgrade to a newer version of .NET] を選択します。 評価が開始されるまで、Copilotの質問に回答します。

  3. チャットを監視して、Copilotが評価中にカスタム命令ファイルを自動的に取得するかどうかを確認します。 Markdown 命令ファイルを開いたというメッセージを探します。

    Copilotがカスタム命令を自動的に適用しない場合は、明示的に要求します。 ファイル名と同様の文言を使用します。 たとえば、「 use the custom instructions to replace Newtonsoft with System.Text.Json during the assessment 」のように入力します。

  4. Copilotが Markdown ファイルを取得したのを確認するまで待ちます。 命令ファイルへの参照が表示されない場合は、ファイルのキー動詞 (置換、更新、削除) とパッケージ名を使用して要求を再入力します。

  5. assessment.md フォルダーに生成された.github/upgrades ファイルを確認します。 評価に、カスタム命令によって識別された問題と変更が含まれていることを確認します。

    たとえば、Newtonsoft を置き換える場合、評価では次のものが識別されます。

    • Newtonsoft.Json パッケージを使用するプロジェクト。
    • System.Text.Jsonのリファクタリングするコード パターン。
    • 削除または置換する依存関係。

  6. 必要に応じて、 assessment.md ファイルを編集してコンテキストを追加するか、特定された問題を調整してから続行します。

  7. 評価にカスタム命令が反映されたら、計画段階に進むようCopilotに指示します。

  8. Copilot生成される plan.md ファイルを確認します。 このファイルには、評価からの問題に対処するための戦略が含まれています。

  9. 続行するようにCopilot指示して、実行ステージを続行します。 Copilotが変換を適用している時にtasks.mdファイルを監視します。

アクティブ化を改善するためのヒント

カスタム アップグレード命令に名前を付け、呼び出す方法は、Copilotがそれらを自動的に取得するかどうかに影響します。 アクティブ化の信頼性を向上させるには、次のガイドラインに従います。

  • ファイル内の動詞と一致させる。 ファイル名で replaceを使用する場合は、その言い回しを使用します ( upgrade や fixではありません)。
  • わかりやすくして再利用するために、ファイルごとに 1 つの変換を保持します。 各ファイルの前提条件を一覧表示して、複数のファイルをシーケンスします。
  • 計画や実行まで待機するのではなく、最適な結果を得るには、評価段階でカスタム命令を要求します。
  • "評価を改善する" などのあいまいな要求を避けます。明示的: "評価中にreplace_newtonsoft_with_system_text_json命令を適用する"

適用された変更を検証する

アップグレードが完了した後:

  1. tasks.mdの.github/upgrades ファイルを確認して、カスタム命令に関連するタスクの状態を確認します。
  2. カスタム命令に関連する変更がないか、実行ステージ中に作成された Git コミットを確認します。
  3. テストを実行して、機能動作が正しいことを確認します。
  4. 省略可能: 成功した変更から差分の例をキャプチャし、それを命令ファイルに追加して、将来の自動化を強化します。

リソースをクリーンアップする

将来のアップグレードで変換が重複しないように、一時命令ファイルを削除または統合します。

関連コンテンツ

  • Last updated on