Extensiones de fragmentos JSON en Terminal Windows

Las extensiones de fragmentos 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 modificar determinados perfiles existentes. Úselos para agregar nuevas combinaciones de colores a la configuración de los usuarios.

Estructura de los archivos JSON

Divida el archivo JSON en dos listas: una para perfiles y otra para esquemas. 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 "profiles" lista actualiza un perfil existente. Identifica el perfil que quiere actualizar a través del GUID proporcionado al "updates" campo (consulte la sección siguiente para obtener más información sobre cómo obtener el GUID). El segundo elemento de esa lista crea un nuevo perfil denominado "Perfil de acceso esporádico".

En la "schemes" lista, se define una nueva combinación de colores denominada "Postmodern Tango Light". Puede hacer referencia a esta combinación de colores en el archivo de configuración o en el mismo archivo JSON (note que "Perfil Fresco" usa esta combinación de colores recién definida).

Si solo desea agregar o modificar perfiles sin agregar combinaciones de colores, o viceversa, incluya solo la lista pertinente y omita la otra lista.

# 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

GUID de perfil

Como se indicó anteriormente, los GUID de perfil son una manera de hacer referencia a perfiles y permitir a los usuarios actualizarlos y ampliarlos sin preocuparse por los cambios de ubicación o nombre. Solo puede modificar los perfiles predeterminados, Símbolo del sistema y PowerShell, así como los perfiles dinámicos a través de fragmentos. Proporcionar un GUID es opcional, pero se recomienda encarecidamente.

El generador UUID de la versión 5 crea los GUID y admite la codificación UTF-16LE sin BOM.

El GUID del espacio de nombres para Terminal Windows en caso de 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}). Esta separación desambigua los perfiles creados por el equipo de Terminal Windows a partir de perfiles creados por complementos o fragmentos para que nunca entren en conflicto accidentalmente.

Cómo determinar el GUID de un perfil existente

Para determinar el GUID de un perfil que se va a actualizar, tenga en cuenta qué tipo de perfil es:

Un perfil enviado por un tercero y almacenado en una ubicación estándar del fragmento de terminal Windows requiere el GUID de espacio de nombres de perfil y fragmento, el GUID {f65ddb7e-706b-4499-8a50-40313caf510a}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 {2bde4a90-d05f-401c-9492-e40884ead1d8} interno de Terminal Windows 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 de 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, use el siguiente ejemplo de Python 3. Genera un GUID basado en el GUID del espacio de nombres del perfil y fragmento para un perfil denominado "Git Bash", almacenado en una carpeta estándar de fragmentos del Terminal de Windows bajo el nombre de la aplicación "Git", coincidiendo convenientemente con la verificació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, use 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 integridad.

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

Algunas restricciones mínimas se aplican a lo que puede agregar a la configuración del usuario mediante fragmentos JSON:

• Para los nuevos perfiles agregados a través de fragmentos, el nuevo perfil debe 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í mismo y definir todos los colores de la tabla de colores (es decir, los colores "negros" 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 los agrega.

Aplicaciones de Microsoft Store

En el caso de las aplicaciones instaladas a través de Microsoft Store (o similares), 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 clave que se deben tener en cuenta:

• El "Name" campo debe ser com.microsoft.windows.terminal.settings para Terminal Windows para detectar la extensión.
• El "Id" campo se puede rellenar como desee.
• El "PublicFolder" campo 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úblico", pero se puede denominar algo más).
• Dentro de la carpeta pública, cree un subdirectorio denominado "Fragmentos" y almacene los archivos JSON en ese subdirectorio.

Aplicaciones instaladas desde la web

En el caso de las aplicaciones instaladas desde la web, tenga en cuenta dos casos.

El primer caso es que la instalación es para todos los usuarios del sistema. En este caso, agregue los archivos JSON a la carpeta :

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

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

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

Tenga en cuenta que las ProgramData carpetas y LocalAppData son carpetas conocidas a las que debe tener acceso el instalador. Si el Windows Terminal\Fragments directorio 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 lee todos los archivos .json en ese directorio.

Distribución de recursos multimedia con la extensión de fragmento

A partir de Terminal Windows 1.24, las extensiones de fragmento pueden distribuir recursos multimedia como imágenes y sombreadores de píxeles que se usarán con las iconpropiedades , backgroundImageexperimental.pixelShaderPath y experimental.pixelShaderImagePath en perfiles y acciones.

Versiones anteriores de las direcciones URL web compatibles con Terminal para icon y backgroundImage. Esas versiones seguirán cargando recursos de dirección URL web a perpetuidad. Las versiones más recientes ya no tendrán acceso a las direcciones URL web, pero en su lugar buscarán en el directorio que contiene el archivo de fragmento.

Si desea mantener la compatibilidad con todas las versiones disponibles de Terminal, puede colocar cualquier recurso web en el mismo directorio que los .json archivos.

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

Puede confiar en los siguientes comportamientos de compatibilidad: