Skip to content

Commit 8fd8f0d

Browse files
AnnaMHuffAnnaMHuff
authored
Merge pull request #299630 from RoseHJM/mdb-customizations-reference
MDB - Customizations yaml reference
2 parents 1107909 + d17977a commit 8fd8f0d

File tree

2 files changed

+255
-0
lines changed

2 files changed

+255
-0
lines changed

‎articles/dev-box/reference-dev-box-customizations.md

Lines changed: 253 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,253 @@
1+
---
2+
title: 'Reference: imagedefinition.yaml and task.yaml files'
3+
description: Reference for customizing Dev Box environments using devbox.yaml and task.yaml files, including built-in tasks and parameters.
4+
author: RoseHJM
5+
ms.service: dev-box
6+
ms.topic: reference
7+
ms.date: 05/09/2025
8+
ms.author: rosemalcolm
9+
10+
---
11+
12+
# Customizations Schema Reference
13+
14+
This reference guide provides detailed information about the `imagedefinition.yaml` and `task.yaml` files used to customize Microsoft Dev Box. These YAML files enable developers to define tasks for provisioning and configuring Dev Boxes, ensuring consistency and efficiency across development environments. The guide covers the schema, required attributes, and examples for both file types, along with built-in tasks like PowerShell and Winget.
15+
16+
## Imagedefinition.yaml files
17+
18+
A Dev Box yaml allows you to define customization tasks that ought to run during Dev Box creation. A devbox.yaml file might live in the same repository as the primary source code being used by the dev team, or in a centralized repository of configurations.
19+
20+
Example Image Definition yaml:
21+
22+
```
23+
$schema: 1.0
24+
name: project-sample-1
25+
image: MicrosoftWindowsDesktop_windows-ent-cpc_win11-21h2-ent-cpc-m365
26+
tasks:
27+
- task: "powershell"
28+
inputs:
29+
command:
30+
```
31+
32+
### name
33+
34+
**Required**
35+
36+
A friendly name for the image definition associated with this devbox.yaml. This setting controls the name of the image definition available when creating and updating pools.
37+
38+
```
39+
name: myVSDevBox
40+
```
41+
42+
### image
43+
44+
**Required**
45+
46+
The image you would like to use as the base image for your image definition. This image can be a marketplace image:
47+
48+
```
49+
image: MicrosoftWindowsDesktop_windows-ent-cpc_win11-21h2-ent-cpc-m365
50+
```
51+
52+
Or a custom image:
53+
54+
```
55+
image: galleryname/imagename@version
56+
```
57+
58+
To get a list of images that your DevCenter has access to, use this az cli command:
59+
60+
```
61+
az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"
62+
```
63+
64+
You would need the DevCenter az cli extension:
65+
66+
```
67+
az extension add --name devcenter
68+
```
69+
70+
### tasks
71+
72+
**Required**
73+
74+
An object collection of Dev Box customization tasks to be executed when provisioning a Dev Box. The specific inputs provided to a task vary by task.
75+
76+
Example:
77+
78+
```
79+
tasks:
80+
- name: winget
81+
parameters:
82+
package: GitHub.GitHubDesktop
83+
```
84+
85+
The **timeout** parameter is supported by all tasks and is optional.
86+
87+
Example:
88+
89+
```
90+
tasks:
91+
- name: powershell
92+
parameters:
93+
command: <command>
94+
timeout: 1800 # in seconds
95+
```
96+
97+
### Built-in tasks
98+
99+
PowerShell and Winget are available as built-in tasks and can be invoked directly without attaching a DevCenter-level catalog that defines the implementation of these tasks.
100+
101+
#### Winget built-in task
102+
103+
Applies a winget configuration to the Dev Box.
104+
105+
**Parameters:**
106+
107+
- **configurationFile**
108+
- type: "string"
109+
- The path to the winget config yaml file. The file must be located in the local machine.
110+
- required: false
111+
112+
- **downloadUrl**
113+
- type: "string"
114+
- A publicly accessible URL where the config yaml file is stored. The file is downloaded to the path given in 'configurationFile'.
115+
- required: false
116+
117+
- **inlineConfigurationBase64**
118+
- type: "string"
119+
- A base64 encoded string of the winget config yaml file. The file is decoded to the path given in 'configurationFile' or to a temporary file if not specified.
120+
- required: false
121+
122+
- **package**
123+
- type: "string"
124+
- The name of the package to install.
125+
- If a config yaml file is provided under other parameters, there's no need for the package name.
126+
- required: false
127+
128+
- **version**
129+
- type: "string"
130+
- The version of the package to install.
131+
- If a config yaml file is provided under other parameters, there's no need for the package version.
132+
- required: false
133+
134+
#### PowerShell built-in task
135+
136+
Execute a PowerShell command.
137+
138+
**Parameters:**
139+
140+
- **command**
141+
- type: "string"
142+
- The command to execute.
143+
- required: true
144+
145+
## task.yaml files
146+
147+
Customization tasks are reusable units of installation code or environment configuration – written using PowerShell scripts and described using a task.yaml metadata file. These tasks are then used by devs to customize a dev box by referencing them from a devbox.yaml file.
148+
149+
By defining customization tasks, you can define a guardrailed palette of what tasks are available to your developers for use in devbox.yamls, without providing high-privilege actions such as the ability to run any PowerShell command.
150+
151+
Example of a task definition that executes a PowerShell command in a specific working directory:
152+
153+
```
154+
name: powershell
155+
description: Execute a powershell command
156+
author: Microsoft Corporation
157+
command: ".\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}"
158+
inputs:
159+
command:
160+
type: string
161+
defaultValue: ""
162+
required: true
163+
description: The command to execute
164+
workingDirectory:
165+
type: string
166+
defaultValue: ""
167+
required: false
168+
description: The working directory to execute the command in
169+
```
170+
171+
### Attributes:
172+
173+
#### name
174+
**Required**
175+
The unique identifier used to refer to a task from devbox.yaml. The name should be unique in the context of the catalog where the task exists.
176+
Naming must match existing Azure Resource constraints: The name must be between 3 and 63 characters and must start with an alphanumeric character and consist of only alphanumeric characters and '-', '.', or '_'. The "/" character is reserved.
177+
178+
```
179+
name: powershell
180+
```
181+
182+
#### description
183+
**Optional**
184+
Description of the task.
185+
186+
```
187+
description: This task executes a powershell command
188+
```
189+
190+
#### inputs
191+
**Required**
192+
List of parameters that this task takes as an input from a devbox.yaml and utilizes while executing the command. Each parent item represents the name of a parameter and supports these keys:
193+
194+
- **type** [required]: input data type for this parameter. Can be string, int.
195+
- **defaultValue** [required]: default value this parameter takes.
196+
- **required** [required]: specifies whether this parameter is optional or required.
197+
- **description** [required]: a description of what this parameter represents.
198+
199+
```
200+
inputs:
201+
command:
202+
type: string
203+
defaultValue: ""
204+
required: true
205+
description: The command to execute
206+
```
207+
208+
#### command
209+
**Required**
210+
The command to execute to fulfill this task. The provided command string would be executed in Windows PowerShell on the local machine.
211+
212+
```
213+
command: ".\runcommand.ps1
214+
```
215+
216+
#### Referencing variables in command
217+
To reference parameters in a command, you can specify the variable name in Handlebar style double braces {{parameter_name}}. The values of these variables are interpolated before your command is executed.
218+
219+
```
220+
command: ".\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}"
221+
```
222+
223+
#### timeout
224+
**Optional**
225+
The maximum amount of time (in minutes) to wait for task execution to complete, before timing out the task. Defaults to 30 minutes.
226+
227+
```
228+
timeout: 30
229+
```
230+
231+
#### author
232+
**Optional**
233+
Identifier of a task author – to help with audits and troubleshooting.
234+
235+
```
236+
author: Contoso Corporation
237+
```
238+
239+
#### documentationURL
240+
**Optional**
241+
Link to documentation for this task.
242+
243+
```
244+
documentationURL: "https://link.to/documentation"
245+
```
246+
247+
#### licenseURL
248+
**Optional**
249+
Link to the license for this task.
250+
251+
```
252+
licenseURL: "https://link.to/license"
253+
```

‎articles/dev-box/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,8 @@ items:
164164
href: how-to-install-dev-box-cli.md
165165
- name: Azure CLI - az devcenter
166166
href: /cli/azure/service-page/microsoft%20dev%20box%20and%20azure%20deployment%20environments
167+
- name: Customizations YAML schema
168+
href: reference-dev-box-customizations.md
167169
- name: Authenticate to REST APIs
168170
href: how-to-authenticate.md
169171
- name: REST API

0 commit comments

Comments
 (0)