Windows 터미널의 JSON 조각 확장

아티클
03/21/2023

JSON 조각 확장은 애플리케이션 개발자가 새 프로필을 사용자의 설정에 추가하거나 특정 기존 프로필을 수정하기 위해 작성할 수 있는 JSON 조각입니다. 또한 새 색 구성표를 사용자의 설정에 추가하는 데 사용할 수 있습니다.

JSON 파일의 구조

JSON 파일은 프로필 및 구성표에 대해 하나씩 두 개의 목록으로 분할되어 있습니다. 새 프로필을 추가하고, 기존 프로필을 수정하고, 새 색 구성표를 만드는 json 파일의 예제는 다음과 같습니다.

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

"profiles" 목록의 첫 번째 항목은 "updates" 필드에 제공된 GUID를 통해 업데이트하려는 프로필을 식별하도록 기존 프로필을 업데이트합니다(GUID를 얻는 방법에 대한 자세한 내용은 다음 섹션에 나와 있음). 해당 목록의 두 번째 항목은 "Cool Profile"이라는 새 프로필을 만듭니다.

"schemes" 목록에는 "Postmodern Tango Light"라는 새 색 구성표가 정의되며, 나중에 사용자가 해당 설정 파일 또는 이 JSON 파일 자체에서 참조할 수 있습니다("Cool Profile"은 이 새로 정의된 색을 사용함).

물론 개발자가 색 구성표를 추가하지 않고 프로필만 추가/수정하려는 경우(및 반대의 경우) 관련 목록만 있으면 되고 다른 목록은 생략할 수 있습니다.

참고 항목

PowerShell을 사용하여 조각을 생성하려는 경우 -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

VS Code를 사용하여 JSON을 편집하는 경우 UTF8이 기본값이지만 아래의 상태 표시줄에서 확인할 수 있습니다.

프로필 GUID

앞에서 설명한 대로 프로필 GUID는 프로필을 참조하고 사용자가 위치 또는 이름 변경에 대해 걱정하지 않고 이러한 프로필을 업데이트하고 확장할 수 있는 방법입니다. 조각을 통해 수정할 수 있는 유일한 프로필은 기본 프로필, 명령 프롬프트 및 PowerShell과 동적 프로필입니다. GUID를 제공하는 것은 선택 사항이지만 강력히 권장됩니다.

GUID는 BOM이 없는 UTF-16LE 인코딩을 지원하는 버전 5 UUID 생성기를 사용하여 생성됩니다.

플러그 인 및 조각에서 만든 프로필의 경우 Windows 터미널에 대한 네임스페이스 GUID는 {f65ddb7e-706b-4499-8a50-40313caf510a}입니다. Windows 터미널 팀에서 만든 프로필은 별도의 GUID({2bde4a90-d05f-401c-9492-e40884ead1d8})를 사용합니다. 이는 Windows 터미널 팀에서 만든 프로필을 플러그 인 또는 조각에서 만든 프로필과 명확히 구분하여 실수로 충돌하지 않도록 하기 위해 수행됩니다.

기존 프로필의 GUID를 확인하는 방법

업데이트할 프로필의 GUID를 확인하려면 프로필의 종류에 따라 달라집니다.

표준 Windows 터미널 조각 위치에 저장된 타사에서 제공하는 프로필에는 프로필 및 조각 네임스페이스 GUID, 애플리케이션 네임스페이스 GUID {f65ddb7e-706b-4499-8a50-40313caf510a}및 프로필 이름이 필요합니다. 'Git' 애플리케이션에서 제공하는 'Git Bash'라는 프로필 조각의 경우 생성된 GUID는 {2ece5bfe-50ed-5f3a-ab87-5cd4baafed2b}입니다.

Windows 터미널에서 자동으로 생성된 프로필에는 Windows 터미널 내부 GUID({2bde4a90-d05f-401c-9492-e40884ead1d8}) 및 프로필 이름이 필요합니다. WSL 설치 중에 자동으로 생성된 'Ubuntu'라는 프로필의 경우 결과 GUID는 {2c4de342-38b7-51cf-b940-2309a097f518}입니다. 이전 조각 예제와 달리 '애플리케이션 이름'이 포함되지 않습니다.

