JSON-fragmentextensies in Windows Terminal

JSON-fragmentextensies zijn fragmenten van JSON die toepassingsontwikkelaars kunnen schrijven om nieuwe profielen toe te voegen aan de instellingen van gebruikers of zelfs bepaalde bestaande profielen te wijzigen. Gebruik ze om nieuwe kleurenschema's toe te voegen aan de instellingen van gebruikers.

Structuur van de JSON-bestanden

Splits het JSON-bestand in twee lijsten: één voor profielen en één voor schema's. Hier volgt een voorbeeld van een JSON-bestand dat een nieuw profiel toevoegt, een bestaand profiel wijzigt en een nieuw kleurenschema maakt:

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

Het eerste item in de "profiles" lijst werkt een bestaand profiel bij. Het identificeert het profiel dat het wil bijwerken via de GUID die is opgegeven voor het "updates" veld (zie de volgende sectie voor meer informatie over het verkrijgen van de GUID). Het tweede item in die lijst maakt een nieuw profiel met de naam 'Statisch profiel'.

In de lijst wordt een nieuw kleurenschema met de "schemes" naam 'Postmodern Tango Light' gedefinieerd. U kunt naar dit kleurenschema verwijzen in uw instellingenbestand of in dit JSON-bestand zelf (let op dat 'Cool Profiel' dit nieuw gedefinieerde kleurenschema gebruikt).

Als u alleen profielen wilt toevoegen of wijzigen zonder kleurenschema's toe te voegen of omgekeerd, neemt u alleen de relevante lijst op en laat u de andere lijst weg.

# 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

Profiel-GUID's

Zoals eerder vermeld, zijn profiel-GUID's een manier om te verwijzen naar profielen en kunnen gebruikers ze bijwerken en uitbreiden zonder dat ze zich zorgen hoeven te maken over locatie- of naamwijzigingen. U kunt alleen de standaardprofielen, opdrachtprompt en PowerShell en dynamische profielen wijzigen via fragmenten. Het leveren van een GUID is optioneel, maar sterk aangemoedigd.

De UUID-generator van versie 5 maakt de GUID's en ondersteunt BOM-less UTF-16LE-codering.

De naamruimte-GUID voor Windows Terminal in het geval van profielen die zijn gemaakt door invoegtoepassingen en fragmenten is {f65ddb7e-706b-4499-8a50-40313caf510a}. Profielen die zijn gemaakt door het Windows Terminal Team gebruiken een afzonderlijke GUID ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Met deze scheiding wordt onderscheid gemaakt tussen profielen die door het Windows Terminal Team zijn gemaakt op basis van profielen die zijn gemaakt door invoegtoepassingen of fragmenten, zodat ze nooit per ongeluk botsen.

De GUID van een bestaand profiel bepalen

Als u de GUID van een profiel wilt bepalen dat moet worden bijgewerkt, moet u overwegen welk type profiel het is:

Voor een profiel dat is verzonden door een derde partij en is opgeslagen op een standaard Windows Terminal Fragment-locatie, zijn de GUID voor de profiel- en fragment-namespace, de GUID van de toepassingsnamespace, en de profielnaam vereist. Voor een profielfragment met de naam 'Git Bash' dat wordt geleverd door de toepassing 'Git', is {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}de gegenereerde GUID.

Voor een profiel dat automatisch wordt gegenereerd door Windows Terminal, is de interne GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} van Windows Terminal en de profielnaam vereist. Voor een profiel met de naam Ubuntu dat automatisch wordt gegenereerd tijdens de WSL-installatie, is {2c4de342-38b7-51cf-b940-2309a097f518}de resulterende GUID. In tegenstelling tot het vorige fragmentvoorbeeld is er geen toepassingsnaam betrokken.

Een nieuwe profiel-GUID genereren

Als u een GUID voor een volledig nieuw profiel wilt genereren voordat u het distribueert, gebruikt u het volgende Python 3-voorbeeld. Een GUID wordt gegenereerd op basis van de GUID van zowel de profiel- als de fragmentnaamruimte voor een profiel genaamd 'Git Bash', dat is opgeslagen in een standaardmap met Windows Terminal Fragments onder de toepassingsnaam 'Git', wat handig overeenkomt met de validatiecontrole.

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

