Extensiones de fragmentos JSON en Terminal Windows

Artículo
03/21/2023

Las extensiones de fragmento JSON son fragmentos de código JSON que los desarrolladores de aplicaciones pueden escribir para agregar nuevos perfiles a la configuración de los usuarios o incluso para modificar determinados perfiles existentes. También se pueden usar para agregar nuevas combinaciones de color a la configuración de los usuarios.

Estructura de los archivos JSON

El archivo JSON debe dividirse en dos listas: una para los perfiles y otra para las combinaciones. Este es un ejemplo de un archivo JSON que agrega un nuevo perfil, modifica un perfil existente y crea una nueva combinación de colores:

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

El primer elemento de la lista "profiles" actualiza un perfil existente e identifica el perfil que se va a actualizar a través del GUID que se ha proporcionado al campo "updates" (los detalles sobre cómo obtener el GUID se encuentran en la sección siguiente). El segundo elemento de esa lista crea un nuevo perfil denominado "Perfil esporádico".

En la lista "schemes", se define una nueva combinación de colores denominada "Postmodern Tango Light" y, posteriormente, el usuario puede hacer referencia a ella en su archivo de configuración o en el propio archivo JSON (tenga en cuenta que el "Perfil esporádico" usa esta combinación de colores recién definida).

Por supuesto, si el desarrollador solo quiere agregar o modificar perfiles sin agregar combinaciones de colores (y viceversa), solo debe estar presente la lista pertinente y se puede omitir la otra lista.

Nota

Si tiene previsto usar PowerShell para generar fragmentos, debe usar -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 usa VS Code para editar el código JSON, UTF8 es el valor predeterminado, pero puede confirmarlo en la barra de estado inferior.

GUID de perfil

Como se ha indicado anteriormente, los GUID de perfil son una manera de hacer referencia a los perfiles y permitir a los usuarios actualizarlos y ampliarlos sin preocuparse por los cambios de ubicación o nombre. Los únicos perfiles que se pueden modificar a través de fragmentos son los perfiles predeterminados, el símbolo del sistema y PowerShell, así como los perfiles dinámicos. Proporcionar un GUID es opcional, pero es muy recomendable hacerlo.

Los GUID se generan mediante un generador UUID de la versión 5, que admite la codificación UTF-16LE sin BOM.

El GUID del espacio de nombres de Terminal Windows en el caso de los perfiles creados por complementos y fragmentos es {f65ddb7e-706b-4499-8a50-40313caf510a}. Los perfiles creados por el equipo de Terminal Windows usan un GUID independiente ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Esto se hace para desambiguar de los perfiles creados por el equipo de Terminal Windows de los perfiles creados por complementos o fragmentos, de modo que nunca entren en conflicto accidentalmente.

Cómo determinar el GUID de un perfil existente

Determinar el GUID de un perfil que se va a actualizar depende del tipo de perfil que sea:

Un perfil enviado por un tercero almacenado en una ubicación estándar del fragmento de Terminal Windows requiere el GUID del espacio de nombres de perfil y fragmento {f65ddb7e-706b-4499-8a50-40313caf510a}, el GUID del espacio de nombres de la aplicación y el nombre del perfil. Para un fragmento de perfil denominado "Git Bash" proporcionado por la aplicación "Git", el GUID generado es: {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}.

Un perfil generado automáticamente por Terminal Windows requiere el GUID interno de Terminal Windows {2bde4a90-d05f-401c-9492-e40884ead1d8} y el nombre del perfil. Para un perfil denominado "Ubuntu" generado automáticamente durante la instalación de WSL, el GUID resultante es: {2c4de342-38b7-51cf-b940-2309a097f518}. A diferencia del ejemplo del fragmento anterior, no hay ningún "nombre de aplicación" implicado.

Generación de un nuevo GUID de perfil

Para generar un GUID para un perfil completamente nuevo antes de distribuirlo, puede usar el siguiente ejemplo de Python 3. Genera un GUID basado en el GUID del espacio de nombres de perfil y fragmento para un perfil denominado "Git Bash" almacenado en una carpeta estándar de fragmentos del Terminal Windows bajo el nombre de la aplicación "Git", que coincide convenientemente con la comprobación de integridad.

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

Cálculo de un GUID para un perfil integrado

Para calcular un GUID para un perfil integrado, como los perfiles de WSL generados automáticamente, puede usar el siguiente ejemplo de Python 3. Calcula un GUID basado en el GUID del espacio de nombres de Terminal Windows para un perfil denominado "Ubuntu" que se generó automáticamente para la distribución de WSL, que coincide convenientemente con la comprobación de estado.

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

Requisitos mínimos para la configuración agregada con fragmentos

Hay algunas restricciones mínimas en los elementos que se pueden agregar a la configuración de usuario mediante fragmentos JSON:

En el caso de los nuevos perfiles agregados a través de fragmentos, el nuevo perfil debe, como mínimo, definir un nombre para sí mismo.
Para las nuevas combinaciones de colores agregadas a través de fragmentos, la nueva combinación de colores debe definir un nombre para sí misma, así como definir cada color de la tabla de colores (es decir, los colores de "black" a "brightWhite" en la imagen de ejemplo anterior).

Dónde colocar los archivos de fragmentos JSON

La ubicación para colocar los archivos de fragmentos JSON varía en función del método de instalación de la aplicación que quiere colocarlos.

Aplicaciones de Microsoft Store

En cuanto a las aplicaciones instaladas a través Microsoft Store (o similar), la aplicación debe declararse como una extensión de aplicación. Obtenga más información sobre cómo Crear y hospedar una extensión de aplicación. La sección necesaria se replica aquí. El archivo appxmanifest del paquete debe incluir:

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

Aspectos a tener en cuenta:

El campo "Name" debe ser com.microsoft.windows.terminal.settings para que Terminal Windows pueda detectar la extensión.
El campo "Id" se puede rellenar como desee el desarrollador.
El campo "PublicFolder" debe tener el nombre de la carpeta (en relación con la raíz del paquete) donde se almacenan los archivos JSON; esta carpeta normalmente se denomina "Pública", pero se puede denominar de forma diferente si el desarrollador así lo desea.
En la carpeta pública, debe crear un subdirectorio denominado "Fragmentos" y los archivos JSON deben almacenarse en ese subdirectorio.

Aplicaciones instaladas desde la web

En el caso de las aplicaciones instaladas desde la web, hay dos casos.

El primero es que la instalación es accesible para todos los usuarios del sistema. En este caso, los archivos JSON deben agregarse a la carpeta:

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

En el segundo caso, la instalación es solo para el usuario actual. En este caso, los archivos JSON deben agregarse a la carpeta:

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

Tenga en cuenta que las carpetas ProgramData y LocalAppData son carpetas conocidas a las que el instalador debe poder acceder. En cualquier caso, si el directorio Windows Terminal\Fragments no existe, el instalador debe crearlo. {app-name} debe ser único para la aplicación y {file-name}.json puede ser cualquier cosa: el terminal leerá todos los archivos .json de ese directorio.

Compartir a través de