사용자 지정 스키마 참조

Microsoft Dev Box 커스터마이징을 통해 플랫폼 엔지니어와 개발자는 도구를 사전 설치하고, 저장소를 복제하며, YAML 파일을 사용해 개발 박스에서 설정을 구성할 수 있습니다. 이 참조는 개발 박스 커스터마이징이 지원하는 YAML 파일과 내장 작업의 현재 스키마를 설명합니다.

필요할 때 이 참고서를 활용하세요:

• imagedefinition.yaml 또는 task.yaml 파일에서 유효한 속성, 타입, 기본값을 찾아보세요.
• 내장된 ~/gitclone, ~/powershell, ~/winget 작업들이 수용하는 매개변수를 확인하세요.
• Dev Box가 이미지를 제공하거나 커스터마이징을 적용할 때 , , userTasks, parametersvariablesbuildProperties 가 어떻게 tasks함께 작동하는지 이해하세요.

커스터마이징 파일 형식

Dev Box 커스터마이징은 각각 다른 목적과 대상을 가진 세 가지 YAML 파일 형식을 사용합니다:

내장 ~/gitclone, ~/powershell, 작업 ~/winget 기능은 카탈로그를 첨부하지 않고도 어느 개발 센터에서든 이용할 수 있습니다. 내장 작업 외에 커스텀 작업을 추가하려면, 카탈로그 내 파일에서 task.yaml 정의하고 이미지 정의나 사용자 커스터마이징 파일에서 이름으로 호출하세요. 자세한 내용은 Microsoft Dev Box 커스터마이징을 참조하세요.

Imagedefinition.yaml 파일

이미지 정의를 생성할 때 Dev Box가 적용하는 이미지, 매개변수, 변수, 커스터마이징 작업을 정의하는 데 사용 imagedefinition.yaml 하세요.

예시 imagedefinition.yaml 파일

$schema: "1.0"
name: example-image-definition
description: Install core tools and clone the project repository.
image: microsoftvisualstudio_visualstudioplustools_vs-2022-ent-general-win11-m365-gen2
parameters:
  repositoryBranch:
    type: string
    default: main
    description: Branch to clone during setup.
variables:
  workspaceRoot:
    type: string
    value: C:\Workspaces
    description: Root directory for repositories.
tasks:
  - name: ~/winget
    parameters:
      package: Git.Git
  - name: ~/gitclone
    parameters:
      repositoryUrl: https://github.com/example-org/example-repo.git
      directory: C:\Workspaces
      branch: "{{repositoryBranch}}"
userTasks:
  - name: ~/powershell
    parameters:
      command: code C:\Workspaces\example-repo
buildProperties:
  networkConnection: corp-westus3

Imagedefinition.yaml 속성

$schema

(스트링 또는 숫자)

파일의 스키마 버전을 지정합니다. 현재 예시에서는 를 사용합니다 1.0.

$schema: "1.0"

name

(문자열, 필요, 3-63자)

이미지 정의를 선택할 때 표시되는 친근한 이름을 지정합니다. 이 설정은 풀을 만들고 업데이트할 때 사용할 수 있는 이미지 정의의 이름을 제어합니다. 이름에는 , ", ;<]|:[+?@=,>*공&백이 포함되거나, 또는 로 시작 -_ 할 수 없습니다./

name: example-image-definition

description

(현악기)

이미지 정의의 목적을 설명합니다.

description: Install core tools and clone the project repository.

image

(끈, 필수)

개발 박스 이미지에 사용할 기본 이미지를 지정합니다. 이미지는 마켓플레이스 이미지일 수도 있고, 첨부된 Azure Compute 갤러리gallery-name/image-name@version에서 가져온 커스텀 이미지일 수도 있습니다.

예:

image: microsoftwindowsdesktop_windows-ent-cpc_win11-21h2-ent-cpc-m365

image: my-gallery/my-image@0.0.1

Azure 컴퓨트 갤러리를 첨부하려면 'Microsoft Dev Box용 Azure 컴퓨트 갤러리 구성'을 참조하세요.

개발 센터에서 접근할 수 있는 이미지 목록을 얻으려면 Azure CLI를 사용하세요:

az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"

필요하다면 먼저 Dev Center Azure CLI 확장 프로그램을 설치하세요:

az extension add --name devcenter

parameters

(객체)

구문을 사용 {{parameterName}} 해 작업 시 참조할 수 있는 이름 있는 입력 매개변수를 정의합니다.

parameters:
  repositoryBranch:
    type: string
    default: main
    description: Branch to clone during setup.