Een GUID berekenen voor een ingebouwd profiel

Als u een GUID wilt berekenen voor een ingebouwd profiel, zoals de automatisch gegenereerde WSL-profielen, gebruikt u het volgende Python 3-voorbeeld. Hiermee wordt een GUID berekend op basis van de GUID van de Windows Terminal-naamruimte voor een profiel met de naam Ubuntu dat automatisch is gegenereerd voor de WSL-distributie, die gemakkelijk overeenkomt met de sanity-controle.

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

Minimale vereisten voor instellingen die zijn toegevoegd met fragmenten

Enkele minimale beperkingen zijn van toepassing op wat u kunt toevoegen aan gebruikersinstellingen met behulp van JSON-fragmenten:

• Voor nieuwe profielen die via fragmenten worden toegevoegd, moet het nieuwe profiel een naam voor zichzelf definiëren.
• Voor nieuwe kleurenschema's die via fragmenten worden toegevoegd, moet het nieuwe kleurenschema een naam voor zichzelf definiëren en elke kleur in de kleurentabel definiëren (dat wil gezegd: de kleuren 'zwart' tot en met 'brightWhite' in de voorgaande voorbeeldafbeelding).

Waar de JSON-fragmentbestanden moeten worden opgeslagen

De locatie waar de JSON-fragmentbestanden moeten worden opgeslagen, is afhankelijk van de installatiemethode van de toepassing die deze toevoegt.

Microsoft Store-toepassingen

Voor toepassingen die zijn geïnstalleerd via de Microsoft Store (of vergelijkbaar), moet de toepassing zichzelf declareren als een app-extensie. Meer informatie over het maken en hosten van een app-extensie. De benodigde sectie wordt hier gerepliceerd. Het appxmanifest-bestand van het pakket moet het volgende bevatten:

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

Belangrijke dingen die u moet noteren:

• Het "Name" veld moet voor Windows Terminal zijn com.microsoft.windows.terminal.settings om de extensie te detecteren.
• Het "Id" veld kan naar wens worden ingevuld.
• Het "PublicFolder" veld moet de naam van de map hebben ten opzichte van de hoofdmap van het pakket, waar u de JSON-bestanden opslaat (deze map wordt meestal 'Openbaar' genoemd, maar kan iets anders worden genoemd).
• Maak in de openbare map een submap met de naam Fragmenten en sla de JSON-bestanden op in die submap.

Toepassingen die vanaf het web zijn geïnstalleerd

Houd rekening met twee gevallen voor toepassingen die vanaf internet zijn geïnstalleerd.

Het eerste geval is dat de installatie voor alle gebruikers op het systeem is. Voeg in dit geval de JSON-bestanden toe aan de map:

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

Het tweede geval is dat de installatie alleen voor de huidige gebruiker is. Voeg in dit geval de JSON-bestanden toe aan de map:

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

Houd er rekening mee dat zowel de als ProgramData de LocalAppData mappen bekende mappen zijn waartoe het installatieprogramma toegang moet hebben. Als de Windows Terminal\Fragments map niet bestaat, moet het installatieprogramma deze maken. De {app-name} moet uniek zijn voor uw toepassing en de {file-name}.json kan alles zijn, de terminal leest namelijk alle .json-bestanden in die map.

Mediabronnen distribueren met uw fragmentextensie

Vanaf Windows Terminal 1.24 kunnen fragmentextensies mediaresources zoals afbeeldingen en pixel-shaders distribueren die moeten worden gebruikt met de icon, backgroundImageexperimental.pixelShaderPath en experimental.pixelShaderImagePath eigenschappen voor profielen en acties.

Eerdere versies van Terminal ondersteunde web-URL's voor icon en backgroundImage. Deze versies blijven web-URL-resources in eeuwigheid laden. Nieuwere versies hebben geen toegang meer tot web-URL's, maar zoeken in plaats daarvan in de map met uw fragmentbestand.

Als u compatibiliteit met alle beschikbare versies van Terminal wilt behouden, kunt u alle webresources in dezelfde map plaatsen als uw .json bestanden.

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

U kunt vertrouwen op het volgende compatibiliteitsgedrag: