Extensões de fragmento JSON no Terminal do Windows

Extensões de fragmento JSON são snippets de JSON que os desenvolvedores de aplicativos podem gravar 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 por meio do GUID fornecido para o "updates" campo (consulte a próxima seção para obter detalhes sobre como obter o GUID). O segundo item nessa lista cria um novo perfil chamado "Perfil Bacana".

Na lista "schemes", um novo esquema de cores chamado "Postmodern Tango Light" é estabelecido. Você pode referenciar esse esquema de cores no arquivo de configurações ou nesse 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

Conforme indicado anteriormente, os GUIDs de perfil são uma maneira de referenciar perfis e permitir que os usuários os atualizem e os estendam sem se preocupar com alterações de local ou nome. Você pode modificar apenas os perfis padrão, o Prompt de Comando e o PowerShell, bem como perfis dinâmicos por meio de fragmentos. Fornecer um GUID é opcional, mas altamente incentivado.

O gerador UUID da versão 5 cria os GUIDs e dá suporte à codificação UTF-16LE sem BOM.

O GUID do namespace para o Windows Terminal em caso de perfis criados por plugins 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 a partir 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 ele é:

Um perfil enviado por terceiros e armazenado em um local padrão de Fragment do Windows Terminal requer o GUID do namespace do perfil e fragmento {f65ddb7e-706b-4499-8a50-40313caf510a}, 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 com base 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', correspondendo convenientemente à 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 embutido

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 com base 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 consistência.

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 definiçõ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 por meio de fragmentos, o novo perfil deve definir um nome para si mesmo.
• Para novos esquemas de cores adicionados por meio 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 "black" por meio 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 semelhante), o aplicativo deve declarar-se como 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 coisas a serem observadas:

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

Aplicativos instalados na Web

Para aplicativos instalados na 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 as pastas ProgramData e LocalAppData são diretórios conhecidos que o instalador deve acessar. Se o Windows Terminal\Fragments diretório não existir, o instalador deverá criá-lo. O {app-name} deve ser exclusivo para seu aplicativo e pode {file-name}.json 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 Windows Terminal 1.24, as extensões de fragmentos podem distribuir recursos de mídia, como imagens e sombreadores de pixels, para serem usados com as propriedades icon, backgroundImage e experimental.pixelShaderPath em perfis e ações experimental.pixelShaderImagePath.

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

Se você quiser manter a compatibilidade com todas as versões disponíveis do Terminal, poderá colocar todos os recursos da Web no mesmo diretório que seus .json arquivos.

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

Você pode contar com os seguintes comportamentos de compatibilidade: