Compartilhar via

Referência de esquema de personalizações

Este artigo de referência fornece informações detalhadas sobre os imagedefinition.yaml arquivos usados task.yaml para personalizar o Microsoft Dev Box. Os desenvolvedores podem usar esses arquivos YAML para definir tarefas para provisionar e configurar caixas de desenvolvimento. Os arquivos ajudam a garantir a consistência e a eficiência em ambientes de desenvolvimento. Este artigo aborda o esquema, os atributos necessários e os exemplos para ambos os tipos de arquivo, juntamente com tarefas internas, como o PowerShell e o WinGet.

Arquivos Imagedefinition.yaml

Você pode usar um arquivo YAML do Dev Box para definir tarefas de personalização que devem ser executadas durante a criação do Dev Box. Um devbox.yaml arquivo pode residir no mesmo repositório que a fonte primária que a equipe de desenvolvimento usa ou o arquivo pode estar em um repositório centralizado de configurações.

Exemplo de definição de imagem YAML:

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

nome

Necessário: Esse nome amigável para a definição de imagem está associado a esse devbox.yaml arquivo. Essa configuração controla o nome da definição de imagem disponível quando você cria e atualiza pools.

name: myVSDevBox

imagem

Necessário: A imagem que você deseja usar como a imagem base para sua definição de imagem pode ser uma imagem do marketplace:

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

Ou pode ser uma imagem personalizada de uma instância anexada da Galeria de Computação do Azure:

image: galleryname/imagename@version

Para saber como anexar uma instância da Galeria de Computação do Azure ao centro de desenvolvimento, consulte Configurar a Galeria de Computação do Azure para Microsoft Dev Box.

Para obter uma lista de imagens às quais o centro de desenvolvimento tem acesso, use este az cli comando:

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

Você precisa da extensão do centro az cli de desenvolvimento:

az extension add --name devcenter

Propriedades de compilação

Essa coleção de objetos é composta por propriedades de build que podem ser usadas para personalizar o processo de build para a imagem.

networkConnection

Opcional: Especifica a conexão de rede a ser usada durante a criação da imagem. Essa conexão de rede permite que tarefas de personalização acessem recursos, como contas de armazenamento ou repositórios, que podem ser acessados pela rede especificada. A conexão de rede deve ser anexada ao Centro de Desenvolvimento antes de ser usada para a criação da imagem.

Exemplo:

buildProperties:
    networkConnection: "my-westus3"

tarefas

Necessário: Essa coleção de objetos é composta por tarefas de personalização do Dev Box a serem executadas quando você provisiona uma caixa de desenvolvimento. As entradas específicas fornecidas para uma tarefa variam de acordo com a tarefa.

Exemplo:

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

Todas as tarefas dão suporte à timeout propriedade, que é opcional.

Exemplo:

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

Tarefas integradas

O PowerShell e o WinGet estão disponíveis como tarefas internas. Você pode invocá-los diretamente sem anexar um catálogo no nível do centro de desenvolvimento que define a implementação dessas tarefas.

Tarefa interna do WinGet

Essa tarefa interna aplica uma configuração do WinGet à caixa de desenvolvimento.

Parâmetros:

  • configurationFile:

    • Tipo: string
    • O caminho para o arquivo YAML de configuração do WinGet. O arquivo deve estar localizado no computador local.
    • Obrigatório: false

  • downloadUrl:

    • Tipo: string
    • Uma URL acessível publicamente em que o arquivo YAML de configuração é armazenado. O arquivo é baixado para o caminho especificado configurationFile .
    • Obrigatório: false

  • inlineConfigurationBase64:

    • Tipo: string
    • Uma cadeia de caracteres codificada em Base64 do arquivo YAML de configuração do WinGet. O arquivo é decodificado para o caminho que configurationFile especifica ou para um arquivo temporário, se não for especificado.
    • Obrigatório: false

  • package:

    • Tipo: string
    • O nome do pacote a ser instalado.
    • Se um arquivo YAML de configuração for fornecido em outros parâmetros, o nome do pacote não será necessário.
    • Obrigatório: false

  • version

    • Tipo: string
    • A versão do pacote a ser instalado.
    • Se um arquivo YAML de configuração for fornecido em outros parâmetros, não haverá necessidade da versão do pacote.
    • Obrigatório: false

Tarefa interna do PowerShell

Essa tarefa interna executa um comando do PowerShell.

Parâmetros:

  • command:
    • Tipo: string
    • O comando a ser executado.
    • Obrigatório: true

arquivos task.yaml

As tarefas de personalização são unidades reutilizáveis de código de instalação ou configuração de ambiente. Os desenvolvedores usam scripts do PowerShell para gravá-los e usar um task.yaml arquivo de metadados para descrevê-los. Os desenvolvedores usam essas tarefas para personalizar uma caixa de desenvolvimento fazendo referência a elas de um devbox.yaml arquivo.

Ao definir tarefas de personalização, você pode identificar as tarefas que estão disponíveis para seus desenvolvedores para uso em devbox.yaml arquivos. Você pode restringir ações de alto privilégio, como a capacidade de executar qualquer comando do PowerShell.

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

nome

Necessário: Esse identificador exclusivo é usado para fazer referência a uma tarefa de devbox.yaml. O nome deve ser exclusivo no contexto do catálogo em que a tarefa existe.

A nomenclatura deve corresponder às restrições de recursos existentes do Azure. O nome deve ter entre 3 e 63 caracteres. Ele deve começar com um caractere alfanumérico. O nome deve consistir apenas em caracteres alfanuméricos e "-", "." ou "_". O caractere "/" é reservado.

name: powershell

descrição

Opcional: Esse atributo descreve a tarefa.

description: This task executes a powershell command

entradas

Necessário: Esse atributo lista os parâmetros que essa tarefa usa como entrada de um devbox.yaml arquivo e usa enquanto executa o comando. Cada item pai representa o nome de um parâmetro e dá suporte a estas chaves:

  • type (obrigatório): o tipo de dados de entrada para esse parâmetro. Pode ser string ou int.
  • defaultValue (obrigatório): o valor padrão que este parâmetro usa.
  • required (obrigatório): a chave que especifica se esse parâmetro é opcional ou necessário.
  • description (obrigatório): uma descrição do que esse parâmetro representa.
inputs:
  command:
    type: string
    defaultValue: ""
    required: true
    description: The command to execute

comando

Necessário: Esse comando é usado para cumprir essa tarefa. A cadeia de caracteres de comando fornecida é executada no Windows PowerShell no computador local.

command: ".\runcommand.ps1

Variáveis de referência em comandos

Para fazer referência a parâmetros em um comando, especifique o nome da variável em chaves duplas, por exemplo, {{parameter_name}}. Os valores dessas variáveis são interpolados antes da execução do comando.

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

tempo limite

Opcional: Essa variável especifica a quantidade máxima de tempo (em minutos) para aguardar a conclusão da execução da tarefa antes do tempo limite da tarefa. O padrão é 30 minutos.

timeout: 30

autor

Opcional: Essa variável identifica o autor da tarefa para ajudar com auditorias e solução de problemas.

author: Contoso Corporation

documentationURL

Opcional: Essa variável vincula à documentação desta tarefa.

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

licenseURL

Opcional: Essa variável vincula à licença para esta tarefa.

licenseURL: "https://link.to/license"
  • Last updated on