Estensioni dei frammenti JSON in Terminale Windows

Articolo
10/11/2023

Le estensioni dei frammenti JSON sono frammenti di codice JSON che gli sviluppatori di applicazioni possono scrivere per aggiungere nuovi profili alle impostazioni degli utenti o persino per modificare determinati profili esistenti. Possono anche essere usate per aggiungere nuove combinazioni di colori alle impostazioni degli utenti.

Struttura dei file JSON

Il file JSON deve essere suddiviso in 2 elenchi, uno per i profili e uno per gli schemi. Di seguito è riportato un esempio di file JSON che aggiunge un nuovo profilo, modifica un profilo esistente e crea una nuova combinazione di colori:

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

Il primo elemento dell'elenco "profiles" aggiorna un profilo esistente, identificando il profilo che desidera aggiornare tramite il GUID fornito al campo "updates" (informazioni dettagliate su come ottenere il GUID sono disponibili nella sezione successiva). Il secondo elemento dell'elenco crea un nuovo profilo denominato "Cool Profile".

Nell'elenco "schemes" viene definita una nuova combinazione di colori denominata "Postmodern Tango Light" e successivamente l'utente può farvi riferimento nel file di impostazioni o in questo file JSON stesso (si noti che "Cool Profile" usa questa nuova combinazione di colori definita).

Naturalmente, se lo sviluppatore vuole aggiungere o modificare solo profili senza aggiungere combinazioni di colori (e viceversa), solo l'elenco pertinente deve essere presente e l'altro elenco può essere omesso.

Nota

Se si prevede di usare PowerShell per generare frammenti, è necessario usare -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

Se si usa VS Code per modificare il codice JSON, UTF8 è l'impostazione predefinita, ma è possibile confermarlo nella barra di stato inferiore.

GUID del profilo

Come indicato in precedenza, i GUID del profilo sono un modo per fare riferimento ai profili e consentire agli utenti di aggiornarli ed estenderli senza doversi preoccupare delle modifiche alla posizione o al nome. Gli unici profili che possono essere modificati tramite frammenti sono i profili predefiniti, il prompt dei comandi e PowerShell, nonché i profili dinamici. La fornitura di un GUID è facoltativa, tuttavia è fortemente incoraggiata.

I GUID vengono generati usando un generatore UUID versione 5 che supporta la codifica UTF-16LE senza BOM.

Il GUID dello spazio dei nomi per Terminale Windows nel caso di profili creati da plug-in e frammenti è {f65ddb7e-706b-4499-8a50-40313caf510a}. I profili creati dal team di Terminale Windows usano un GUID separato ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Questa operazione viene eseguita per rimuovere l'ambiguità dei profili creati dal team di Terminale Windows da quelli creati da plug-in o frammenti in modo che non possano mai scontrarsi accidentalmente.

Come determinare il GUID di un profilo esistente

Per determinare il GUID di un profilo da aggiornare, l'operazione dipende dal tipo di profilo:

Un profilo fornito da terze parti archiviato in un percorso standard Terminale Windows Fragment richiede il GUID dello spazio dei nomi profile &fragment, il GUID {f65ddb7e-706b-4499-8a50-40313caf510a}dello spazio dei nomi dell'applicazione e il nome del profilo. Per un frammento di profilo denominato "Git Bash" fornito dall'applicazione "Git" il GUID generato è: {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}.

Un profilo generato automaticamente da Terminale Windows richiede il GUID interno Terminale Windows {2bde4a90-d05f-401c-9492-e40884ead1d8} e il nome del profilo. Per un profilo denominato "Ubuntu" generato automaticamente durante l'installazione di WSL, il GUID risultante è: {2c4de342-38b7-51cf-b940-2309a097f518}. A differenza dell'esempio di frammento precedente non è coinvolto alcun "nome applicazione".

Generazione di un nuovo GUID del profilo

Per generare un GUID per un profilo completamente nuovo prima di distribuirlo, è possibile usare l'esempio Python 3 seguente. Genera un GUID basato sul GUID dello spazio dei nomi del profilo e del frammento per un profilo denominato "Git Bash" archiviato in una cartella standard Terminale Windows Fragments con il nome dell'applicazione "Git", che corrisponde facilmente al controllo della integrità.

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

Calcolo di un GUID per un profilo predefinito

Per calcolare un GUID per un profilo predefinito, ad esempio i profili WSL generati automaticamente, è possibile usare l'esempio Python 3 seguente. Calcola un GUID basato sul GUID dello spazio dei nomi Terminale Windows per un profilo denominato "Ubuntu" generato automaticamente per la distribuzione WSL, che corrisponde per comodità al controllo integrità.

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

Requisiti minimi per le impostazioni aggiunte con frammenti

Esistono alcune restrizioni minime su ciò che è possibile aggiungere alle impostazioni utente usando frammenti JSON:

Per i nuovi profili aggiunti tramite frammenti, il nuovo profilo deve, almeno, definire un nome per se stesso.
Per le nuove combinazioni di colori aggiunte tramite frammenti, la nuova combinazione deve definire un nome per se stessa, nonché definire ogni colore nella tabella colori (ad esempio i colori da "black" a "brightWhite" nell'immagine di esempio precedente).

Dove inserire i file di frammento JSON

Il percorso in cui posizionare i file di frammento JSON varia a seconda del metodo di installazione dell'applicazione che desidera inserirli.

Applicazioni di Microsoft Store

Per le applicazioni installate tramite Microsoft Store (o simili), l'applicazione deve dichiararsi come un'estensione dell'app. Altre informazioni su come Creare e ospitare un'estensione dell'app. La sezione necessaria viene replicata qui. Il file appxmanifest del pacchetto deve includere:

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

Cose importanti da tenere a mente:

Il campo "Name" deve essere com.microsoft.windows.terminal.settings per permettere a Terminale Windows di rilevare l'estensione.
Il campo "Id" può essere compilato come lo sviluppatore desidera.
Il campo "PublicFolder" deve avere il nome della cartella rispetto alla radice del pacchetto in cui sono archiviati i file JSON (questa cartella è in genere denominata "Pubblica", ma può essere denominata in modo diverso se lo sviluppatore lo desidera).
All'interno della cartella pubblica deve essere creata una sottodirectory denominata "Frammenti" e i file JSON devono essere archiviati in tale sottodirectory.

Applicazioni installate dal Web

Per le applicazioni installate dal Web, esistono 2 casi.

Il primo è l'installazione per tutti gli utenti del sistema. In questo caso, i file JSON devono essere aggiunti alla cartella :

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

Nel secondo caso, l'installazione è solo per l'utente corrente. In questo caso, i file JSON devono essere aggiunti alla cartella :

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

Si noti che entrambe le cartelle ProgramData e LocalAppData sono cartelle note a cui il programma di installazione deve essere in grado di accedere. In entrambi i casi, se la directory Windows Terminal\Fragments non esiste, il programma di installazione deve crearla. {app-name} deve essere univoco per l'applicazione e {file-name}.json può essere qualsiasi elemento. Il terminale leggerà tutti i file JSON in tale directory.