Extensions de fragments JSON dans le Terminal Windows

Article
03/21/2023

Les extensions de fragments 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 et même modifier certains profils existants. Elles permettent également d’ajouter de nouveaux modèles de couleurs aux paramètres des utilisateurs.

Structure des fichiers JSON

Le fichier JSON doit être divisé en deux listes : une pour les profils et une pour les modèles. Voici un exemple de fichier JSON qui ajoute un nouveau profil, modifie un profil existant et crée un modèle 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 liste "profiles" met à jour un profil existant, celui-ci étant identifié par le GUID fourni au champ "updates". Vous verrez comment obtenir le GUID dans la section suivante. Le deuxième élément de cette liste crée un profil appelé « Cool Profile ».

Dans la liste "schemes", un nouveau modèle de couleurs appelé « Postmodern Tango Light » est défini. L’utilisateur peut par la suite référencer ce modèle dans son fichier de paramètres ou dans ce fichier JSON (notez que « Cool Profile » utilise le nouveau modèle de couleurs défini).

Bien entendu, si le développeur souhaite uniquement ajouter/modifier des profils sans ajouter de modèles de couleurs (et inversement), seule la liste appropriée doit être présente et l’autre liste peut être omise.

Remarque

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

# 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

Si vous utilisez VS Code pour modifier du code JSON, UTF8 est la valeur par défaut (ce que vous pouvez 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 les profils et de permettre aux utilisateurs de les mettre à jour et de les étendre sans se soucier des changements d’emplacement ou de nom. Les seuls profils qui peuvent être modifiés au moyen de fragments sont les profils par défaut, Invite de commandes et PowerShell, ainsi que les profils dynamiques. La spécification d’un GUID est facultative, mais vivement encouragée.

Les GUID sont générés à l’aide d’un générateur UUID version 5 qui prend en charge l’encodage UTF-16LE sans indicateur d’ordre des octets (BOM).

Le GUID d’espace de noms pour le Terminal Windows dans le 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 Terminal Windows utilisent un GUID distinct ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Cela permet de lever l’ambiguïté entre les profils créés par l’équipe Terminal Windows et ceux créés par des plug-ins ou des fragments afin qu’ils n’entrent jamais en conflit accidentellement.

Comment déterminer le GUID d’un profil existant

Le GUID d’un profil à mettre à jour dépend du type de profil :

Un profil fourni par un tiers et stocké dans un emplacement de fragments Terminal Windows standard nécessite le GUID d’espace de noms de fragment et de profil utilisateur{f65ddb7e-706b-4499-8a50-40313caf510a}, le GUID d’espace de noms d’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 interne du Terminal Windows {2bde4a90-d05f-401c-9492-e40884ead1d8} et le nom du profil. Pour un profil nommé « Ubuntu » généré automatiquement durant 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 profil entièrement nouveau avant de le distribuer, vous pouvez utiliser l’exemple Python 3 suivant. Il génère un GUID basé sur le GUID d’espace de noms de fragment et de profil pour un profil appelé « Git Bash » stocké dans un dossier de fragments Terminal Windows standard sous le nom d’application « Git », ce qui correspond précisément au contrôle d’intégrité.

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é, comme un profil WSL généré automatiquement, vous pouvez utiliser l’exemple Python 3 suivant. Il calcule un GUID basé sur le GUID d’espace de noms Terminal Windows pour un profil appelé « Ubuntu » qui a été généré automatiquement pour la distribution WSL, ce qui correspond précisément au contrôle d’intégrité.

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

Les profils qu’il est possible d’ajouter aux paramètres utilisateur avec des fragments JSON font l’objet de restrictions :

Un nouveau profil ajouté avec des fragments doit, au minimum, s’attribuer un nom.
Un nouveau modèle de couleurs ajouté avec des fragments doit s’attribuer un nom et définir chaque couleur de la table des couleurs (de « black » à « brightWhite » dans l’exemple d’image ci-dessus).

Où placer les fichiers de fragments JSON

L’emplacement des fichiers de fragments JSON varie en fonction de la méthode d’installation de l’application qui souhaite placer ces fichiers.

Applications Microsoft Store

Pour les applications installées par le biais du Microsoft Store (ou similaire), l’application doit se déclarer comme extension d’application. Découvrez-en 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>

Points clés à prendre en compte :

Le champ "Name" doit être com.microsoft.windows.terminal.settings pour que le Terminal Windows puisse détecter l’extension.
Le champ "Id" peut être rempli selon les préférences du développeur.
Le champ "PublicFolder" doit contenir le nom du dossier, relatif à la racine du package, où les fichiers JSON sont stockés (ce dossier est généralement appelé « Public », mais peut être renommé par le développeur).
Dans le dossier Public, les fichiers JSON doivent être stockés dans un sous-répertoire appelé « Fragments ».

Applications installées à partir du web

Pour les applications installées à partir du web, deux cas de figure se présentent.

Dans le premier cas, l’installation est destinée à tous les utilisateurs du système. Les fichiers JSON doivent alors être ajoutés au dossier :

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

Dans le deuxième cas, l’installation est réservée à l’utilisateur actuel. Les fichiers JSON doivent alors être ajoutés 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 avoir accès. Dans les deux cas, si le répertoire Windows Terminal\Fragments n’existe pas, le programme d’installation doit le créer. {app-name} doit être unique à votre application et {file-name}.json peut être ce que vous voulez (le terminal lira tous les fichiers .json dans ce répertoire).