매개변수 객체 속성

type

(문자열, 필수, 허용 값: 문자열, 불리언, 숫자)

매개변수 데이터 타입을 지정합니다.

allowed

(문자열 배열)

매개변수를 허용되는 고정된 문자열 값 집합으로 제한합니다.

default

(문자열, 불리언 또는 숫자 필요)

매개변수의 기본값을 설정합니다.

description

(현악기)

저자 및 도구 매개변수를 설명합니다.

validationRegex

(현악기)

문자열 값이 일치해야 하는 정규 표현식을 정의합니다.

minLength

(정수)

문자열 값의 최소 길이를 설정합니다.

maxLength

(정수)

문자열 값의 최대 길이를 설정합니다.

variables

(객체)

이미지 정의에서 재사용할 수 있는 이름 있는 변수들을 정의합니다.

variables:
  workspaceRoot:
    type: string
    value: C:\Workspaces
    description: Root directory for repositories.

변수 객체 속성

type

(문자열, 필수, 허용 값: 문자열, 불리언, 숫자)

변수 데이터 타입을 지정합니다.

value

(문자열, 불리언 또는 숫자 필요)

변수 값을 설정합니다.

description

(현악기)

저자와 도구 변수를 설명합니다.

tasks

(작업 객체 배열)

프로비저닝 중 시스템 컨텍스트에서 실행할 맞춤화 작업을 나열합니다. 제공하는 특정 입력값은 작업에 따라 다릅니다. 각 작업 항목은 반드시 포함 name 해야 하며, descriptionparameterstimeout도 정의displayName할 수 있습니다.

tasks:
  - name: ~/winget
    parameters:
      package: Git.Git
  - name: ~/gitclone
    timeout: 1800
    parameters:
      repositoryUrl: https://github.com/example-org/example-repo.git
      directory: C:\Workspaces

이 속성은 timeout 선택 사항이며, 에서 imagedefinition.yaml사용할 때 초 단위로 측정됩니다.

tasks:
  - name: ~/powershell
    timeout: 1800
    parameters:
      command: <command>

작업 입력 속성

name

(끈, 필수)

실행할 작업을 식별합니다. , , 와 ~/gitclone같은 ~/winget~/powershell내장 작업에 접두사를 ~/ 사용하세요.

displayName

(현악기)

UI 표면에 짧은 표시 텍스트를 제공합니다.

description

(현악기)

이미지의 정의에서 작업이 수행하는 일을 설명합니다.

parameters

(객체)

작업에 전달되는 입력값을 정의합니다. 매개변수 이름과 가치 유형은 선택한 작업에 따라 다릅니다.

매개변수 정의는 매개변수 속성에 대해 task.yaml 설명된 동일한 스키마를 따릅니다. 자세한 내용은 , , allowed, validationRegexdefaultdescriptionminLengthmaxLength를 required참고type하세요.

timeout

(정수)

작업 실행 타임아웃을 몇 초 만에 무시합니다.

userTasks

(작업 객체 배열)

로그인 후 사용자 컨텍스트에서 실행할 맞춤화 작업을 나열합니다. userTasks 와 동일한 작업 입력 스키마 tasks를 사용합니다.

userTasks:
  - name: ~/powershell
    parameters:
      command: code C:\Workspaces\example-repo

buildProperties

(객체)

이미지 빌드 과정을 맞춤화하는 빌드별 설정을 정의합니다.

buildProperties:
  networkConnection: corp-westus3

빌드 속성 객체 속성

networkConnection

(현악기)

이미지 생성 시 사용되는 네트워크 연결을 지정합니다. 빌드 작업이 특정 네트워크 연결을 통해서만 접근 가능한 개인 저장소나 스토리지 계정 같은 자원에 접근해야 할 때 이 설정을 사용하세요. 이미지 생성에 사용하려면 네트워크 연결이 개발 센터에 연결되어야 합니다.

buildProperties:
  networkConnection: my-westus3

기본 제공 작업

카탈로그를 첨부하지 않고 일반적인 맞춤화 작업이 필요할 때는 내장 작업을 활용하세요. ~/ 예를 ~/winget들어, , ~/powershell, 또는 ~/gitclone.

• GitClone 내장 작업
• PowerShell 내장 작업
• WinGet 내장 작업

GitClone 내장 작업

GitClone 내장 작업을 사용해 저장소를 개발 박스에 복제하세요.

예제:

