Referencia del esquema de personalizaciones

Las personalizaciones de Microsoft Dev Box permiten a los ingenieros y desarrolladores de plataformas preinstalar herramientas, clonar repositorios y configurar configuraciones en dev boxes usando archivos YAML. Esta referencia describe el esquema actual para los archivos YAML y las tareas integradas que soportan las personalizaciones de Dev Box.

Utiliza esta referencia cuando necesites:

  • Consulta las propiedades, tipos y valores predeterminados válidos en un archivo imagedefinition.yaml o task.yaml .
  • Confirma los parámetros que aceptan las tareas integradas ~/gitclone, ~/powershell, y ~/winget las tareas.
  • Entiende cómo tasks, userTasks, parameters, variables, y buildProperties funcionan juntos cuando Dev Box provisiona una imagen o aplica personalizaciones a un dev box.

Tipos de archivo de personalización

Las personalizaciones de Dev Box utilizan tres tipos de archivo YAML, cada uno con un propósito y público diferentes:

Archivo propósito Autor Dónde se ejecuta
imagedefinition.yaml Define una imagen reutilizable para un grupo de desarrolladores. Lista la imagen base, los parámetros, las variables, las tareas del sistema, las tareas del usuario y las propiedades de compilación que deben aplicar cuando Dev Box crea una definición de imagen. Ingeniero de plataforma o líder de equipo Almacenado en un catálogo adjunto a un proyecto; Aplicado a cada dev box creado a partir de un pool que hace referencia a la definición de imagen.
task.yaml Define una tarea de personalización reutilizable y parametrizada que se añade a un catálogo. Permite a los administradores envolver la lógica de PowerShell con metadatos, validación de parámetros, documentación y ajustes de ejecución. Ingeniero de plataformas Almacenado en un catálogo adjunto a un centro de desarrollo; llamado por nombre desde imagedefinition.yaml archivos de OR devbox.yaml .
devbox.yaml Archivo de personalización personal de usuario subido durante la creación de la dev box. Solo se aplica a la caja de desarrollo a la que está vinculado. Desarrollador individual Subido desde el disco local o referenciado desde un repositorio en el portal de desarrolladores.

Las tareas integradas ~/gitclone, ~/powershell, y ~/winget están disponibles en cualquier centro de desarrollo sin necesidad de adjuntar un catálogo. Para añadir tareas personalizadas más allá de las integradas, defínyelas en task.yaml archivos de un catálogo y llámalas por nombre desde tu archivo de definición de imagen o personalización de usuario. Para más información, consulta las personalizaciones de Microsoft Dev Box.

Archivos Imagedefinition.yaml

Úsalo imagedefinition.yaml para definir la imagen, los parámetros, las variables y las tareas de personalización que Dev Box aplica al crear una definición de imagen.

Ejemplo de archivo 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

Propiedades de Imagedefinition.yaml

Propiedad Obligatorio Tipo Description
$schema string o number Especifica la versión del esquema para el archivo.
name ✅ string Define el nombre amigable para la definición de la imagen.
descripción string Describe la definición de la imagen.
image ✅ string Identifica la imagen base que se usará para la imagen de dev box.
Parámetros object Define parámetros de entrada que las tareas pueden referenciar en la definición de imagen.
variables object Define valores reutilizables para la definición de la imagen.
Tasks Array de objetos de tarea Lista tareas de personalización del contexto del sistema para ejecutar durante el aprovisionamiento.
userTasks Array de objetos de tarea Lista tareas de personalización del contexto del usuario para ejecutar tras iniciar sesión.
buildPropiedades object Define configuraciones específicas para la creación de imágenes.

$schema

(cuerda o número)

Especifica la versión del esquema para el archivo. Los ejemplos actuales utilizan 1.0.

$schema: "1.0"

name

(cadena, requerida, 3-63 caracteres)

