JSON-Fragmenterweiterungen in Windows-Terminal

JSON-Fragmenterweiterungen sind JSON-Codeausschnitte, die Anwendungsentwickler schreiben können, um den Einstellungen der Benutzer neue Profile hinzuzufügen oder sogar bestimmte vorhandene Profile zu ändern. Sie können auch verwendet werden, um den Einstellungen der Benutzer neue Farbschemas hinzuzufügen.

Struktur der JSON-Dateien

Die JSON-Datei sollte in zwei Listen aufgeteilt sein: eine für Profile und eine für Schemas. Hier ist ein Beispiel für eine JSON-Datei, die ein neues Profil hinzufügt, ein vorhandenes Profil ändert und ein neues Farbschema erstellt:

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

Das erste Element in der "profiles"-Liste aktualisiert ein vorhandenes Profil, wobei es das Profil, das über die für das Feld "updates" bereitgestellte GUID aktualisiert werden soll, identifiziert (Details zum Abrufen der GUID finden Sie im nächsten Abschnitt). Das zweite Element in dieser Liste erstellt ein neues Profil namens „Cool Profile“.

In der Liste "schemes" wird ein neues Farbschema namens „Postmodern Tango Light“ definiert, auf das der Benutzer anschließend in seiner Einstellungsdatei oder in dieser JSON-Datei selbst verweisen kann (beachten Sie, dass „Cool Profile“ dieses neu definierte Farbschema verwendet).

Wenn der Entwickler nur Profile hinzufügen/ändern möchte, ohne Farbschemata hinzuzufügen (und umgekehrt), muss natürlich nur die relevante Liste vorhanden sein und die andere Liste kann weggelassen werden.

# 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

Profil-GUIDs

Wie bereits erwähnt, sind Profil-GUIDs eine Möglichkeit, auf Profile zu verweisen und Benutzern das Aktualisieren und Erweitern zu ermöglichen, ohne sich Gedanken über Änderungen am Speicherort oder Namen machen zu müssen. Die einzigen Profile, die durch Fragmente geändert werden können, sind Standardprofile, die Profile „Eingabeaufforderung“ und „Windows PowerShell“, sowie dynamische Profile. Die Bereitstellung einer GUID ist optional, wird jedoch dringend empfohlen.

Die GUIDs werden mithilfe eines UUID-Generators der Version 5 generiert, der UTF-16LE-Codierung ohne BOM unterstützt.

Die Namespace-GUID für Windows-Terminal bei Profilen, die von Plug-Ins und Fragmenten erstellt werden, ist {f65ddb7e-706b-4499-8a50-40313caf510a}. Profile, die vom Windows-Terminal-Team erstellt werden, verwenden eine separate GUID ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Dadurch werden Profile, die vom Windows-Terminal-Team erstellt wurden, von Profilen, die von Plug-Ins oder Fragmenten erstellt wurden, eindeutig unterschieden, damit sie nie versehentlich in Konflikt geraten können.

Bestimmen der GUID eines vorhandenen Profils

Das Bestimmen der GUID eines zu aktualisierenden Profils hängt davon ab, um welche Art von Profil es sich handelt:

Für ein Profil, das von einem Drittanbieter angeboten wird und an einem Standardspeicherort für Windows-Terminal-Fragmente gespeichert ist, sind die GUID des Profil- und Fragmentnamespace, die GUID {f65ddb7e-706b-4499-8a50-40313caf510a} des Anwendungsnamespace und der Profilname erforderlich. Für ein Profilfragment mit dem Namen „Git Bash“, das von der Anwendung „Git“ bereitgestellt wird, lautet die generierte GUID wie folgt: {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}.

Für ein Profil, das automatisch von Windows-Terminal generiert wird, sind die interne Windows-Terminal-GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} und der Profilname erforderlich. Für ein Profil mit dem Namen „Ubuntu“, das während der WSL-Installation automatisch generiert wird, lautet die resultierende GUID {2c4de342-38b7-51cf-b940-2309a097f518}. Im Gegensatz zum vorherigen Fragmentbeispiel ist kein „Anwendungsname“ beteiligt.

