Referência de esquema de personalizações

As customizações do Microsoft Dev Box permitem que engenheiros e desenvolvedores de plataforma pré-instalem ferramentas, clonem repositórios e configurem configurações em dev boxes usando arquivos YAML. Esta referência descreve o esquema atual para os arquivos YAML e as tarefas embutidas que as customizações do Dev Box suportam.

Use esta referência quando precisar:

• Procure as propriedades, tipos e padrões que são válidos em um arquivo imagedefinition.yaml ou task.yaml .
• Confirme os parâmetros que as tarefas embutidas ~/gitclone, ~/powershell, e ~/winget aceitam.
• Entenda como tasks, userTasks, parameters, variables, e buildProperties funcionam juntos quando o Dev Box fornece uma imagem ou aplica personalizações a um dev box.

Tipos de arquivo de personalização

As customizações do Dev Box usam três tipos de arquivo YAML, cada um com um propósito e público diferentes:

As tarefas embutidas ~/gitclonede , ~/powershell, e ~/winget estão disponíveis em qualquer centro de desenvolvimento sem necessidade de anexar um catálogo. Para adicionar tarefas personalizadas além dessas embutidas, defina-as em task.yaml arquivos em um catálogo e chame-as pelo nome a partir da sua definição de imagem ou do arquivo de personalização do usuário. Para mais informações, veja as personalizações do Microsoft Dev Box.

Arquivos Imagedefinition.yaml

Use imagedefinition.yaml para definir a imagem, parâmetros, variáveis e tarefas de personalização que o Dev Box aplica ao criar uma definição de imagem.

Arquivo imagedefinition.yaml de exemplo

$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

Propriedades do Imagedefinition.yaml

$schema

(fio ou número)

Especifica a versão do esquema para o arquivo. Exemplos atuais usam 1.0.

$schema: "1.0"

name

(string, obrigatório, 3-63 caracteres)

Especifica o nome amigável mostrado ao selecionar uma definição de imagem. Essa configuração controla o nome da definição de imagem disponível quando você cria e atualiza pools. O nome não pode conter /, ", [, :], @><+|?&,;*=espaço em branco, nem começar com _ ou .-

name: example-image-definition

description

(corda)

Descreve o propósito da definição da imagem.

description: Install core tools and clone the project repository.

image

(corda, necessária)

Especifica a imagem base a usar para a imagem da dev box. A imagem pode ser uma imagem de marketplace ou uma imagem personalizada de uma galeria de computação do Azure anexada no formato gallery-name/image-name@version.

Exemplos:

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

image: my-gallery/my-image@0.0.1

Para anexar uma Galeria de Computação do Azure, veja Configurar a Galeria de Computação do Azure para Microsoft Dev Box.

Para obter uma lista de imagens acessadas pelo seu centro de desenvolvimento, use o CLI do Azure:

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

Se necessário, instale primeiro a extensão Dev Center CLI do Azure:

az extension add --name devcenter

parameters

(objeto)

Define parâmetros de entrada nomeados que você pode referenciar em tarefas usando {{parameterName}} sintaxe.

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

Propriedades do objeto de parâmetros

type

(string, obrigatório, valores permitidos: string, boolean, número)

Especifica o tipo de dado do parâmetro.

allowed

(matriz de cordas)

Restringe o parâmetro a um conjunto fixo de valores de cadeia permitidos.

default

(string, boolean ou número, necessário)

Define o valor padrão para o parâmetro.

description

(corda)

Descreve o parâmetro para autores e ferramentas.

validationRegex

(corda)

Define uma expressão regular que os valores da cadeia devem corresponder.

minLength

(inteiro)

Define o comprimento mínimo para valores de cordas.

maxLength

(inteiro)

Define o comprimento máximo para os valores das cordas.

variables

(objeto)

Define variáveis nomeadas que você pode reutilizar na definição da imagem.

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

Propriedades do objeto variável

type

(string, obrigatório, valores permitidos: string, boolean, número)

Especifica o tipo de dado variável.

value

(string, boolean ou número, necessário)

Define o valor da variável.

description

(corda)

Descreve a variável para autores e ferramentas.

tasks

(matriz de objetos de tarefa)

Lista tarefas de personalização para serem executadas no contexto do sistema durante o provisionamento. Os valores específicos de entrada que você fornece variam conforme a tarefa. Cada entrada de tarefa deve incluir name e também pode definir displayName, description, parameters, e 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

A timeout propriedade é opcional e é medida em segundos quando você a usa em imagedefinition.yaml.

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

Propriedades de entrada de tarefas

name

(corda, necessária)

Identifica a tarefa a ser executada. Use o ~/ prefixo para tarefas embutidas, como ~/winget, ~/powershell, e ~/gitclone.

displayName

(corda)

Fornece texto de exibição curto para superfícies da interface.

description

(corda)

Descreve o que a tarefa faz na definição da imagem.

parameters

(objeto)

Define os valores de entrada passados para a tarefa. Nomes de parâmetros e tipos de valor dependem da tarefa selecionada.

As definições de parâmetros seguem o mesmo esquema descrito para task.yaml propriedades de parâmetro. Para detalhes, veja type, allowed, default, validationRegexdescription, , minLength, maxLength, , e required.

timeout

(inteiro)

Anula o tempo limite de execução da tarefa em segundos.

userTasks

(matriz de objetos de tarefa)

Lista tarefas de personalização para executar no contexto do usuário após o login. userTasks usa o mesmo esquema de entrada de tarefa que tasks.

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

buildProperties

(objeto)

Define configurações específicas de build que personalizam o processo de construção da imagem.

buildProperties:
  networkConnection: corp-westus3

Propriedades de build Propriedades do objeto

networkConnection

(corda)

Especifica a conexão de rede usada durante a criação da imagem. Use essa configuração quando tarefas de build precisarem de acesso a recursos como repositórios privados ou contas de armazenamento que só podem ser acessadas por meio de uma conexão de rede específica. A conexão de rede precisa estar conectada ao centro de desenvolvimento antes de poder usá-la para criação de imagens.

buildProperties:
  networkConnection: my-westus3

Tarefas integradas

Use tarefas integradas quando precisar de ações comuns de personalização, sem anexar um catálogo. Use o ~/ prefixo para chamar uma tarefa embutida, por exemplo ~/winget, ~/powershell, ou ~/gitclone.

• Tarefa embutida no GitClone
• Tarefa embutida do PowerShell
• Tarefa embutida WinGet

Tarefa embutida no GitClone

Use a tarefa embutida do GitClone para clonar um repositório na dev box.

Exemplo:

tasks:
  - name: ~/gitclone
    parameters:
      repositoryUrl: https://github.com/microsoft/calculator
      directory: C:\Workspaces
      branch: main

repositoryUrl

(corda, necessária)

Especifica a URL do repositório a ser clonada.

directory

(string, padrão: C:\Workspaces)

Define o diretório sob o qual o repositório é clonado.

branch

(corda)

Seleciona um ramo para clonar.

pat

(corda)

Fornece um token de acesso pessoal para operações de clonagem autenticadas. Quando pat não é fornecido, o clone é colocado na fila para o primeiro login do usuário. Quando você fornece pat, a tarefa pode ser clonada durante o provisionamento. Use uma referência secreta do Key Vault em vez de um valor secreto bruto.

A tarefa embutida do GitClone também instala PowerShell 7, Git e Git LFS durante a execução.

Tarefa interna do PowerShell

Use a tarefa embutida do PowerShell para executar um comando ou script.

Exemplo:

tasks:
  - name: ~/powershell
    parameters:
      command: Write-Host "Hello from Dev Box"

command

(corda)

Roda um comando inline. Se você fornecer command, os script, scriptArgs, e scriptExecutionPolicy os parâmetros são ignorados.

workingDirectory

(corda)

Define o diretório de trabalho para o comando ou script.

script

(corda)

Especifica o caminho para um script PowerShell local ou remoto a ser executado. Esse parâmetro é ignorado quando command é fornecido.

scriptArgs

(corda)

Fornece argumentos para o roteiro. Esse parâmetro é ignorado quando command é fornecido.

scriptExecutionPolicy

(string, padrão: Bypass)

Define a política de execução do script. Esse parâmetro é ignorado quando command é fornecido.

Tarefa interna do WinGet

Use a tarefa embutida do WinGet para instalar um pacote diretamente ou aplicar um arquivo de configuração do WinGet.

Exemplo:

tasks:
  - name: ~/winget
    parameters:
      package: GitHub.GitHubDesktop
      version: 3.4.16

configurationFile

(corda)

Aponta para um arquivo YAML de configuração do WinGet na máquina local.

downloadUrl

(corda)

Especifica uma URL pública para um arquivo YAML de configuração do WinGet. O arquivo é baixado para o caminho em configurationFile.

inlineConfigurationBase64

(corda)

Fornece um arquivo YAML de configuração WinGet codificado em Base64. A tarefa decodifica para configurationFile, ou para um arquivo temporário se configurationFile não estiver ativado.

package

(corda)

Instala um pacote diretamente pelo nome. Se você usar uma fonte de arquivo de configuração, não precisa fornecer package.