새 프로필 GUID 생성

배포하기 전에 완전히 새로운 프로필에 대한 GUID를 생성하려면 다음 Python 3 예제를 사용할 수 있습니다. 'Git' 애플리케이션 이름 아래의 표준 Windows 터미널 Fragments 폴더에 저장된 'Git Bash'라는 프로필에 대한 프로필 및 조각 네임스페이스 GUID를 기반으로 GUID를 생성하여 온전성 검사 편리하게 일치합니다.

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

기본 제공 프로필에 대한 GUID 계산

자동으로 생성된 WSL 프로필과 같은 기본 제공 프로필에 대한 GUID를 계산하려면 다음 Python 3 예제를 사용할 수 있습니다. WSL 배포에 대해 자동으로 생성된 'Ubuntu'라는 프로필에 대한 Windows 터미널 네임스페이스 GUID를 기반으로 하는 GUID를 계산하여 온전성 검사와 편리하게 일치시킵니다.

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

조각으로 추가된 설정에 대한 최소 요구 사항

JSON 조각을 사용하여 사용자 설정에 추가할 수 있는 항목에 대한 몇 가지 최소한의 제한 사항이 있습니다.

조각을 통해 추가된 새 프로필의 경우 해당 새 프로필은 최소한 자체 이름을 정의해야 합니다.
조각을 통해 추가된 새 색 구성표의 경우 해당 새 색 구성표는 자체 이름을 정의하고 색 테이블의 모든 색을 정의해야 합니다(예: 위의 예제 이미지에서 "black"에서 "brightWhite"까지의 색).

JSON 조각 파일을 배치할 위치

JSON 조각 파일을 배치하는 위치는 배치하려는 애플리케이션의 설치 방법에 따라 달라집니다.

Microsoft Store 애플리케이션

Microsoft Store(또는 이와 비슷한 스토어)를 통해 설치된 애플리케이션의 경우 해당 애플리케이션에서 자체를 앱 확장으로 선언해야 합니다. 앱 확장을 만들고 호스트하는 방법에 대해 자세히 알아보세요. 필요한 섹션이 여기에 복제됩니다. 패키지의 appxmanifest 파일에는 다음이 포함되어야 합니다.

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

주의해야 할 주요 사항은 다음과 같습니다.

Windows 터미널에서 확장을 검색할 수 있으려면 "Name" 필드가 com.microsoft.windows.terminal.settings여야 합니다.
"Id" 필드는 개발자가 원하는 대로 채울 수 있습니다.
"PublicFolder" 필드에는 JSON 파일이 저장되는 패키지 루트를 기준으로 하는 폴더 이름이 있어야 합니다(이 폴더는 일반적으로 "Public"이라고 하지만, 개발자가 원하는 경우 다른 이름으로 지정할 수 있음).
"Fragments"라는 하위 디렉터리가 Public 폴더 내에 만들어지고, JSON 파일은 해당 하위 디렉터리에 저장되어야 합니다.

웹에서 설치되는 애플리케이션

웹에서 설치되는 애플리케이션의 경우 두 가지 사례가 있습니다.

첫 번째 사례는 시스템의 모든 사용자용으로 설치하는 것입니다. 이 경우 JSON 파일을 다음 폴더에 추가해야 합니다.

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

두 번째 사례는 현재 사용자용으로만 설치하는 것입니다. 이 경우 JSON 파일을 다음 폴더에 추가해야 합니다.

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

ProgramData 및 LocalAppData 폴더는 모두 설치 관리자에서 액세스할 수 있어야 하는 알려진 폴더입니다. 두 사례 모두 Windows Terminal\Fragments 디렉터리가 없으면 설치 관리자에서 이 디렉터리를 만들어야 합니다. {app-name}은 애플리케이션에 고유해야 하고, {file-name}.json는 아무것이 될 수 있습니다. 터미널은 해당 디렉터리의 모든 .json 파일을 읽습니다.