Especifica el nombre amigable que aparece al seleccionar una definición de imagen. Esta configuración controla el nombre de la definición de imagen que está disponible al crear y actualizar grupos. El nombre no puede contener /, ", [, ], :, <|, >, +, ?*&,;@=espacio en blanco, ni empezar por _ o .-

name: example-image-definition

description

(cuerda)

Describe el propósito de la definición de la imagen.

description: Install core tools and clone the project repository.

image

(cuerda, requerida)

Especifica la imagen base que se debe usar para la imagen de la caja de desarrollo. La imagen puede ser una imagen de marketplace o una imagen personalizada de una galería de computación adjunta de Azure en el formato gallery-name/image-name@version.

Ejemplos:

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

image: my-gallery/my-image@0.0.1

Para adjuntar una galería de computación de Azure, consulte Configurar la galería de cálculo de Azure para Microsoft Dev Box.

Para obtener una lista de imágenes a las que puede acceder tu centro de desarrollo, usa CLI de Azure:

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

Si es necesario, instala primero la extensión de CLI de Azure de Dev Center:

az extension add --name devcenter

parameters

(objeto)

Define parámetros de entrada nombrados que puedes referenciar en tareas usando {{parameterName}} sintaxis.

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

Propiedades del objeto de parámetro

Propiedad Obligatorio Tipo Description
tipo ✅ string Especifica el tipo de dato del parámetro.
permitido Matriz de cadenas Restringe el parámetro a una lista fija de valores de cadena.
default ✅ String, booleano o número Establece el valor predeterminado del parámetro.
descripción string Describe el parámetro.
validationRegex string Valida los valores de la cadena frente a una expresión regular.
minLength integer Establece la longitud mínima para los valores de la cadena.
maxLength integer Establece la longitud máxima para los valores de la cadena.

type

(cadena, obligatoria, valores permitidos: cadena, booleana, número)

Especifica el tipo de dato del parámetro.

allowed

(matriz de cuerdas)

Restringe el parámetro a un conjunto fijo de valores de cadena permitidos.

default

(se requiere una cadena, booleana o número)

Establece el valor predeterminado del parámetro.

description

(cuerda)

Describe el parámetro para autores y herramientas.

validationRegex

(cuerda)

Define una expresión regular que debe coincidir con los valores de la cadena.

minLength

(entero)

Establece la longitud mínima para los valores de la cadena.

maxLength

(entero)

Establece la longitud máxima para los valores de la cadena.

variables

(objeto)

Define variables nombradas que puedes reutilizar en la definición de la imagen.

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

Propiedades variables del objeto

Propiedad Obligatorio Tipo Description
tipo ✅ string Especifica el tipo de dato variable.
valor ✅ String, booleano o número Establece el valor variable.
descripción string Describe la variable.

type

(cadena, obligatoria, valores permitidos: cadena, booleana, número)

Especifica el tipo de dato variable.

value

(se requiere una cadena, booleana o número)

Establece el valor variable.

description

(cuerda)

Describe la variable para autores y herramientas.

tasks

(matriz de objetos de tarea)

Lista tareas de personalización para ejecutar en contexto de sistema durante la provisión. Los valores de entrada específicos que proporcionas varían según la tarea. Cada entrada de tarea debe incluir name y también puede definir displayName, description, parameters, y 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

La timeout propiedad es opcional y se mide en segundos cuando la usas en imagedefinition.yaml.

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

Propiedades de entrada de tareas

Propiedad Obligatorio Tipo Description
name ✅ string Identifica la tarea a invocar.
displayName string Proporciona texto corto de la interfaz para la tarea.
descripción string Describe lo que hace la tarea.
Parámetros object Proporciona valores de entrada para la tarea.
timeout integer Anula el tiempo de ejecución de la tarea en segundos.

name

(cuerda, requerida)

Identifica la tarea a ejecutar. Utiliza el ~/ prefijo para tareas integradas, como ~/winget, ~/powershell, y ~/gitclone.

displayName

(cuerda)

Proporciona texto de visualización corto para las superficies de la interfaz.

description

(cuerda)