tasks:
  - name: ~/gitclone
    parameters:
      repositoryUrl: https://github.com/microsoft/calculator
      directory: C:\Workspaces
      branch: main

repositoryUrl

(끈, 필수)

복제할 저장소 URL을 지정합니다.

directory

(문자열, 기본값: C:\Workspaces)

저장소가 복제되는 디렉터리를 설정합니다.

branch

(현악기)

복제할 분기를 선택합니다.

pat

(현악기)

인증된 복제 작업을 위한 개인 접근 토큰을 제공합니다. 제공되지 않으면 pat 클론이 첫 사용자 로그인 대기열에 들어갑니다. 공급 pat하면 프로비전 중에 작업이 복제될 수 있습니다. 원시 비밀 값 대신 Key Vault 비밀 참조를 사용하세요.

GitClone 내장 작업은 실행 중에 PowerShell 7, Git, Git LFS도 설치합니다.

PowerShell 기본 제공 작업

PowerShell 내장 작업을 사용해 명령어나 스크립트를 실행하세요.

예제:

tasks:
  - name: ~/powershell
    parameters:
      command: Write-Host "Hello from Dev Box"

command

(현악기)

인라인 명령어를 실행합니다. 만약 를 script제공command하면 , , scriptArgs와 scriptExecutionPolicy 매개변수는 무시됩니다.

workingDirectory

(현악기)

명령어나 스크립트의 작업 디렉터리를 설정합니다.

script

(현악기)

실행할 로컬 또는 원격 PowerShell 스크립트로 가는 경로를 지정합니다. 이 매개변수는 제공되면 command 무시됩니다.

scriptArgs

(현악기)

대본에 대한 논거를 제공합니다. 이 매개변수는 제공되면 command 무시됩니다.

scriptExecutionPolicy

(문자열, 기본값: Bypass)

스크립트의 실행 정책을 설정합니다. 이 매개변수는 제공되면 command 무시됩니다.

WinGet 기본 제공 작업

WinGet 내장 작업을 사용해 패키지를 직접 설치하거나 WinGet 구성 파일을 적용하세요.

예제:

tasks:
  - name: ~/winget
    parameters:
      package: GitHub.GitHubDesktop
      version: 3.4.16

configurationFile

(현악기)

로컬 머신의 WinGet 설정 YAML 파일을 가리킵니다.

downloadUrl

(현악기)

WinGet 구성 YAML 파일의 공개 URL을 지정합니다. 파일은 .의 configurationFile경로로 다운로드됩니다.

inlineConfigurationBase64

(현악기)

Base64로 인코딩된 WinGet 구성 YAML 파일을 제공합니다. 작업이 설정되지 않으면 임시 파일 configurationFile 로 디코딩configurationFile합니다.

package

(현악기)

이름으로 직접 패키지를 설치합니다. 구성 파일 소스 package를 사용하면 .

version

(현악기)

특정 패키지 버전을 설치합니다. 구성 파일 소스 version를 사용하면 .

task.yaml 파일

카탈로그에서 재사용 가능한 커스터마이징 작업을 정의하는 데 사용 task.yaml 하세요. 작업 정의는 명령어, 메타데이터, 매개변수, 문서 및 실행 설정을 설명합니다.

맞춤화 작업을 정의할 때, 개발자가 파일에서 imagedefinition.yamldevbox.yaml 사용할 수 있는 작업을 식별합니다. 작업 정의를 사용해 임의의 PowerShell 명령어 실행 권한과 같은 고권한이 동작을 제한할 수 있습니다.

예시 task.yaml 파일

$schema: "1.0"
name: install-vsix-extension
description: Install a Visual Studio extension from a VSIX package.
author: Contoso Corporation
command: .\install-extension.ps1 -VsixPath {{vsixPath}}
documentationURL: https://contoso.example/devbox/install-vsix-extension
keywords:
  - visual-studio
  - extension
parameters:
  vsixPath:
    type: string
    required: true
    description: Path to the VSIX package.
timeout: 30
rebootRequired: false
documentation:
  notes: Use a path that is available during task execution.
  examples:
    - name: install-vsix-extension
      parameters:
        vsixPath: .\extensions\contoso.vsix

다음 예시는 특정 작업 디렉터리에서 PowerShell 명령을 실행하는 작업 정의를 보여줍니다:

$schema: "1.0"
name: powershell
description: Execute a PowerShell command.
author: Microsoft Corporation
command: .\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}
parameters:
  command:
    type: string
    default: ""
    required: true
    description: The command to execute.
  workingDirectory:
    type: string
    default: ""
    required: false
    description: The working directory in which to execute the command.

Task.yaml 속성

$schema

(끈, 필수)

작업 정의에 대한 스키마 버전을 지정합니다. 현재 예시에서는 를 사용합니다 1.0.

name

(끈, 필수)

작업이나 imagedefinition.yamldevbox.yaml 파일을 참조하는 데 사용되는 식별자를 정의합니다. 이름은 작업이 존재하는 카탈로그의 컨텍스트에서 고유해야 합니다.

다른 개발자 박스 커스터마이징 아티팩트와 동일한 명명 제약 조건을 사용하세요. 이름은 3자에서 63자 사이여야 하며, 영숫자 문자로 시작해야 하며, -오직 영숫자 문자, , ., 만 _포함되어야 합니다. 문자가 / 예약되어 있습니다.

name: install-vsix-extension

command

(끈, 필수)

작업을 구현하는 PowerShell 명령어를 지정합니다. 이 명령어는 로컬 머신의 Windows PowerShell에서 실행됩니다. 명령어 문자열의 매개변수 값을 참조하는 구문을 사용 {{parameterName}} 하세요.

command: .\install-extension.ps1 -VsixPath {{vsixPath}}

다음은 그 예입니다.

command: .\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}

description

(현악기)

과제의 목적을 설명합니다.

description: This task executes a PowerShell command.

author

(현악기)

감사 및 문제 해결을 위한 작업 작성자를 식별합니다.

author: Contoso Corporation

issueNotificationEmail

(현악기)

사용자가 작업에 문제가 있을 때 연락할 수 있는 이메일 주소를 제공합니다. 제품 기능은 이 가치를 소비하지 않습니다.

documentationURL

(현악기)

작업 관련 문서 링크입니다.

documentationURL: https://link.to/documentation

licenseURL

(현악기)

작업 라이선스 링크입니다.

licenseURL: https://link.to/license

keywords

(문자열 배열)

소비자가 해당 작업을 찾는 데 도움이 되는 키워드를 나열합니다.

parameters

(객체)

작업의 이름 있는 입력 매개변수를 정의합니다. 각 자식 항목은 매개변수 이름을 나타내며, 매개변수 유형, 허용된 값, 기본 값, 설명, 검증 규칙, 길이 제한, 매개변수 필요성 여부를 정의할 수 있습니다.

parameters:
  vsixPath:
    type: string
    required: true
    description: Path to the VSIX package.

매개변수 정의 특성

type

(문자열, 필수, 허용 값: 문자열, 불리언, 숫자)

입력 데이터 타입을 지정합니다.

allowed

(문자열 배열)

입력을 허용되는 고정된 문자열 값 집합으로 제한합니다.

default

(문자열, 불리언, 또는 숫자)

입력값의 기본값을 설정합니다.

description

(현악기)

입력을 설명합니다.

validationRegex

(현악기)

문자열 값이 일치해야 하는 정규 표현식을 정의합니다.

minLength

(정수)

문자열 값의 최소 길이를 설정합니다.

maxLength

(정수)

문자열 값의 최대 길이를 설정합니다.

required

(불리언)

입력이 공급되어야 하는지 여부를 나타냅니다. 생략하면 기본값은 .입니다 false.

timeout

(정수, 기본값: 30)

기본 작업 타임아웃을 몇 분 내에 설정합니다. 값을 지정하지 않으면 기본값은 30분입니다.

timeout: 30

documentation

(객체)

작업 사용자가 이미지 정의에 작업을 추가할 때 사용할 수 있는 노트와 호출 예시를 제공합니다.

문서화 객체 속성

notes

(현악기)

업무 수행자에게 안내나 주의사항을 추가합니다.

examples

(작업 객체 배열)

작업 항목과 imagedefinition.yaml동일한 스키마를 사용하여 예시 작업 호출을 보여줍니다.

rebootRequired

(불리언, 기본값: false)

실행 후 작업이 재부팅이 필요한지 여부를 나타냅니다.

관련 콘텐츠

• 팀 커스터마이징 구성 - 파일을 생성 imagedefinition.yaml 하고 개발 박스 풀에 적용하세요.
• 개발자 박스에 사용자 커스터마이징 파일을 설정 하고 개인 devbox.yaml 용 파일을 업로드하세요.
• Dev Box 커스터마이징을 위한 작업 구성 - 파일 작성 task.yaml 후 카탈로그를 통해 게시하세요.
• Azure 리소스에 연결하거나 프라이빗 리포지토리 복제