カスタマイズ スキーマ リファレンス

Microsoft Dev Boxのカスタマイズにより、プラットフォームエンジニアや開発者はツールの事前インストール、リポジトリのクローン作成、YAMLファイルを使ってDev Boxの設定を行えます。 このリファレンスは、Dev BoxのカスタマイズがサポートするYAMLファイルおよび組み込みタスクの現在のスキーマを説明しています。

必要なときにこの参考文献を活用してください:

• imagedefinition.yamlやtask.yamlファイルで有効なプロパティ、型、デフォルトを調べてみてください。
• 組み込みの ~/gitclone、 ~/powershell、 ~/winget タスクが受け入れるパラメータを確認してください。
• Dev Boxが画像をプロビジョニングしたりカスタマイズを適用したりする際、 tasks、 userTasks、 parameters、 variables、 buildProperties がどのように連携して動作するかを理解しましょう。

カスタマイズファイル形式

Dev Boxのカスタマイズは、それぞれ異なる目的と対象を持つ3種類のYAMLファイル形式を使用します。

組み込みの ~/gitclone、 ~/powershell、 ~/winget タスクは、カタログを添付せずにどの開発センターからも利用可能です。 組み込み以外のカスタムタスクを追加するには、カタログ内の task.yaml ファイルで定義し、画像定義やユーザーカスタマイズファイルから名前で呼び出してください。 詳細については、Microsoft Dev Boxのカスタマイズをご覧ください。

Imagedefinition.yaml ファイル

imagedefinition.yamlを使って、Dev Boxが画像定義を作成する際に適用する画像、パラメータ、変数、カスタマイズタスクを定義します。

例 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

(文字列、必須)

Dev Boxのイメージに使うベースイメージを指定します。 画像はマーケットプレイスの画像であったり、Azure Compute Galleryに付属したカスタム画像で、gallery-name/image-name@versionの形式で作成できます。

例：

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

image: my-gallery/my-image@0.0.1

Azure Compute Galleryを添付するには、「Microsoft Dev Box の Azure Compute Gallery の設定」をご覧ください。

開発センターがアクセスできるイメージのリストを取得するには、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 が含まれなければならず、 displayName、 description、 parameters、 timeoutも定義できます。

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

(文字列、必須)

実行すべきタスクを特定します。 ~/winget、~/powershell、~/gitcloneなどの組み込みタスクには~/プレフィックスを使いましょう。

displayName

(弦)

UIの表面に短い表示テキストを提供します。

description

(弦)

画像定義でタスクの機能を記述します。

parameters

(物体)

タスクに渡される入力値を定義します。 パラメータ名や値型は選択したタスクによって異なります。

パラメータ定義は、 task.yaml パラメータ特性について説明されたのと同じスキーマに従っています。 詳細は、 type、 allowed、 default、 description、 validationRegex、 minLength、 maxLength、 requiredを参照してください。

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

(弦)

インラインコマンドを実行します。 commandを提供すれば、script、scriptArgs、scriptExecutionPolicyパラメータは無視されます。

workingDirectory

(弦)

コマンドやスクリプトの作業ディレクトリを設定します。

script

(弦)

実行するローカルまたはリモートのPowerShellスクリプトへのパスを指定します。 このパラメータは command が提供される際に無視されます。

scriptArgs

(弦)

脚本の根拠も提供しています。 このパラメータは command が提供される際に無視されます。

scriptExecutionPolicy

(文字列、デフォルト:バイパス)

スクリプトの実行ポリシーを設定します。 このパラメータは 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.yaml ファイルや devbox.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.yaml または devbox.yaml ファイルから定義します。 名前は、タスクが存在するカタログのコンテキストで一意である必要があります。

他のDev Boxのカスタマイズアーティファクトと同じ命名制約を使いましょう。 名前は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 ファイルを作成し、Dev Boxプールに適用します。
• 開発者ボックス用のユーザーカスタマイズファイルを設定 し、Authorを使い、個人用の devbox.yaml ファイルをアップロードしてください。
• Dev Boxのカスタマイズタスクを設定してください 。ファイルを task.yaml 作成し、カタログを通じて公開します。
• Azure リソースに接続するか、プライベート リポジトリを複製する