익스텐션 게시하기

익스텐션을 완성한 경우에, 다른 사람들이 익스텐션을 찾고 다운로드하고 사용할 수 있게 VS Code Extension Marketplace에 게시 할 수 있습니다. 다른 방법으로, 익스텐션을 설치 가능한 VSIX 포맷의 패키지로 만들어 다른 사람들과 공유 할 수 있습니다.

이번 주제에서 다루는 내용:

VS Code 익스텐션을 관리 하는 CLI 툴인 vsce를 사용하기
익스텐션을 패키징, 게시 그리고 게시 취소하기.
익스텐션 게시를 위한 publisherId 등록 하기

vsce

vsce는 ‘Visual Studio Code Extension’의 줄임말로 VS Code 익스텐션을 패키징, 게시, 관리하는 커맨드라인 도구 입니다.

설치

Node.js가 설치되어 있는지 확인 후 다음을 실행하십시오:

npm install -g vsce

사용예시

vsce를 사용하여 익스텐션을 쉽게 패키징하고 게시 할 수 있습니다.

$ cd myExtension
$ vsce package
# myExtension.vsix generated
$ vsce publish
# <publisherID>.myExtension published to VS Code MarketPlace

또한 vsce로 익스텐션 검색, 메타데이터 검색, 게시 취소를 할 수 있습니다. 가능한 모든 vsce 명령어를 확인하려면, vsce --help 를 실행하십시오.

익스텐션 게시하기

메모 보안 문제로 인해, vsce는 사용자 제공 SVG 이미지를 포함하는 익스텐션을 게시 할 수 없습니다.

게시 도구는 다음 상황들을 만족해야합니다.

package.json에 제공되는 아이콘은 SVG 가 아니어야 합니다.
package.json에 쓰이는 뱃지는 검증된 뱃지 제공자로부터 온 SVG만 허용 됩니다.
README.md와 CHANGELOG.md의 이미지 URL은 https URL로 제공되어야 합니다.
README.md와 CHANGELOG.md의 이미지는 검증된 뱃지 제공자로부터 온 SVG만 허용 됩니다.

Visual Studio Code 는 마켓플레이스 서비스를 위해 Azure DevOps를 사용합니다. 이는 익스텐션의 검증, 호스팅, 관리가 Azure DevOps를 통해서 행해진다는것을 의미합니다 .

vsce는 Personal Access Tokens를 사용해야만 익스텐션을 게시할 수 있습니다. 익스텐션 게시를 위해서 적어도 한개 이상을 생성하십시오.

Personal Access Token 생성하기

먼저, Azure DevOps organization가 있는지 확인하십시오.

예시에서 vscode를 organization 의 이름으로 사용합니다. 여러분의 organization의 홈페이지에서 (예를 들면: https://dev.azure.com/vscode), 프로필 이미지 옆의 유저 설정 메뉴를 열고 Personal access tokens를 선택하십시오.

Personal settings menu

Personal Access Tokens 페이지에서, New Token을 클릭하여 새로운 Personal Access Token을 생성하십시오:

Create personal access token

Personal Access Token에 이름을 부여하고, 모든 organization에서 접근 가능하게 한 다음, custom defined 범위를 선택하여 Show all scopes를 클릭하십시오. 필요한 경우 만료기간을 1년으로 연장하십시오.

Personal access token details

마지막으로, 가능한 범위들을 Marketplace를 찾을 때까지 아래로 스크롤하여 Acquire 과 Manage 모두 선택하십시오:

Personal access token details

Create를 선택하면 이제 새로운 Personal Access Token을 생성 할 것입니다. 토큰을 Copy 하십시오. 게시자를 생성할때 필요합니다.

게시자 생성하기

게시자 는 Visual Studio Code 마켓플레이스에 익스텐션을 게시할 수 있는 신분입니다. 모든 익스텐션은 package.json 파일에 publisher 이름이 포함되어있어야만 합니다.

Personal Access Token을 만들고 나면, 여러분은 vsce를 사용하여 새로운 게시자를 생성 할 수 있습니다.

vsce create-publisher (publisher name)

vsce는 현재 게시자의 이후 사용을 위해 제공된 Personal Access Token 정보를 기억할 것입니다.

메모 다음 섹션에서 설명하는 대로 게시자를 마켓플레이스 게시자 관리 페이지에서 생성한 다음 vsce를 통해서 로그인 하는 방법도 있습니다 .

게시자로 로그인하기

이미 게시자를 생성했고 vsce에서 사용하려는 경우:

vsce login (publisher name)

create-publisher 명령과 유사하게, vsce는 사용자의 Personal Access Token을 요구하고 이후의 명령어를 위해 기억할 것입니다.

한편, 사용자의 Personal Access Token을 추가 파라미터 -p <token>를 사용하여 입력 할 수도 있습니다.

vsce publish -p <token>

익스텐션 버전의 관리

사용자는 익스텐션을 게시할때 SemVer에 호환 되는 버전을 표기하는 것 : major, minor, patch 으로 버전 넘버를 관리 할 수 있습니다.

예를 들어, 만약 익스텐션의 버전을 1.0.0 에서 1.1.0 으로 업데이트 하려는 경우, minor로 표기하십시오:

vsce publish minor

이는 익스텐션을 게시 하기 전에, 익스텐션의 package.json [version] 항목을 수정할 것입니다.

커맨드 라인에서 온전한 SemVer에 호환 되는 버전을 표기하는 방법도 있습니다.

vsce publish 2.0.1

메모 : 만약 vsce publish가 깃 저장소에서 실행 되는 경우, 태그가 npm-version으로 달린 버전 커밋이 생성될 것입니다. 기본 커밋 메세지는 익스텐션의 버전이지만, 다른 커밋 메세지를 -m 플래그를 이용하여 사용 할 수 있습니다. ( 현재 버전은 커밋 메세지에서 %s를 통해 참조 가능합니다.)

익스텐션 게시 취소하기

vsce 에서 익스텐션 ID publisher.extension을 통해 익스텐션 게시를 취소할 수 있습니다.

vsce unpublish (publisher name).(extension name)

메모: 익스텐션 게시를 취소할 때, 마켓플레이스에서 수집된 익스텐션 통계가 제거 될 것입니다. 경우에 따라 퍼블리싱을 취소하기보단 업데이트 하십시오.

익스텐션 패키징하기

만약 익스텐션을 로컬 VS Code에서 설치 후 테스트 하려 하거나 혹은 VS Code 마켓플레이스에 게시 하지 않고 익스텐션을 배포 하고자 하는 경우, 익스텐션을 패키징 하는 방법을 선택 하십시오. vsce 는 사용자가 쉽게 설치 할 수 있는 VSIX 파일로 익스텐션을 패키징 할 수 있습니다. 어떤 익스텐션들은 VSIX 파일을 깃허브 릴리즈를 통해 퍼블리시 하기도 합니다.

익스텐션 저자는 익스텐션의 루트 폴더에서 vsce package를 실행하여 VSIX 파일을 만들 수 있습니다.

사용자가 VSIX 파일을 받았을 경우, code --install-extension my-extension-0.0.1.vsix 명령어를 사용하여해 익스텐션을 설치할 수 있습니다.

비공개적으로 공유하기

만약 익스텐션을 비공개적으로 공유하려는 경우, 패키지된 익스텐션 .vsix 파일을 보내십시오.

익스텐션 폴더

익스텐션을 불러오려면, 사용자는 VS Code 익스텐션 폴더 .vscode/extensions에 파일을 복사 해야 합니다. 이는 사용중인 플랫폼에 따라 다음 폴더에 위치해 있습니다.

Windows %USERPROFILE%\.vscode\extensions
macOS ~/.vscode/extensions
Linux ~/.vscode/extensions

Visual Studio Code와의 호환성

익스텐션을 작성할때, package.json 내부의 engines.vscode를 통해서 Visual Studio Code와의 호환성을 표기 해야 합니다.

{
  "engines": {
    "vscode": "^1.8.0"
  }
}

1.8.0의 값은 익스텐션이 오직 VS Code 1.8.0버전에만 호환 가능함을 의미합니다. ^1.8.0은 익스텐션이 VS Code 버전 1.8.0 그리고 1.8.1, 1.9.0 과 같이 그 이상과도 호환 가능함을 의미합니다.

engines.vscode 필드를 사용하여 익스텐션이 의존하는 API를 포함하고 있는 클라이언트에만 설치 할 수 있게 하십시오. 이러한 메커니즘은 Insider에서의 안정적인 릴리스를 가능하게 합니다.

예를 들어, 최근의 VS Code Stable 버전이 1.8.0이고 새로운 API를 포함하는 1.9.0 버전에서 개발 중인 경우 1.9.0-insider를 통해 릴리스 할 수 있습니다. 만약 익스텐션 버전을 1.9.0 의 새로운 API를 활용할 수 있게 게시 하려는 경우, 버전 의존성을 ^1.9.0으로 표기해야 합니다. 새로운 익스텐션 버전으로 인해 VS Code >=1.9.0 에서만 설치 가능할 것이고, 이는 현재 1.9.0의 사용자는 사용 가능하지만, Stable 버전을 사용 하는 다른 사용자의 경우 Stable 버전이 1.9.0가 될 때 사용 가능함을 의미합니다.

고급 사용법

마켓플레이스 완성

여러분의 익스텐션이 Visual Studio 마켓플레이스에서 어떤식으로 보일지 커스터마이즈 할 수 있습니다. Go extension에 있는 예시를 참조하십시오.

여러분의 익스텐션을 더욱 멋져보이게 하는 몇가지 팁이 있습니다.

README.md파일은 익스텐션의 마켓플레이스 페이지의 보여지는 핵심입니다. vsce는 README 링크를 2가지 방법을 통해 수정 할 수 있습니다.
- 만약 여러분의 깃허브 저장소로 package.json의 repository 필드를 더하는 경우, vsce에서 자동으로 감지하여 링크를 조정 할 것입니다.
- vsce package 명령어를 사용하면서 --baseContentUrl 과 --baseImagesUrl 플래그를 사용해서 오버라이드 할 수 있습니다. 그 후 패키지된 .vsix파일의 경로를 vsce publish의 인수로 제공하여 익스텐션을 게시 하십시오.
LICENSE파일은 익스텐션의 라이센스를 명시하기 위해 사용됩니다.
CHANGELOG.md파일은 익스텐션의 change log를 기록하기 위해 사용됩니다.
package.json의 galleryBanner.color를 의도한 hex값으로 설정하여 배너 배경색을 설정할 수 있습니다.
익스텐션에 포함시킨 128px 정사각형 PNG 파일의 상대 경로를, package.json의 icon에 설정하여 아이콘을 설정할 수 있습니다.

Marketplace Presentation Tips를 참고하십시오.

`.vscodeignore`

.vscodeignore파일을 생성하여 익스텐션 패키지에서 특정 파일들을 배제할 수 있습니다. 이 .vscodeingore파일은 각 줄마다 반복되는 glob패턴 들로 구성되어 있습니다.

예를 들어:

**/*.ts
**/tsconfig.json
!file.ts

여러분은 실행에 필요하지 않은 모든 파일을 배제해야 합니다. 예를 들어, 익스텐션이 타입스크립트로 작성 된 경우, 예제와 같이 모든 **/*.ts파일을 배제하십시오.

메모: devDependencies에 작성된 개발 의존성은 자동으로 배제될것이니, .vscodeignore 파일에 추가하지 마십시오.

Pre-publish 단계

Pre-publish 단계를 여러분의 매니페스트 파일에 더하는것이 가능합니다. 이 명령어는 익스텐션이 패키지 될 때마다 실행 될 것입니다.

{
  "name": "uuid",
  "version": "0.0.1",
  "publisher": "someone",
  "engines": {
    "vscode": "0.10.x"
  },
  "scripts": {
    "vscode:prepublish": "tsc"
  }
}

이는 익스텐션이 패키징 될 때마다 타입스크립트 컴파일러를 호출 할 것입니다.

다음 단계들

Extension Marketplace - VS Code의 공개적인 익스텐션 마켓플레이스에 대해 더 배우십시오.
Testing Extensions - 높은 완성도를 위해, 익스텐션에 테스트를 더하십시오.
Bundling Extensions - webpack으로 bundling하여 여러분의 익스텐션 로드 시간을 개선하십시오.

자주 나오는 질문들

익스텐션을 게시 할때 403 Forbidden (또는 401 Unauthorized) 에러가 발생하는 경우?

PAT(Personal Access Token)을 생성할때 쉬운 실수 중 하나는 계정 필드에서 all accessible accounts를 선택하지 않는것입니다. (대신 특정 계정을 선택) 또한 작업물을 게시 하기 위해 Authorized 범위를 All scopes로 설정하십시오.

`vsce`를 이용하여 내 익스텐션 게시를 취소 할 수 없는 경우?

익스텐션 ID나 게시자 이름이 변경 되었을 수 있습니다. 대신 여러분의 익스텐션을 마켓플레이스에서 관리 페이지를 통해 직접 관리 할 수 있습니다. 여러분의 퍼블리셔 관리 페이지에서 익스텐션을 업데이트 하거나, 게시 취소하십시오.

vsce 가 파일 속성을 보전 하지 않는 경우?

익스텐션을 Windows에서 만들고 게시하는 경우에 유념해주십시오, 모든 익스텐션 패키지에 포함되어 있는 파일은 POSFIX 파일 속성이 없는, 다시말해 실행가능한 비트 입니다. 어떤 node_modules는 정상적으로 작동하기 위해 이러한 속성에 의존하기 때문에. Linux와 macOS에서 게시하는 것을 권장됩니다.

Continuous integration (CI) 빌드에서 게시할 수 있습니까?

가능합니다, Continuous Integration 주제의 Automated publishing 섹션을 참조하여 Azure DevOps를 설정하고 자동으로 마켓플레이스에 익스텐션을 게시 하는 방법을 배우십시오.

익스텐션 게시하기

vsce

설치

사용예시

익스텐션 게시하기

Personal Access Token 생성하기

게시자 생성하기

게시자로 로그인하기

익스텐션 버전의 관리

익스텐션 게시 취소하기

익스텐션 패키징하기

비공개적으로 공유하기

익스텐션 폴더

Visual Studio Code와의 호환성

고급 사용법

마켓플레이스 완성

.vscodeignore

Pre-publish 단계

다음 단계들

자주 나오는 질문들

익스텐션을 게시 할때 403 Forbidden (또는 401 Unauthorized) 에러가 발생하는 경우?

vsce를 이용하여 내 익스텐션 게시를 취소 할 수 없는 경우?

vsce 가 파일 속성을 보전 하지 않는 경우?

Continuous integration (CI) 빌드에서 게시할 수 있습니까?

`.vscodeignore`

`vsce`를 이용하여 내 익스텐션 게시를 취소 할 수 없는 경우?