Extensões de fragmento JSON no Terminal do Windows

As extensões de fragmento JSON são trechos de JSON que os desenvolvedores de aplicativos podem escrever para adicionar novos perfis às configurações dos usuários ou até mesmo modificar determinados perfis existentes. Use-os para adicionar novos esquemas de cores às configurações dos usuários.

Estrutura dos arquivos JSON

Divida o arquivo JSON em duas listas: uma para perfis e outra para esquemas. Aqui está um exemplo de um arquivo JSON que adiciona um novo perfil, modifica um perfil existente e cria um novo esquema de cores:

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

O primeiro item da "profiles" lista atualiza um perfil existente. Ele identifica o perfil que deseja atualizar através do GUID fornecido ao "updates" campo (consulte a próxima seção para obter detalhes sobre como obter o GUID). O segundo item dessa lista cria um novo perfil chamado "Cool Profile".

Na lista "schemes", está definido um novo esquema de cores chamado "Postmodern Tango Light". Você pode fazer referência a esse esquema de cores em seu arquivo de configurações ou no próprio arquivo JSON (observe que "Cool Profile" usa esse esquema de cores recém-definido).

Se você quiser apenas adicionar ou modificar perfis sem adicionar esquemas de cores, ou vice-versa, inclua apenas a lista relevante e omita a outra 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

GUIDs de perfil

Como dito anteriormente, os GUIDs de perfil são uma maneira de referenciar perfis e permitir que os usuários os atualizem e estendam sem se preocupar com mudanças de localização ou nome. Você pode modificar apenas os perfis padrão, Prompt de Comando e PowerShell, bem como perfis dinâmicos por meio de fragmentos. Fornecer um GUID é opcional, mas fortemente encorajado.

O gerador UUID Versão 5 cria os GUIDs e suporta codificação UTF-16LE sem BOM.

O GUID do namespace para o Terminal do Windows no caso de perfis criados por plug-ins e fragmentos é {f65ddb7e-706b-4499-8a50-40313caf510a}. Os perfis criados pela Equipe de Terminal do Windows usam um GUID separado ({2bde4a90-d05f-401c-9492-e40884ead1d8}). Essa separação desambigua perfis criados pela Equipe de Terminal do Windows de perfis criados por plug-ins ou fragmentos para que eles nunca colidam acidentalmente.

Como determinar o GUID de um perfil existente

Para determinar o GUID de um perfil a ser atualizado, considere que tipo de perfil é:

Um perfil enviado por terceiros e armazenado em um local padrão de Windows Terminal Fragment requer o GUID {f65ddb7e-706b-4499-8a50-40313caf510a} do namespace do perfil e do fragmento, o GUID do namespace do aplicativo e o nome do perfil. Para um fragmento de perfil chamado 'Git Bash' fornecido pelo aplicativo 'Git', o GUID gerado é {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}.

Um perfil gerado automaticamente pelo Terminal do Windows requer o GUID {2bde4a90-d05f-401c-9492-e40884ead1d8} interno do Terminal do Windows e o nome do perfil. Para um perfil chamado 'Ubuntu' gerado automaticamente durante a instalação do WSL, o GUID resultante é {2c4de342-38b7-51cf-b940-2309a097f518}. Ao contrário do exemplo de fragmento anterior, não há nenhum nome de aplicativo envolvido.

Gerando um novo GUID de perfil

Para gerar um GUID para um perfil completamente novo antes de distribuí-lo, use o seguinte exemplo do Python 3. Ele gera um GUID baseado no GUID de namespace de perfil e fragmento para um perfil chamado 'Git Bash' armazenado em uma pasta padrão de Fragmentos de Terminal do Windows sob o nome do aplicativo 'Git', combinando convenientemente com a verificação de sanidade.

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

Calculando um GUID para um perfil incorporado

Para calcular um GUID para um perfil interno, como os perfis WSL gerados automaticamente, use o seguinte exemplo do Python 3. Ele calcula um GUID baseado no GUID do namespace do Terminal do Windows para um perfil chamado 'Ubuntu' que foi gerado automaticamente para a distribuição WSL, correspondendo convenientemente à verificação de sanidade.

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 configurações adicionadas com fragmentos

Algumas restrições mínimas se aplicam ao que você pode adicionar às configurações do usuário usando fragmentos JSON:

• Para novos perfis adicionados através de fragmentos, o novo perfil deve definir um nome para si mesmo.
• Para novos esquemas de cores adicionados através de fragmentos, o novo esquema de cores deve definir um nome para si mesmo e definir cada cor na tabela de cores (ou seja, as cores "preto" através de "brightWhite" na imagem de exemplo anterior).

Onde colocar os arquivos de fragmento JSON

O local para colocar os arquivos de fragmento JSON varia dependendo do método de instalação do aplicativo que os adiciona.

Aplicativos da Microsoft Store

Para aplicativos instalados por meio da Microsoft Store (ou similar), o aplicativo deve se declarar uma extensão de aplicativo. Saiba mais sobre como criar e hospedar uma extensão de aplicativo. A seção necessária é replicada aqui. O arquivo appxmanifest do pacote deve 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>

Principais aspetos a ter em conta:

• O "Name" campo deve ser com.microsoft.windows.terminal.settings para o Terminal do Windows detetar a extensão.
• O "Id" campo pode ser preenchido como desejar.
• O "PublicFolder" campo deve ter o nome da pasta, relativo à raiz do pacote, onde você armazena os arquivos JSON (esta pasta é normalmente chamada de "Pública", mas pode ser chamada de outra coisa).
• Dentro da pasta pública, crie um subdiretório chamado "Fragmentos" e armazene os arquivos JSON nesse subdiretório.

Aplicações instaladas a partir da Web

Para aplicações instaladas a partir da Web, considere dois casos.

O primeiro caso é que a instalação é para todos os usuários no sistema. Nesse caso, adicione os arquivos JSON à pasta:

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

O segundo caso é que a instalação é apenas para o usuário atual. Nesse caso, adicione os arquivos JSON à pasta:

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

Observe que ambas as ProgramData pastas e LocalAppData são pastas conhecidas que o instalador deve acessar. Se o Windows Terminal\Fragments diretório não existir, o instalador deve criá-lo. O {app-name} deve ser exclusivo para o seu aplicativo e o {file-name}.json pode ser qualquer coisa - o terminal lê todos os arquivos .json nesse diretório.

Distribuindo recursos de mídia com sua extensão de fragmento

A partir do Terminal 1.24 do Windows, as extensões de fragmento podem distribuir recursos de mídia, como imagens e sombreadores de pixel, para serem usados com o icon, backgroundImageexperimental.pixelShaderPath e propriedades em perfis e experimental.pixelShaderImagePath ações.

Versões anteriores do Terminal suportavam URLs da Web para icon e backgroundImage. Essas versões continuarão a carregar recursos de URL da Web para sempre. As versões mais recentes não acessarão mais URLs da Web, mas procurarão no diretório que contém o arquivo de fragmento.

Se desejar manter a compatibilidade com todas as versões disponíveis do Terminal, poderá colocar quaisquer recursos Web no mesmo diretório que os seus .json ficheiros.

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

Você pode confiar nos seguintes comportamentos de compatibilidade: