Extensions de fragment JSON dans le terminal Windows

Les extensions de fragment JSON sont des extraits de code JSON que les développeurs d’applications peuvent écrire pour ajouter de nouveaux profils aux paramètres des utilisateurs ou même modifier certains profils existants. Utilisez-les pour ajouter de nouveaux jeux de couleurs aux paramètres des utilisateurs.

Structure des fichiers JSON

Fractionnez le fichier JSON en deux listes : une pour les profils et une pour les schémas. Voici un exemple de fichier JSON qui ajoute un nouveau profil, modifie un profil existant et crée un jeu de couleurs :

{
  "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"
    }
  ]
}

Le premier élément de la "profiles" liste met à jour un profil existant. Il identifie le profil qu’il souhaite mettre à jour via le GUID fourni au "updates" champ (consultez la section suivante pour plus d’informations sur l’obtention du GUID). Le deuxième élément de cette liste crée un profil appelé « Profil froid ».

Dans la "schemes" liste, un nouveau jeu de couleurs appelé « Postmoderne Tango Light » est défini. Vous pouvez référencer ce jeu de couleurs dans votre fichier de paramètres ou dans ce fichier JSON lui-même (notez que « Profil froid » utilise ce jeu de couleurs nouvellement défini).

Si vous souhaitez uniquement ajouter ou modifier des profils sans ajouter de jeux de couleurs, ou vice versa, incluez uniquement la liste appropriée et omettez l’autre liste.

Note

Si vous envisagez d’utiliser PowerShell pour générer des fragments, utilisez -Encoding Utf8:

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

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

Si vous utilisez VS Code pour modifier le JSON, UTF8 est la valeur par défaut, mais vous pouvez la confirmer dans la barre d’état inférieure.

GUID de profil

Comme indiqué précédemment, les GUID de profil sont un moyen de référencer des profils et de permettre aux utilisateurs de les mettre à jour et de les étendre sans se soucier des modifications d’emplacement ou de nom. Vous ne pouvez modifier que les profils par défaut, l’invite de commandes et PowerShell, ainsi que les profils dynamiques par le biais de fragments. Fournir un GUID est facultatif, mais fortement encouragé.

Le générateur UUID version 5 crée les GUID et prend en charge l’encodage UTF-16LE sans BOM.

Le GUID d’espace de noms pour le terminal Windows en cas de profils créés par des plug-ins et des fragments est {f65ddb7e-706b-4499-8a50-40313caf510a}. Les profils créés par l’équipe de terminal Windows utilisent un GUID distinct ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Cette séparation désambigue les profils créés par l’équipe de terminal Windows des profils créés par des plug-ins ou des fragments afin qu’ils ne se heurtent jamais accidentellement.

Guide pratique pour déterminer le GUID d’un profil existant

Pour déterminer le GUID d’un profil à mettre à jour, tenez compte du type de profil utilisé :

Le profil expédié par un tiers et stocké dans un emplacement standard de fragment de Terminal Windows nécessite le GUID de l’espace de noms de profil et de fragment {f65ddb7e-706b-4499-8a50-40313caf510a}, le GUID de l’espace de noms de l’application, et le nom du profil. Pour un fragment de profil nommé « Git Bash » fourni par l’application « Git », le GUID généré est {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}.

Un profil généré automatiquement par le terminal Windows nécessite le GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} interne du terminal Windows et le nom du profil. Pour un profil nommé « Ubuntu » généré automatiquement pendant l’installation de WSL, le GUID résultant est {2c4de342-38b7-51cf-b940-2309a097f518}. Contrairement à l’exemple de fragment précédent, aucun nom d’application n’est impliqué.

Génération d’un nouveau GUID de profil

Pour générer un GUID pour un nouveau profil avant de le distribuer, utilisez l’exemple Python 3 suivant. Il génère un GUID basé sur le GUID de l’espace de noms de profil et de fragment pour un profil appelé « Git Bash » stocké dans un dossier standard de fragments du Terminal Windows sous le nom de l’application « Git », correspondant facilement à la vérification de cohérence.

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}}}")

Calcul d’un GUID pour un profil intégré

Pour calculer un GUID pour un profil intégré, tel que les profils WSL générés automatiquement, utilisez l’exemple Python 3 suivant. Il calcule un GUID basé sur le GUID de l’espace de noms du terminal Windows pour un profil appelé « Ubuntu » qui a été généré automatiquement pour la distribution WSL, correspondant facilement à la vérification de la santé.

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}}}")

Configuration minimale requise pour les paramètres ajoutés avec des fragments

Certaines restrictions minimales s’appliquent à ce que vous pouvez ajouter aux paramètres utilisateur à l’aide de fragments JSON :

Pour les nouveaux profils ajoutés via des fragments, le nouveau profil doit définir un nom pour lui-même.
Pour les nouveaux jeux de couleurs ajoutés par fragments, le nouveau jeu de couleurs doit définir un nom pour lui-même et définir chaque couleur dans la table de couleurs (autrement dit, les couleurs « noir » par « brightWhite » dans l’exemple d’image précédent).

Où placer les fichiers de fragment JSON

L’emplacement où placer les fichiers de fragment JSON varie en fonction de la méthode d’installation de l’application qui les ajoute.

Applications du Microsoft Store

Pour les applications installées via le Microsoft Store (ou similaire), l’application doit se déclarer comme une extension d’application. En savoir plus sur la création et l’hébergement d’une extension d’application. La section nécessaire est répliquée ici. Le fichier appxmanifest du package doit inclure :

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

Éléments clés à noter :

Le "Name" champ doit être com.microsoft.windows.terminal.settings destiné au terminal Windows pour détecter l’extension.
Le "Id" champ peut être rempli comme vous le souhaitez.
Le "PublicFolder" champ doit avoir le nom du dossier, par rapport à la racine du package, où vous stockez les fichiers JSON (ce dossier est généralement appelé « Public », mais peut être nommé autre chose).
Dans le dossier public, créez un sous-répertoire appelé « Fragments » et stockez les fichiers JSON dans ce sous-répertoire.

Applications installées à partir du web

Pour les applications installées à partir du web, tenez compte de deux cas.

Le premier cas est que l’installation concerne tous les utilisateurs sur le système. Dans ce cas, ajoutez les fichiers JSON au dossier :

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

Le deuxième cas est que l’installation n’est destinée qu’à l’utilisateur actuel. Dans ce cas, ajoutez les fichiers JSON au dossier :

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

Notez que les dossiers ProgramData et LocalAppData sont des dossiers connus auxquels le programme d’installation doit accéder. Si le Windows Terminal\Fragments répertoire n’existe pas, le programme d’installation doit le créer. {app-name} doit être exclusif à votre application, et {file-name}.json le terminal peut lire tous les fichiers .json dans ce répertoire.

Distribution de ressources multimédias avec votre extension de fragment

À partir de Windows Terminal 1.24, les extensions de fragment peuvent distribuer des ressources multimédias telles que des images et des nuanceurs de pixels à utiliser avec les iconbackgroundImageexperimental.pixelShaderPath propriétés et experimental.pixelShaderImagePath les profils et les actions.

Versions antérieures des URL web prises en charge par Terminal pour icon et backgroundImage. Ces versions continueront de charger des ressources d’URL web à perpétuité. Les versions plus récentes n’accèdent plus aux URL web, mais recherchent plutôt dans le répertoire contenant votre fichier fragment.

Si vous souhaitez maintenir la compatibilité avec toutes les versions disponibles de Terminal, vous pouvez placer toutes les ressources web dans le même répertoire que vos .json fichiers.

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

Vous pouvez vous appuyer sur les comportements de compatibilité suivants :

Chemin d’accès aux ressources	< 1.24	≥ 1.24
`https://example.com/app/app_icon.png`	✅ chargé à partir du web	✅ chargé à partir de `$FRAGMENT_ROOT\app_icon.png`
`app_icon.png`	❌ Ignoré	✅ chargé à partir de `$FRAGMENT_ROOT\app_icon.png`
`ms-appx://MyApplication/Fragments/app_icon.png`	❌ Ignoré	✅ chargé à partir de `$FRAGMENT_ROOT\app_icon.png`