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

2025-05-29

このリファレンス記事では、Microsoft Dev Box のカスタマイズに使用される imagedefinition.yaml ファイルと task.yaml ファイルの詳細について説明します。開発者はこれらの YAML ファイルを使用して、開発ボックスをプロビジョニングおよび構成するためのタスクを定義できます。このファイルは、開発環境全体の一貫性と効率を確保するのに役立ちます。この記事では、スキーマ、必要な属性、両方のファイルの種類の例と、PowerShell や WinGet などの組み込みタスクについて説明します。

Imagedefinition.yaml ファイル

Dev Box YAML ファイルを使用して、Dev Box の作成時に実行する必要があるカスタマイズタスクを定義できます。 devbox.yaml ファイルは、開発チームが使用するプライマリソースと同じリポジトリに存在する場合もあれば、ファイルが構成の一元化されたリポジトリ内にある場合もあります。

イメージ定義 YAML の例:

$schema: 1.0
name: project-sample-1
image: MicrosoftWindowsDesktop_windows-ent-cpc_win11-21h2-ent-cpc-m365
tasks:
- name: "powershell"
  inputs:
    command:

名前

必須： イメージ定義のこのフレンドリ名は、この devbox.yaml ファイルに関連付けられています。この設定は、プールを作成および更新するときに使用できるイメージ定義の名前を制御します。

name: myVSDevBox

画像

必須： イメージ定義の基本イメージとして使用するイメージは、マーケットプレースイメージにすることができます。

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

または、アタッチされた Azure Compute Gallery インスタンスのカスタムイメージを指定することもできます。

image: galleryname/imagename@version

Azure コンピューティングギャラリーインスタンスをデベロッパーセンターにアタッチする方法については、「 Microsoft Dev Box 用に Azure Compute Gallery を構成する」を参照してください。

デベロッパーセンターがアクセスできるイメージの一覧を取得するには、次の az cli コマンドを使用します。

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

デベロッパーセンターの az cli 拡張機能が必要です。

az extension add --name devcenter

用事

必須： このオブジェクトコレクションは、開発ボックスをプロビジョニングするときに実行する Dev Box カスタマイズタスクで構成されます。タスクに提供される特定の入力は、タスクによって異なります。

例：

tasks:
- name: winget
  parameters:
    package: GitHub.GitHubDesktop

すべてのタスクで timeout プロパティがサポートされています。これは省略可能です。

例：

tasks:
- name: powershell
  timeout: 1800 # in seconds
  parameters:
    command: <command>

組み込みタスク

PowerShell と WinGet は、組み込みのタスクとして使用できます。これらのタスクの実装を定義するデベロッパーセンターレベルでカタログをアタッチせずに、それらを直接呼び出すことができます。

WinGet 組み込みタスク

この組み込みタスクは、WinGet 構成を開発ボックスに適用します。

パラメーター:

configurationFile:
- タイプ: string
- WinGet 構成 YAML ファイルへのパス。ファイルはローカルコンピューターに配置する必要があります。
- 必須: false
downloadUrl:
- タイプ: string
- 構成 YAML ファイルが格納されているパブリックにアクセス可能な URL。ファイルは、指定したパス configurationFile ダウンロードされます。
- 必須: false
inlineConfigurationBase64:
- タイプ: string
- WinGet 構成 YAML ファイルの Base64 でエンコードされた文字列。ファイルは、指定 configurationFile パスにデコードされ、指定されていない場合は一時ファイルにデコードされます。
- 必須: false
package:
- タイプ: string
- インストールするパッケージの名前。
- 構成 YAML ファイルが他のパラメーターの下に指定されている場合、パッケージ名は必要ありません。
- 必須: false
version
- タイプ: string
- インストールするパッケージのバージョン。
- 構成 YAML ファイルが他のパラメーターの下に指定されている場合、パッケージのバージョンは必要ありません。
- 必須: false

PowerShell 組み込みタスク

この組み込みタスクは、PowerShell コマンドを実行します。

パラメーター:

command:
- タイプ: string
- 実行するコマンド。
- 必須: true

task.yaml ファイル

カスタマイズタスクは、再利用可能なインストールコードまたは環境構成の単位です。開発者は PowerShell スクリプトを使用してスクリプトを記述し、 task.yaml メタデータファイルを使用して記述します。開発者はこれらのタスクを使用して、 devbox.yaml ファイルからそれらを参照して開発ボックスをカスタマイズします。

カスタマイズタスクを定義すると、開発者が devbox.yaml ファイルで使用できるタスクを特定できます。 PowerShell コマンドを実行する機能など、高い特権のアクションを制限できます。

タスク定義の次の例では、特定の作業ディレクトリで PowerShell コマンドを実行します。

name: powershell
description: Execute a powershell command
author: Microsoft Corporation
command: ".\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}"
inputs:
  command:
    type: string
    defaultValue: ""
    required: true
    description: The command to execute
  workingDirectory:
    type: string
    defaultValue: ""
    required: false
    description: The working directory to execute the command in

属性

名前

必須： この一意識別子は、 devbox.yamlからタスクを参照するために使用されます。名前は、タスクが存在するカタログのコンテキストで一意である必要があります。

名前付けは、既存の Azure リソース制約と一致している必要があります。名前は 3 ~ 63 文字にする必要があります。英数字で始まる必要があります。名前は、英数字と "-"、"."、または "_" のみで構成する必要があります。 "/" 文字は予約されています。

name: powershell

説明

随意： この属性は、タスクを記述します。

description: This task executes a powershell command

入力

必須： この属性は、このタスクが devbox.yaml ファイルからの入力として受け取るパラメーターを一覧表示し、コマンドの実行中に使用します。各親項目はパラメーターの名前を表し、次のキーをサポートします。

type (必須): このパラメーターの入力データ型。 string または int を指定できます。
defaultValue (必須): このパラメーターが受け取る既定値。
required (必須): このパラメーターが省略可能か必須かを指定するキー。
description (必須): このパラメーターが表す内容の説明。

inputs:
  command:
    type: string
    defaultValue: ""
    required: true
    description: The command to execute

コマンド

必須： このコマンドは、このタスクを実行するために使用されます。指定されたコマンド文字列は、ローカルコンピューター上の Windows PowerShell で実行されます。

command: ".\runcommand.ps1

コマンド内の変数を参照する

コマンドでパラメーターを参照するには、変数名を二重中かっこで指定します (例: {{parameter_name}})。これらの変数の値は、コマンドを実行する前に補間されます。

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

タイムアウト

随意： この変数は、タスクの実行が完了するまでタスクがタイムアウトするまでの最大時間 (分) を指定します。既定値は 30 分です。

timeout: 30

著者

随意： この変数は、監査とトラブルシューティングに役立つタスク作成者を識別します。

author: Contoso Corporation

documentationURL

随意： この変数は、このタスクのドキュメントにリンクされています。

documentationURL: "https://link.to/documentation"

licenseURL

随意： この変数は、このタスクのライセンスにリンクします。

licenseURL: "https://link.to/license"