Referência de esquema de personalizações

As personalizações do Microsoft Dev Box permitem que engenheiros e programadores de plataforma pré-instalem ferramentas, clonem repositórios e configurem definições nas dev boxes usando ficheiros YAML. Esta referência descreve o esquema atual para os ficheiros YAML e as tarefas incorporadas que as personalizações do Dev Box suportam.

Use esta referência quando precisar:

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

Tipos de ficheiros de personalização

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

As tarefas incorporadas ~/gitclone, ~/powershell, e ~/winget estão disponíveis em qualquer centro de desenvolvimento sem necessidade de anexar um catálogo. Para adicionar tarefas personalizadas para além dessas incorporadas, defina-as em task.yaml ficheiros num catálogo e chame-as pelo nome a partir da definição de imagem ou ficheiro de personalização do utilizador. Para mais informações, consulte 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.

Ficheiro 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 de Imagedefinition.yaml

$schema

(fio ou número)

Especifica a versão do esquema para o ficheiro. Exemplos atuais utilizam 1.0.

$schema: "1.0"

name

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

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

Examples:

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, consulte Configurar a Galeria de Computação do Azure para Microsoft Dev Box.

Para obter uma lista de imagens a que o seu centro de desenvolvimento pode aceder, 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 podes referenciar em tarefas usando {{parameterName}} sintaxe.

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

Propriedades do objeto paramétrico

type

(string, obrigatório, valores permitidos: string, boolean, number)

Especifica o tipo de dado do parâmetro.

allowed

(conjunto de cordas)

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

default

(fio, booleano ou número, necessário)

Define o valor padrão do 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 os valores das cordas.

maxLength

(inteiro)

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

variables

(objeto)

Define variáveis nomeadas que podes reutilizar na definição da imagem.

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

Propriedades dos objetos variáveis

type

(string, obrigatório, valores permitidos: string, boolean, number)

Especifica o tipo de dado variável.

value

(fio, booleano ou número, necessário)

Define o valor da variável.

description

(corda)

Descreve a variável para autores e ferramentas.

tasks

(array de objetos de tarefa)

Lista tarefas de personalização para executar no contexto do sistema durante o provisionamento. Os valores específicos de entrada que forneces variam consoante a tarefa. Cada entrada de tarefa deve incluir name e pode também 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 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 executar. Use o ~/ prefixo para tarefas incorporadas, como ~/winget, ~/powershell, e ~/gitclone.

displayName

(corda)

Fornece texto curto para as 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. Os nomes dos parâmetros e os tipos de valor dependem da tarefa selecionada.

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

timeout

(inteiro)

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

userTasks

(array de objetos de tarefa)

Lista tarefas de personalização para executar no contexto do utilizador após iniciar sessão. userTasks usa o mesmo esquema de entrada de tarefas que tasks.

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

buildProperties

(objeto)

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

buildProperties:
  networkConnection: corp-westus3

Propriedades de construção Propriedades do objeto

networkConnection

(corda)

Especifica a ligação de rede usada durante a criação da imagem. Use esta configuração quando as tarefas de construção precisarem de acesso a recursos como repositórios privados ou contas de armazenamento que só sejam acedidos através de uma ligação de rede específica. A ligação de rede tem de estar ligada ao centro de desenvolvimento antes de a poderes usar para criar imagens.

buildProperties:
  networkConnection: my-westus3

Tarefas incorporadas

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

• Tarefa incorporada no GitClone
• Tarefa incorporada no PowerShell
• Tarefa incorporada do WinGet

Tarefa incorporada no GitClone

Usa a tarefa incorporada 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 clonar.

directory

(cadeia, 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 utilizador. Quando forneces pat, a tarefa pode clonar durante o provisionamento. Use uma referência secreta do Key Vault em vez de um valor secreto bruto.

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

Tarefa interna do PowerShell

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

Exemplo:

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

command

(corda)

Executa um comando inline. Se 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. Este parâmetro é ignorado quando command é fornecido.

scriptArgs

(corda)

Fornece argumentos para o guião. Este parâmetro é ignorado quando command é fornecido.

scriptExecutionPolicy

(string, por defeito: Bypass)

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

Tarefa interna do WinGet

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

Exemplo:

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

configurationFile

(corda)

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

downloadUrl

(corda)

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

inlineConfigurationBase64

(corda)

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

package

(corda)

Instala um pacote diretamente pelo nome. Se usares uma fonte de ficheiro de configuração, não precisas de fornecer package.

version

(corda)

Instala uma versão específica do pacote. Se usares uma fonte de ficheiro de configuração, não precisas de fornecer version.

arquivos task.yaml

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

Quando defines tarefas de personalização, identificas as tarefas que estão disponíveis para os programadores usarem em imagedefinition.yaml ficheiros de OU devbox.yaml . Pode usar definições de tarefas para restringir ações de alto privilégio, como a possibilidade de executar comandos PowerShell arbitrários.

Ficheiro task.yaml de exemplo

$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 seguinte mostra uma definição de tarefa que executa um comando PowerShell num 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 utilizam 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 onde a tarefa existe.

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

name: install-vsix-extension

command

(corda, necessária)

Especifica o comando PowerShell que implementa a tarefa. O comando corre no PowerShell do Windows na máquina local. Use {{parameterName}} a sintaxe para referenciar valores de parâmetros na cadeia 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 resolução de problemas.

author: Contoso Corporation

issueNotificationEmail

(corda)

Fornece um endereço de email que os utilizadores podem contactar caso tenham problemas com a tarefa. A funcionalidade do produto não consome esse valor.

documentationURL

(corda)

Ligações para a documentação da tarefa.

documentationURL: https://link.to/documentation

licenseURL

(corda)

Ligações para a licença da tarefa.

licenseURL: https://link.to/license

keywords

(conjunto 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 permitido, 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 de definição de parâmetros

type

(string, obrigatório, valores permitidos: string, boolean, number)

Especifica o tipo de dados de entrada.

allowed

(conjunto de cordas)

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

default

(corda, booleano 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 os valores das 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 é false.

timeout

(inteiro, padrão: 30)

Define o timeout padrão da tarefa em minutos. Se não especificar um valor, o valor padrão é 30 minutos.

timeout: 30

documentation

(objeto)

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

Propriedades do objeto de documentação

notes

(corda)

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

examples

(array de objetos de tarefa)

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

rebootRequired

(booleano, padrão: falso)

Indica se a tarefa requer um reinício após a execução.

Conteúdo relacionado

• Configura as personalizações da equipa - Cria imagedefinition.yaml ficheiros e aplica-os a um grupo de dev boxs.
• Configura um ficheiro de personalização de utilizador para a tua dev box - Cria e carrega um ficheiro pessoal devbox.yaml .
• Configurar tarefas para personalizações do Dev Box - Criar task.yaml ficheiros de autor e publicá-los através de um catálogo.
• Conecte-se a recursos Azure ou clone repositórios privados