Windows ターミナルでの JSON フラグメント拡張機能

JSON フラグメント拡張は、アプリケーション開発者がユーザーの設定に新しいプロファイルを追加したり、特定の既存のプロファイルを変更したりするために書き込むことができる JSON のスニペットです。 また、ユーザーの設定に新しい配色を追加するために使用することもできます。

JSON ファイルの構造

JSON ファイルは、プロファイル用とスキーム用の 2 つのリストに分割する必要があります。 新しいプロファイルを追加し、既存のプロファイルを変更し、新しい配色パターンを作成する json ファイルの例を次に示します。

{
  "profiles": [
    {
      // update a profile by using its GUID
      "updates": "{2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}",
      "fontSize": 16,
      "fontWeight": "thin"
    },
    {
      // create a new profile
      "name": "Cool Profile",
      "commandline": "powershell.exe",
      "antialiasingMode": "aliased",
      "fontWeight": "bold",
      "colorScheme": "Postmodern Tango Light"
    }
  ],
  "schemes": [
    {
      // create a new color scheme
      "name": "Postmodern Tango Light",
      "black": "#0C0C0C",
      "red": "#C50F1F",
      "green": "#13A10E",
      "yellow": "#C19C00",
      "blue": "#0037DA",
      "purple": "#881798",
      "cyan": "#3A96DD",
      "white": "#CCCCCC",
      "brightBlack": "#767676",
      "brightRed": "#E74856",
      "brightGreen": "#16C60C",
      "brightYellow": "#F9F1A5",
      "brightBlue": "#3B78FF",
      "brightPurple": "#B4009E",
      "brightCyan": "#61D6D6",
      "brightWhite": "#F2F2F2"
    }
  ]
}

"profiles"リストの最初の項目は、既存のプロファイルを更新し、"updates" フィールドに提供された GUID を介して更新するプロファイルを識別します (GUID を取得する方法の詳細は次のセクションにあります)。 その一覧の 2 番目の項目では、"クール プロファイル" という名前の新しいプロファイルが作成されます。

"schemes"リストでは、"Postmodern Tango Light" と呼ばれる新しい配色が定義され、その後、ユーザーが設定ファイルまたはこの JSON ファイル自体で参照できます ("クール プロファイル" では、この新しく定義された配色が使用されていることに注意してください)。

もちろん、開発者が配色を追加せずにプロファイルの追加/変更のみを希望する場合 (およびその逆の場合)、関連するリストのみが存在する必要があり、他のリストは省略できます。

# BAD: PowerShell uses UTF16LE by default
Write-Output $fragmentJson > $fragmentPath

# GOOD: Uses UTF8, so Terminal will read this
Write-Output $fragmentJson | Out-File $fragmentPath -Encoding Utf8

プロファイル GUID

前述のプロファイル GUID は、プロファイルを参照し、ユーザーが場所や名前の変更を気にせずに更新および拡張できるようにする方法です。 フラグメントを使用して変更できるプロファイルは、既定のプロファイル、コマンド プロンプト、PowerShell、 および動的プロファイルのみです。 ただし、GUID の指定は省略可能ですが、強くお勧めします。

GUID は、BOM レス UTF-16LE エンコードをサポートするバージョン 5 UUID ジェネレーターを使用して生成されます。

プラグインとフラグメントによって作成されたプロファイルの場合の Windows ターミナルの名前空間 GUID が {f65ddb7e-706b-4499-8a50-40313caf510a}。 Windows ターミナル チームによって作成されたプロファイルでは、別の GUID ({2bde4a90-d05f-401c-9492-e40884ead1d8}) が使用されます。 これは、Windows ターミナル チームによって作成されたプロファイルを、プラグインまたはフラグメントによって作成されたプロファイルから明確にするために行われ、誤って競合することがないようにします。

既存のプロファイルの GUID を確認する方法

更新するプロファイルの GUID を決定するには、プロファイルの種類によって異なります。

標準の Windows ターミナル フラグメントの場所に格納されているサード パーティによって出荷されるプロファイルには、プロファイルとフラグメント名前空間 GUID {f65ddb7e-706b-4499-8a50-40313caf510a}、アプリケーション名前空間 GUID、およびプロファイル名が必要です。 アプリケーション 'Git' によって提供される "Git Bash" という名前のプロファイル フラグメントの場合、生成される GUID は次のとおりです: {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}。

Windows ターミナルによって自動的に生成されるプロファイルには、Windows ターミナルの内部 GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} とプロファイル名が必要です。 WSL のインストール中に自動的に生成される "Ubuntu" という名前のプロファイルの場合、結果の GUID は {2c4de342-38b7-51cf-b940-2309a097f518}です。 前のフラグメントの例とは対照的に、'アプリケーション名' は関係しません。

新しいプロファイル GUID の生成

配布する前にまったく新しいプロファイルの GUID を生成するには、次の Python 3 の例を使用します。 "Git" アプリケーション名の下にある標準の Windows ターミナル フラグメント フォルダーに格納されている "Git Bash" という名前のプロファイルのプロファイルとフラグメント名前空間 GUID に基づいて GUID が生成され、サニティ チェックと簡単に一致します。

import uuid

# The Windows Terminal namespace GUID for custom profiles & fragments
terminalNamespaceGUID = uuid.UUID("{f65ddb7e-706b-4499-8a50-40313caf510a}")

# The Application Namespace GUID
appNamespaceGUID = uuid.uuid5(terminalNamespaceGUID, "Git".encode("UTF-16LE").decode("ASCII"))

# Calculate the example GUID for the 'Git Bash' profile
profileGUID = uuid.uuid5(appNamespaceGUID, "Git Bash".encode("UTF-16LE").decode("ASCII"))

# Output the GUID as Windows Terminal expects it (enclosed in curly brackets)
print(f"{{{profileGUID}}}")

組み込みプロファイルの GUID の計算

自動生成された WSL プロファイルなど、組み込みプロファイルの GUID を計算するには、次の Python 3 の例を使用できます。 WSL ディストリビューション用に自動的に生成された "Ubuntu" という名前のプロファイルの Windows ターミナル名前空間 GUID に基づいて GUID が計算され、サニティ チェックと簡単に一致します。

import uuid

# The Windows Terminal namespace GUID automatically generated profiles
terminalNamespaceGUID = uuid.UUID("{2bde4a90-d05f-401c-9492-e40884ead1d8}")

# Calculate the example GUID for the 'Git Bash' profile
profileGUID = uuid.uuid5(terminalNamespaceGUID, "Ubuntu".encode("UTF-16LE").decode("ASCII"))

# Output the GUID as Windows Terminal expects it (enclosed in curly brackets)
print(f"{{{profileGUID}}}")

フラグメントで追加された設定の最小要件

JSON フラグメントを使用してユーザー設定に追加できる内容には、いくつかの最小限の制限があります。

• フラグメントを介して追加された新しいプロファイルの場合、新しいプロファイルでは、少なくともそれ自体の名前を定義する必要があります。
• フラグメントを介して追加された新しい配色パターンの場合、新しい配色では、それ自体の名前を定義し、カラー テーブル内のすべての色を定義する必要があります (つまり、上記の例の画像では、"黒" から "brightWhite" までの色)。

JSON フラグメント ファイルを配置する場所

JSON フラグメント ファイルを配置する場所は、配置するアプリケーションのインストール方法によって異なります。

Microsoft Store アプリケーション

Microsoft Store (または同様) を使用してインストールされたアプリケーションの場合、アプリケーションはアプリ拡張機能として宣言する必要があります。 アプリ拡張機能を作成してホストする方法の詳細について説明します。 ここで必要なセクションがレプリケートされます。 パッケージの appxmanifest ファイルには、次のものが含まれている必要があります。

<Package
  ...
  xmlns:uap3="http://schemas.microsoft.com/appx/manifest/uap/windows10/3"
  IgnorableNamespaces="uap uap3 mp">
  ...
    <Applications>
      <Application Id="App" ... >
        ...
        <Extensions>
          ...
          <uap3:Extension Category="windows.appExtension">
            <uap3:AppExtension Name="com.microsoft.windows.terminal.settings"
                               Id="<id>"
                               PublicFolder="Public">
            </uap3:AppExtension>
          </uap3:Extension>
        </Extensions>
      </Application>
    </Applications>
    ...
</Package>

注意すべき重要な点:

• Windows ターミナルが拡張機能を検出できるようにするには、 "Name" フィールドを com.microsoft.windows.terminal.settings する必要があります。
• "Id"フィールドは、開発者が望むように入力できます。
• "PublicFolder" フィールドには、JSON ファイルが格納されているパッケージ ルートを基準としたフォルダーの名前が必要です (このフォルダーは通常は "Public" と呼ばれますが、開発者が必要とする場合は別の名前を付けることができます)。
• パブリック フォルダー内に "Fragments" という名前のサブディレクトリを作成し、JSON ファイルをそのサブディレクトリに格納する必要があります。

Web からインストールされたアプリケーション

Web からインストールされたアプリケーションの場合、2 つのケースがあります。

1 つ目は、インストールがシステム上のすべてのユーザーに対して行われるということです。 この場合、JSON ファイルをフォルダーに追加する必要があります。

C:\ProgramData\Microsoft\Windows Terminal\Fragments\{app-name}\{file-name}.json

2 番目のケースでは、インストールは現在のユーザーに対してのみ行われます。 この場合、JSON ファイルをフォルダーに追加する必要があります。

C:\Users\<user>\AppData\Local\Microsoft\Windows Terminal\Fragments\{app-name}\{file-name}.json

ProgramDataフォルダーとLocalAppData フォルダーの両方が、インストーラーがアクセスできる既知のフォルダーであることに注意してください。 いずれの場合も、 Windows Terminal\Fragments ディレクトリが存在しない場合は、インストーラーによって作成されます。 {app-name}はアプリケーションに固有である必要があり、{file-name}.jsonは何でもかまいません。ターミナルはそのディレクトリ内のすべての .json ファイルを読み取ります。

フラグメント拡張機能を使用したメディア リソースの配布

Windows ターミナル 1.24 の時点で、フラグメント拡張機能は、プロファイルとアクションの icon、 backgroundImage、 experimental.pixelShaderPath 、および experimental.pixelShaderImagePath プロパティで使用されるイメージやピクセル シェーダーなどのメディア リソースを配布できます。

以前のバージョンのターミナルでは、 icon と backgroundImageの Web URL がサポートされています。 これらのバージョンでは、永続的に Web URL リソースが引き続き読み込まれます。 新しいバージョンでは Web URL にアクセスできなくなりますが、代わりにフラグメント ファイルを含むディレクトリが検索されます。

利用可能なすべてのバージョンのターミナルとの互換性を維持したい場合は、 .json ファイルと同じディレクトリに任意の Web リソースを配置できます。

Fragments\
 `- AppName\ <- FRAGMENT_ROOT
     |- file1.json
     |- file2.json
     `- app_icon.png

次の互換性の動作に依存できます。