Describe lo que hace la tarea en la definición de la imagen.

parameters

(objeto)

Define los valores de entrada que se pasan a la tarea. Los nombres de parámetros y los tipos de valores dependen de la tarea seleccionada.

Las definiciones de parámetros siguen el mismo esquema descrito para task.yaml las propiedades de los parámetros. Para más detalles, véase type, allowed, defaultdescription, validationRegex, minLength, maxLength, , y required.

timeout

(entero)

Anula el tiempo de ejecución de la tarea en segundos.

userTasks

(matriz de objetos de tarea)

Lista tareas de personalización para ejecutar en el contexto del usuario tras iniciar sesión. userTasks utiliza el mismo esquema de entrada de tareas que tasks.

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

buildProperties

(objeto)

Define configuraciones específicas de la compilación que personalizan el proceso de creación de la imagen.

buildProperties:
  networkConnection: corp-westus3

Propiedades de construcción Propiedades del objeto

Propiedad Obligatorio Tipo Description
redConexión string Selecciona la conexión de red para crear imágenes.

networkConnection

(cuerda)

Especifica la conexión de red utilizada durante la creación de la imagen. Utiliza esta configuración cuando las tareas de compilación necesiten acceso a recursos como repositorios privados o cuentas de almacenamiento que solo sean accesibles a través de una conexión de red específica. La conexión de red debe estar conectada al centro de desarrollo antes de poder usarla para crear imágenes.

buildProperties:
  networkConnection: my-westus3

Tareas integradas

Utiliza tareas integradas cuando necesites acciones de personalización comunes sin adjuntar un catálogo. Utiliza el ~/ prefijo para llamar a una tarea incorporada, por ejemplo ~/winget, ~/powershell, o ~/gitclone.

Tarea incorporada en GitClone

Usa la tarea integrada de GitClone para clonar un repositorio en la caja de desarrollo.

Ejemplo:

tasks:
  - name: ~/gitclone
    parameters:
      repositoryUrl: https://github.com/microsoft/calculator
      directory: C:\Workspaces
      branch: main
Propiedad Obligatorio Tipo Description
repositoryUrl ✅ string Especifica la URL del repositorio para clonar.
de directorio de string Establece el directorio bajo el cual se clona el repositorio.
rama string Selecciona una rama para clonar.
Pat string Proporciona un token de acceso personal para operaciones de clonación autenticadas.

repositoryUrl

(cuerda, requerida)

Especifica la URL del repositorio para clonar.

directory

(cadena, por defecto: C:\Workspaces)

Establece el directorio bajo el cual se clona el repositorio.

branch

(cuerda)

Selecciona una rama para clonar.

pat

(cuerda)

Proporciona un token de acceso personal para operaciones de clonación autenticadas. Cuando pat no se suministra, el clon se coloca en cola para el primer inicio de sesión del usuario. Cuando suministras pat, la tarea puede clonarse durante el aprovisionamiento. Usa una referencia secreta de Key Vault en lugar de un valor secreto en bruto.

La tarea integrada de GitClone también instala PowerShell 7, Git y Git LFS durante la ejecución.

Tarea integrada de PowerShell

Utiliza la tarea integrada de PowerShell para ejecutar un comando o script.

Ejemplo:

tasks:
  - name: ~/powershell
    parameters:
      command: Write-Host "Hello from Dev Box"
Propiedad Obligatorio Tipo Description
command string Ejecuta un comando en línea.
Directorio de trabajo string Establece el directorio de trabajo para el comando o script.
Script string Ejecuta un script PowerShell local o remoto.
scriptArgs string Proporciona argumentos para el guion.
scriptExecutionPolicy string Establece la política de ejecución para el script.

command

(cuerda)

Ejecuta un comando en línea. Si proporcionas command, los script, scriptArgs, y scriptExecutionPolicy los parámetros se ignoran.

workingDirectory

(cuerda)

Establece el directorio de trabajo para el comando o script.

script

(cuerda)

Especifica la ruta hacia un script PowerShell local o remoto para ejecutarse. Este parámetro se ignora cuando command se proporciona.

scriptArgs

(cuerda)

Proporciona argumentos para el guion. Este parámetro se ignora cuando command se proporciona.

scriptExecutionPolicy

(cadena, por defecto: Bypass)

Establece la política de ejecución para el script. Este parámetro se ignora cuando command se proporciona.

Tarea integrada de WinGet

Utiliza la tarea integrada de WinGet para instalar un paquete directamente o aplica un archivo de configuración de WinGet.

Important

La tarea integrada de WinGet no es la misma que el winget ejecutable. La tarea integrada utiliza el cmdlet WinGet de PowerShell.

Ejemplo:

tasks:
  - name: ~/winget
    parameters:
      package: GitHub.GitHubDesktop
      version: 3.4.16
Propiedad Obligatorio Tipo Description
Archivo de configuración string Apunta a un archivo de configuración local de WinGet.
downloadUrl string Descarga un archivo de configuración desde una URL pública.
inlineConfigurationBase64 string Suministra un archivo de configuración WinGet codificado en Base64.
package string Instala un paquete directamente por nombre.
versión string Instala una versión específica del paquete.

configurationFile

(cuerda)

Apunta a un archivo YAML de configuración WinGet en la máquina local.

downloadUrl

(cuerda)

Especifica una URL pública para un archivo YAML de configuración de WinGet. El archivo se descarga en la ruta en configurationFile.

inlineConfigurationBase64

(cuerda)

Suministra un archivo YAML de configuración WinGet codificado en Base64. La tarea lo decodifica a configurationFile, o a un archivo temporal si configurationFile no está activado.

package

(cuerda)

Instala un paquete directamente por nombre. Si usas un código fuente de archivo de configuración, no necesitas proporcionar packagearchivos .

version

(cuerda)

Instala una versión específica del paquete. Si usas un código fuente de archivo de configuración, no necesitas proporcionar versionarchivos .

archivos task.yaml

Úsalo task.yaml para definir una tarea de personalización reutilizable en un catálogo. Una definición de tarea describe el comando, metadatos, parámetros, documentación y configuración de ejecución de la tarea.

Cuando defines tareas de personalización, identificas las tareas que están disponibles para los desarrolladores para su uso en imagedefinition.yaml archivos o devbox.yaml archivos. Puedes usar definiciones de tareas para restringir acciones de alto privilegio, como la posibilidad de ejecutar comandos arbitrarios de PowerShell.

Ejemplo de archivo 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

El siguiente ejemplo muestra una definición de tarea que ejecuta un comando PowerShell en un directorio de trabajo específico:

$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.

Propiedades de Task.yaml

Propiedad Obligatorio Tipo Description
$schema ✅ string Especifica la versión del esquema para el archivo de tareas.
name ✅ string Define el identificador de tarea.
command ✅ string Proporciona el comando PowerShell que implementa la tarea.
descripción string Describe la tarea.
autor string Identifica al autor de la tarea.
issueNotificaciónCorreo electrónico string Proporciona un correo de contacto para problemas de tareas.
documentation URL string Enlaces a la documentación de tareas.
licenseURL string Enlaces a la licencia de tarea.
Palabras clave Matriz de cadenas Lista palabras clave de búsqueda para la tarea.
Parámetros object Define las entradas que acepta la tarea.
timeout integer Establece el tiempo de espera por defecto en minutos.
documentación object Añade notas y ejemplos de invocación de tareas para consumidores.
reinicioNecesario booleano Indica si la tarea requiere un reinicio tras la ejecución.

$schema

(cuerda, requerida)

Especifica la versión del esquema para la definición de la tarea. Los ejemplos actuales utilizan 1.0.

name

(cuerda, requerida)

Define el identificador utilizado para referenciar la tarea desde imagedefinition.yaml o devbox.yaml archivos. El nombre debe ser único en el contexto del catálogo donde existe la tarea.

