Extensões de fragmento JSON no Terminal do Windows

  • Artigo

Extensões de fragmento JSON são snippets 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. Eles também podem ser usados para adicionar novos esquemas de cores às configurações dos usuários.

Estrutura dos arquivos JSON

O arquivo JSON deve ser dividido em duas listas, uma para perfis e outra para esquemas. Veja um exemplo de arquivo JSON que adiciona um novo perfil, modifica um perfil existente e cria um 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 na lista "profiles" atualiza um perfil existente, identificando o perfil que deseja atualizar por meio do GUID fornecido para o campo "updates" (os detalhes sobre como obter o GUID estão na próxima seção). O segundo item nessa lista cria um perfil chamado "Perfil Frio".

Na lista "schemes", um novo esquema de cores chamado "Postmodern Tango Light" é definido e pode ser referenciado posteriormente pelo usuário no arquivo de configurações ou no próprio arquivo JSON (observe que "Perfil Frio" usa esse esquema de cores recém-definido).

Se o desenvolvedor quiser apenas adicionar/modificar perfis sem adicionar esquemas de cores (e vice-versa), somente a lista relevante precisará estar presente, e a outra lista poderá ser omitida.

Observação

Se você planejar usar o PowerShell para gerar fragmentos, precisará 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

Se você estiver usando o VS Code para editar o JSON, UTF8 é o padrão, mas você pode confirmar isso na barra de status inferior.

GUIDs de perfil

Como mencionado anteriormente, os GUIDs de perfil são uma forma de referenciar perfis e permitir que os usuários os atualizem e os estendam sem se preocupar com alterações no nome ou na localização. Os únicos perfis que podem ser modificados por meio de fragmentos são os perfis padrão, do Prompt de Comando e do PowerShell, bem como os perfis dinâmicos. Fornecer um GUID é opcional, porém, altamente incentivado.

Os GUIDs são gerados usando um gerador de UUID versão 5 que dá suporte à 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 do Terminal do Windows usam um GUID ({2bde4a90-d05f-401c-9492-e40884ead1d8}) separado. Isso é feito para eliminar a ambiguidade de perfis criados pela Equipe de Terminal do Windows em relação a perfis criados por plug-ins ou fragmentos para que eles nunca possam colidir acidentalmente.

Como determinar o GUID de um perfil existente

Determinar o GUID de um perfil a ser atualizado depende do tipo do perfil:

Um perfil enviado por terceiros armazenado em um local padrão do Fragmento do Terminal do Windows requer o GUID {f65ddb7e-706b-4499-8a50-40313caf510a} do namespace de perfil e 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 interno do Terminal do Windows {2bde4a90-d05f-401c-9492-e40884ead1d8} e o nome do perfil. Em 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 do aplicativo' envolvido.

Como gerar um GUID do novo perfil

Para gerar um GUID para um perfil completamente novo antes de distribuí-lo, você pode usar o exemplo do Python 3 a seguir. Ele gera um GUID com base no GUID do perfil e do namespace de fragmento para um perfil chamado "Git Bash" armazenado em uma pasta padrão de Fragmentos de Terminal do Windows com o nome do aplicativo "Git", correspondendo convenientemente à verificação de integridade.

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

Como calcular um GUID de um perfil interno

Para calcular um GUID de um perfil interno, como os perfis de WSL gerados automaticamente, você pode usar o exemplo do Python 3 a seguir. 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, que corresponde convenientemente à verificação de integridade.

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

Há algumas restrições mínimas sobre o que pode ser adicionado às configurações do usuário usando fragmentos JSON:

  • Para novos perfis adicionados por meio de fragmentos, o novo perfil deve, no mínimo, definir um nome para si mesmo.
  • Para novos esquemas de cores adicionados por meio de fragmentos, o novo esquema de cores precisa definir um nome para si mesmo, bem como definir todas as cores na tabela de cores (ou seja, as cores "black" até "brightWhite" na imagem de exemplo acima).

Onde colocar os arquivos de fragmento JSON

O local onde colocar os arquivos de fragmento JSON varia dependendo do método de instalação do aplicativo que deseja colocá-los.

Aplicativos da Microsoft Store

Para aplicativos instalados por meio da Microsoft Store (ou semelhantes), o aplicativo deve se declarar 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>

Aspectos importantes a observar:

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

Aplicativos instalados da Web

Para aplicativos instalados da Web, há dois casos.

No primeiro, a instalação é para todos os usuários no sistema. Nesse caso, os arquivos JSON devem ser adicionados à pasta :

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

No segundo caso, a instalação é somente para o usuário atual. Nesse caso, os arquivos JSON devem ser adicionados à pasta :

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

Observe que as pastas ProgramData e LocalAppData são pastas conhecidas que o instalador deve ser capaz de acessar. Nos dois casos, se o diretório Windows Terminal\Fragments não existir, o instalador deverá criá-lo. O {app-name} deve ser exclusivo para seu aplicativo e o {file-name}.json pode ser qualquer coisa – o terminal lerá todos os arquivos .json nesse diretório.