Generieren einer neuen Profil-GUID

Zum Generieren einer GUID für ein vollständig neues Profil vor der Verteilung können Sie das folgende Python 3-Beispiel verwenden. Es generiert eine GUID basierend auf der GUID des Profil- und Fragmentnamespace für ein Profil namens „Git Bash“, das in einem Standardordner für Windows-Terminal-Fragmente unter dem Anwendungsnamen „Git“ gespeichert ist, und passt praktischerweise zur Integritätsprüfung.

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

Berechnen einer GUID für ein integriertes Profil

Zum Berechnen einer GUID für ein integriertes Profil, z. B. die automatisch generierten WSL-Profile, können Sie das folgende Python 3-Beispiel verwenden. Es berechnet eine GUID basierend auf der GUID des Windows-Terminal-Namespace für ein Profil namens „Ubuntu“, das automatisch für die WSL-Verteilung generiert wurde und praktischerweise der Integritätsprüfung entspricht.

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

Mindestanforderungen für Einstellungen, die mit Fragmenten hinzugefügt wurden

Es gibt einige minimale Einschränkungen dahingehend, welche Elemente Benutzereinstellungen mithilfe von JSON-Fragmenten hinzugefügt werden können:

• Für neue Profile, die über Fragmente hinzugefügt werden, muss das neue Profil mindestens seinen eigenen Namen definieren.
• Für neue Farbschemas, die über Fragmente hinzugefügt werden, muss das neue Farbschema seinen eigenen Namen sowie jede Farbe in der Farbtabelle definieren (d. h. im obigen Beispielbild die Farben „black“ bis „brightWhite“).

Speicherort der JSON-Fragmentdateien

Der Speicherort für die JSON-Fragmentdateien variiert je nach Installationsmethode der Anwendung, die sie platzieren möchte.

Microsoft Store-Anwendungen

Bei Anwendungen, die über Microsoft Store (oder ähnliches) installiert werden, muss sich die Anwendung selbst als App-Erweiterung deklarieren. Erfahren Sie mehr über das Erstellen und Hosten einer App-Erweiterung. Der erforderliche Abschnitt wird hier repliziert. Die appxmanifest-Datei des Pakets muss Folgendes enthalten:

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

Folgende wichtige Dinge sind zu beachten:

• Das Feld "Name" muss auf com.microsoft.windows.terminal.settings festgelegt sein, damit Windows-Terminal die Erweiterung erkennen kann.
• Das Feld "Id" kann nach Wunsch des Entwicklers ausgefüllt werden.
• Das Feld "PublicFolder" sollte den Namen des Ordners relativ zum Paketstamm enthalten, unter dem die JSON-Dateien gespeichert werden – dieser Ordner heißt normalerweise „Öffentlich“, kann aber auch anders benannt werden, wenn der Entwickler dies möchte.
• Im öffentlichen Ordner sollte ein Unterverzeichnis namens „Fragmente“ erstellt werden, und die JSON-Dateien sollten in diesem Unterverzeichnis gespeichert werden.

Über das Web installierte Anwendungen

Für Anwendungen, die über das Web installiert werden, gibt es zwei Fälle.

Im ersten Fall erfolgt die Installation für alle Benutzer auf dem System. In diesem Fall sollten die JSON-Dateien dem Ordner hinzugefügt werden:

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

Im zweiten Fall gilt die Installation nur für den aktuellen Benutzer. In diesem Fall sollten die JSON-Dateien dem Ordner hinzugefügt werden:

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

Beachten Sie, dass die Ordner ProgramData und LocalAppData bekannte Ordner sind, auf die das Installationsprogramm zugreifen kann. In beiden Fällen gilt Folgendes: Wenn das Verzeichnis Windows Terminal\Fragments nicht vorhanden ist, sollte es vom Installationsprogramm erstellt werden. {app-name} sollte für Ihre Anwendung eindeutig sein und {file-name}.json kann beliebig sein – das Terminal liest alle JSON-Dateien in diesem Verzeichnis.