Usa las mismas restricciones de nombres que otros artefactos de personalización de Dev Box. El nombre debe tener entre 3 y 63 caracteres, comenzar con un carácter alfanumérico y contener solo caracteres alfanuméricos, -, ., o _. El / carácter está reservado.

name: install-vsix-extension

command

(cuerda, requerida)

Especifica el comando PowerShell que implementa la tarea. El comando se ejecuta en PowerShell de Windows en la máquina local. Usa {{parameterName}} la sintaxis para referenciar los valores de los parámetros en la cadena de comandos.

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

Por ejemplo:

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

description

(cuerda)

Describe el propósito de la tarea.

description: This task executes a PowerShell command.

author

(cuerda)

Identifica al autor de la tarea para auditorías y resolución de problemas.

author: Contoso Corporation

issueNotificationEmail

(cuerda)

Proporciona una dirección de correo electrónico a la que los usuarios pueden contactar si tienen problemas con la tarea. La funcionalidad del producto no consume este valor.

documentationURL

(cuerda)

Enlaces a la documentación de la tarea.

documentationURL: https://link.to/documentation

licenseURL

(cuerda)

Enlaces a la licencia de tarea.

licenseURL: https://link.to/license

keywords

(matriz de cuerdas)

Enumera palabras clave que ayudan a los consumidores a encontrar la tarea.

parameters

(objeto)

Define parámetros de entrada nombrados para la tarea. Cada elemento hijo representa un nombre de parámetro y puede definir el tipo de parámetro, valores permitidos, valor por defecto, descripción, reglas de validación, límites de longitud y si el parámetro es necesario.

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

Propiedades de definición de parámetros

Propiedad Obligatorio Tipo Description
tipo ✅ string Especifica el tipo de dato de entrada.
permitido Matriz de cadenas Restringe la entrada a una lista fija de valores de cadena.
default String, booleano o número Establece el valor predeterminado de la entrada.
descripción string Describe la entrada.
validationRegex string Valida los valores de la cadena frente a una expresión regular.
minLength integer Establece la longitud mínima para los valores de la cadena.
maxLength integer Establece la longitud máxima para los valores de la cadena.
required booleano Indica si la entrada debe ser suministrada.

type

(cadena, obligatoria, valores permitidos: cadena, booleana, número)

Especifica el tipo de dato de entrada.

allowed

(matriz de cuerdas)

Restringe la entrada a un conjunto fijo de valores de cadena permitidos.

default

(string, boolean o número)

Establece el valor predeterminado de la entrada.

description

(cuerda)

Describe la entrada.

validationRegex

(cuerda)

Define una expresión regular que debe coincidir con los valores de la cadena.

minLength

(entero)

Establece la longitud mínima para los valores de la cadena.

maxLength

(entero)

Establece la longitud máxima para los valores de la cadena.

required

(booleano)

Indica si la entrada debe ser suministrada. Si se omite, se utiliza el valor predeterminado false.

timeout

(entero, por defecto: 30)

Establece el tiempo de espera por defecto de la tarea en minutos. Si no especificas un valor, el valor por defecto son 30 minutos.

timeout: 30

documentation

(objeto)

Proporciona notas y ejemplos de invocación que los consumidores de tareas pueden usar cuando añaden la tarea a una definición de imagen.

Propiedades del objeto de documentación

Propiedad Obligatorio Tipo Description
notas string Proporciona orientación a los consumidores de la tarea.
Ejemplos Array de objetos de tarea Muestra cómo invocar la tarea desde un archivo YAML.

notes

(cuerda)

Añade orientación o advertencias para los consumidores de la tarea.

examples

(matriz de objetos de tarea)

Muestra ejemplos de invocaciones de tareas usando el mismo esquema que las entradas de tarea en imagedefinition.yaml.

rebootRequired

(booleano, por defecto: falso)

Indica si la tarea requiere un reinicio tras la ejecución.

Contenido relacionado

  • Last updated on