Compartir a través de

Referencia del esquema de personalizaciones

En este artículo de referencia se proporciona información detallada sobre los imagedefinition.yaml archivos y task.yaml que se usan para personalizar Microsoft Dev Box. Los desarrolladores pueden usar estos archivos YAML para definir tareas para el aprovisionamiento y la configuración de cuadros de desarrollo. Los archivos ayudan a garantizar la coherencia y la eficacia en los entornos de desarrollo. En este artículo se tratan el esquema, los atributos necesarios y los ejemplos de ambos tipos de archivo, junto con tareas integradas como PowerShell y WinGet.

Archivos Imagedefinition.yaml

Puede usar un archivo YAML de Dev Box para definir tareas de personalización que deben ejecutarse durante la creación de Dev Box. Un devbox.yaml archivo podría estar en el mismo repositorio que el origen principal que usa el equipo de desarrollo o el archivo podría estar en un repositorio centralizado de configuraciones.

YaML de definición de imagen de ejemplo:

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

nombre

Obligatorio: Este nombre descriptivo para la definición de imagen está asociado a este devbox.yaml archivo. Esta configuración controla el nombre de la definición de imagen que está disponible al crear y actualizar grupos.

name: myVSDevBox

imagen

Obligatorio: La imagen que desea usar como imagen base para la definición de imagen puede ser una imagen de Marketplace:

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

O bien, puede ser una imagen personalizada desde una instancia adjunta de Azure Compute Gallery:

image: galleryname/imagename@version

Para obtener información sobre cómo adjuntar una instancia de Azure Compute Gallery al centro de desarrollo, consulte Configuración de Azure Compute Gallery para Microsoft Dev Box.

Para obtener una lista de imágenes a las que tiene acceso el centro de desarrollo, use este az cli comando:

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

Necesita la extensión del centro de desarrollo az cli :

az extension add --name devcenter

tareas

Obligatorio: Esta colección de objetos se compone de tareas de personalización de Dev Box que se ejecutarán al aprovisionar un cuadro de desarrollo. Las entradas específicas que se proporcionan a una tarea varían según la tarea.

Ejemplo:

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

Todas las tareas admiten la timeout propiedad , que es opcional.

Ejemplo:

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

Tareas integradas

PowerShell y WinGet están disponibles como tareas integradas. Puede invocarlos directamente sin adjuntar un catálogo en el nivel del centro de desarrollo que defina la implementación de estas tareas.

Tarea integrada de WinGet

Esta tarea integrada aplica una configuración de WinGet al cuadro de desarrollo.

Parámetros:

  • configurationFile:

    • Tipo: string
    • Ruta de acceso al archivo YAML de configuración de WinGet. El archivo debe encontrarse en el equipo local.
    • Obligatorio: false

  • downloadUrl:

    • Tipo: string
    • Dirección URL accesible públicamente donde se almacena el archivo YAML de configuración. El archivo se descarga en la ruta de acceso que configurationFile especifica.
    • Obligatorio: false

  • inlineConfigurationBase64:

    • Tipo: string
    • Cadena codificada en Base64 del archivo YAML de configuración de WinGet. El archivo se descodifica en la ruta de acceso que configurationFile especifica o en un archivo temporal si no se especifica.
    • Obligatorio: false

  • package:

    • Tipo: string
    • Nombre del paquete que se va a instalar.
    • Si se proporciona un archivo YAML de configuración en otros parámetros, el nombre del paquete no es necesario.
    • Obligatorio: false

  • version

    • Tipo: string
    • Versión del paquete que se va a instalar.
    • Si se proporciona un archivo YAML de configuración en otros parámetros, no es necesario la versión del paquete.
    • Obligatorio: false

Tarea integrada de PowerShell

Esta tarea integrada ejecuta un comando de PowerShell.

Parámetros:

  • command:
    • Tipo: string
    • Comando que debe ejecutar.
    • Obligatorio: true

archivos task.yaml

Las tareas de personalización son unidades reutilizables de código de instalación o configuración del entorno. Los desarrolladores usan scripts de PowerShell para escribirlos y usar un task.yaml archivo de metadatos para describirlos. Los desarrolladores usan estas tareas para personalizar un cuadro de desarrollo haciendo referencia a ellos desde un devbox.yaml archivo.

Al definir tareas de personalización, puede identificar las tareas que están disponibles para los desarrolladores para usarlas en devbox.yaml archivos. Puede restringir las acciones con privilegios elevados, como la capacidad de ejecutar cualquier comando de PowerShell.

En el ejemplo siguiente de una definición de tarea se ejecuta un comando de PowerShell en un directorio de trabajo específico:

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

Atributos

nombre

Obligatorio: Este identificador único se usa para hacer referencia a una tarea desde devbox.yaml. El nombre debe ser único en el contexto del catálogo donde existe la tarea.

La nomenclatura debe coincidir con las restricciones de recursos de Azure existentes. El nombre debe tener entre 3 y 63 caracteres. Debe comenzar con un carácter alfanumérico. El nombre solo debe constar de caracteres alfanuméricos y "-", "." o "_". El carácter "/" está reservado.

name: powershell

descripción

Opcional: Este atributo describe la tarea.

description: This task executes a powershell command

Entradas

Obligatorio: Este atributo enumera los parámetros que esta tarea toma como entrada de un devbox.yaml archivo y usa mientras ejecuta el comando . Cada elemento primario representa el nombre de un parámetro y admite estas claves:

  • type (obligatorio): tipo de datos de entrada para este parámetro. Puede ser string o int.
  • defaultValue (obligatorio): el valor predeterminado que toma este parámetro.
  • required (obligatorio): clave que especifica si este parámetro es opcional o necesario.
  • description (obligatorio): una descripción de lo que representa este parámetro.
inputs:
  command:
    type: string
    defaultValue: ""
    required: true
    description: The command to execute

comando

Obligatorio: Este comando se usa para completar esta tarea. La cadena de comandos proporcionada se ejecuta en Windows PowerShell en el equipo local.

command: ".\runcommand.ps1

Variables de referencia en comandos

Para hacer referencia a parámetros en un comando, especifique el nombre de la variable en llaves dobles, por ejemplo, {{parameter_name}}. Los valores de estas variables se interpolan antes de que se ejecute el comando.

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

tiempo de expiración

Opcional: Esta variable especifica la cantidad máxima de tiempo (en minutos) que se debe esperar a que se complete la ejecución de la tarea antes de que se agote el tiempo de espera de la tarea. El valor predeterminado es 30 minutos.

timeout: 30

autor

Opcional: Esta variable identifica al autor de la tarea para ayudar con las auditorías y la solución de problemas.

author: Contoso Corporation

documentationURL

Opcional: Esta variable vincula a la documentación de esta tarea.

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

licenseURL

Opcional: Esta variable vincula a la licencia de esta tarea.

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