version

(corda)

Instala uma versão específica do pacote. Se você usar uma fonte de arquivo de configuração, não precisa fornecer version.

arquivos task.yaml

Use task.yaml para definir uma tarefa de personalização reutilizável em um catálogo. Uma definição de tarefa descreve o comando, metadados, parâmetros, documentação e configurações de execução da tarefa.

Ao definir tarefas de personalização, você identifica as tarefas disponíveis para desenvolvedores usarem em imagedefinition.yaml arquivos ou devbox.yaml arquivos. Você pode usar definições de tarefas para restringir ações de alto privilégio, como a capacidade de executar comandos PowerShell arbitrários.

Exemplo de arquivo 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

O exemplo a seguir mostra uma definição de tarefa que executa um comando PowerShell em um diretório de trabalho 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.

Propriedades do Task.yaml

$schema

(corda, necessária)

Especifica a versão do esquema para a definição da tarefa. Exemplos atuais usam 1.0.

name

(corda, necessária)

Define o identificador usado para referenciar a tarefa de imagedefinition.yaml ou devbox.yaml arquivos. O nome deve ser exclusivo no contexto do catálogo em que a tarefa existe.

Use as mesmas restrições de nomes que outros artefatos de personalização do Dev Box. O nome deve ter entre 3 e 63 caracteres, começar com um caractere alfanumérico e conter apenas caracteres alfanuméricos, -, ., ou _. O / caractere é reservado.

name: install-vsix-extension

command

(corda, necessária)

Especifica o comando PowerShell que implementa a tarefa. O comando roda no PowerShell do Windows na máquina local. Use {{parameterName}} a sintaxe para referenciar valores de parâmetros na string de comandos.

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

Por exemplo:

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

description

(corda)

Descreve o propósito da tarefa.

description: This task executes a PowerShell command.

author

(corda)

Identifica o autor da tarefa para auditorias e solução de problemas.

author: Contoso Corporation

issueNotificationEmail

(corda)

Fornece um endereço de e-mail que os usuários podem contatar caso tenham problemas com a tarefa. A funcionalidade do produto não consome esse valor.

documentationURL

(corda)

Links para a documentação da tarefa.

documentationURL: https://link.to/documentation

licenseURL

(corda)

Links para a licença da tarefa.

licenseURL: https://link.to/license

keywords

(matriz de cordas)

Lista palavras-chave que ajudam os consumidores a encontrar a tarefa.

parameters

(objeto)

Define parâmetros de entrada nomeados para a tarefa. Cada item filho representa um nome de parâmetro e pode definir o tipo de parâmetro, valores permitidos, valor padrão, descrição, regras de validação, limites de comprimento e se o parâmetro é necessário.

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

Propriedades da definição de parâmetros

type

(string, obrigatório, valores permitidos: string, boolean, número)

Especifica o tipo de dado de entrada.

allowed

(matriz de cordas)

Restringe a entrada a um conjunto fixo de valores de string permitidos.

default

(string, boolean ou número)

Define o valor padrão para a entrada.

description

(corda)

Descreve a entrada.

validationRegex

(corda)

Define uma expressão regular que os valores da cadeia devem corresponder.

minLength

(inteiro)

Define o comprimento mínimo para valores de cordas.

maxLength

(inteiro)

Define o comprimento máximo para os valores das cordas.

required

(booleano)

Indica se a entrada deve ser fornecida. Se omitido, o padrão será false.

timeout

(inteiro, padrão: 30)

Define o tempo limite padrão da tarefa em minutos. Se você não especificar um valor, o padrão é 30 minutos.

timeout: 30

documentation

(objeto)

Fornece notas e exemplos de invocação que os consumidores de tarefas podem usar ao adicionar a tarefa a uma definição de imagem.

Propriedades do objeto de documentação

notes

(corda)

Adiciona orientações ou ressalvas para os consumidores da tarefa.

examples

(matriz de objetos de tarefa)

Mostra exemplos de invocações de tarefas usando o mesmo esquema das entradas de tarefas em imagedefinition.yaml.

rebootRequired

(booleano, padrão: falso)

Indica se a tarefa precisa de reinicialização após a execução.

Conteúdo relacionado

• Configure as customizações da equipe - Crie imagedefinition.yaml arquivos e aplique em um grupo de dev box.
• Configure um arquivo de personalização de usuário para sua dev box - Crie e envie um arquivo pessoal devbox.yaml .
• Configure tarefas para personalizações do Dev Box - Crie task.yaml arquivos e publique-os em um catálogo.
• Conectar-se aos recursos do Azure ou clonar repositórios privados