This reference article provides detailed information about theimagedefinition.yaml andtask.yaml files that are used to customize Microsoft Dev Box. Developers can use these YAML files to define tasks for provisioning and configuring dev boxes. The files help to ensure consistency and efficiency across development environments. This article covers the schema, required attributes, and examples for both file types, along with built-in tasks like PowerShell and WinGet.

Imagedefinition.yaml files

You can use a Dev Box YAML file to define customization tasks that ought to run during Dev Box creation. Adevbox.yaml file might live in the same repository as the primary source that the dev team uses, or the file might be in a centralized repository of configurations.

Example image definition YAML:

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

name

Required: This friendly name for the image definition is associated with thisdevbox.yaml file. This setting controls the name of the image definition that's available when you create and update pools.

name: myVSDevBox

image

Required: The image that you want to use as the base image for your image definition can be a marketplace image:

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

Or it can be a custom image from an attached Azure Compute Gallery instance:

image: galleryname/imagename@version

To learn how to attach an Azure Compute Gallery instance to your dev center, seeConfigure Azure Compute Gallery for Microsoft Dev Box.

To get a list of images to which your dev center has access, use thisaz cli command:

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

You need the dev centeraz cli extension:

az extension add --name devcenter

buildProperties

This object collection is made up of build properties that can be used to customize the build process for the image.

networkConnection

Optional: Specifies the network connection to use during image creation. This network connection allows customization tasks to access resources, like storage accounts or repositories, that are accessible from the specified network. The network connection must be attached to the Dev Center before it can be used for image creation.

Example:

buildProperties:    networkConnection: "my-westus3"

tasks

Required: This object collection is made up of Dev Box customization tasks to run when you provision a dev box. The specific inputs that are provided to a task vary by task.

Example:

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

All tasks support thetimeout property, which is optional.

Example:

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

Built-in tasks

PowerShell and WinGet are available as built-in tasks. You can invoke them directly without attaching a catalog at the dev center level that defines the implementation of these tasks.

WinGet built-in task

This built-in task applies a WinGet configuration to the dev box.

Parameters:

• configurationFile:

  • Type:string
  • The path to the WinGet config YAML file. The file must be located in the local machine.
  • Required:false

• downloadUrl:

  • Type:string
  • A publicly accessible URL where the config YAML file is stored. The file is downloaded to the path thatconfigurationFile specifies.
  • Required:false

• inlineConfigurationBase64:

  • Type:string
  • A Base64-encoded string of the WinGet config YAML file. The file is decoded to the path thatconfigurationFile specifies or to a temporary file if it isn't specified.
  • Required:false

• package:

  • Type:string
  • The name of the package to install.
  • If a config YAML file is provided under other parameters, the package name isn't needed.
  • Required:false

• version

  • Type:string
  • The version of the package to install.
  • If a config YAML file is provided under other parameters, there's no need for the package version.
  • Required:false

PowerShell built-in task

This built-in task runs a PowerShell command.

Parameters:

• command:
  • Type:string
  • The command to run.
  • Required:true

task.yaml files

Customization tasks are reusable units of installation code or environment configuration. Developers use PowerShell scripts to write them and use atask.yaml metadata file to describe them. Developers use these tasks to customize a dev box by referencing them from adevbox.yaml file.

When you define customization tasks, you can identify the tasks that are available to your developers for use indevbox.yaml files. You can restrict high-privilege actions, such as the ability to run any PowerShell command.

The following example of a task definition runs a PowerShell command in a specific working directory:

name: powershelldescription: Execute a powershell commandauthor: Microsoft Corporationcommand: ".\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

Attributes

name

Required: This unique identifier is used to refer to a task fromdevbox.yaml. The name must be unique in the context of the catalog where the task exists.

Naming must match existing Azure resource constraints. The name must be between 3 and 63 characters. It must start with an alphanumeric character. The name must consist of only alphanumeric characters and "-", ".", or "_". The "/" character is reserved.

name: powershell

description

Optional: This attribute describes the task.

description: This task executes a powershell command

inputs

Required: This attribute lists the parameters that this task takes as an input from adevbox.yaml file and uses while it runs the command. Each parent item represents the name of a parameter and supports these keys:

• type (required): The input data type for this parameter. Can bestring orint.
• defaultValue (required): The default value this parameter takes.
• required (required): The key that specifies whether this parameter is optional or required.
• description (required): A description of what this parameter represents.

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

command

Required: This command is used to fulfill this task. The provided command string runs in Windows PowerShell on the local machine.

command: ".\runcommand.ps1

Reference variables in commands

To reference parameters in a command, specify the variable name in double braces, for example,{{parameter_name}}. The values of these variables are interpolated before your command runs.

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

timeout

Optional: This variable specifies the maximum amount of time (in minutes) to wait for task execution to complete before the task times out. The default is 30 minutes.

timeout: 30

author

Optional: This variable identifies the task author to help with audits and troubleshooting.

author: Contoso Corporation

documentationURL

Optional: This variable links to the documentation for this task.

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

licenseURL

Optional: This variable links to the license for this task.

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