Gravar um arquivo de personalização para uma caixa de desenvolvimento
Neste artigo, você aprenderá a criar e testar um arquivo de personalização para sua caixa de desenvolvimento usando o VS Code (Visual Studio Code) e o Dev Home.
Há duas maneiras de usar um arquivo de personalização no Computador de Desenvolvimento da Microsoft. As personalizações de equipe são aplicadas automaticamente quando os desenvolvedores as configuram em um pool. As Personalizações individuais são aplicadas quando um usuário cria uma caixa de desenvolvimento.
Este artigo ajuda você a definir novas tarefas em seu arquivo de personalização, aplicá-las às caixas de desenvolvimento e testar essas personalizações diretamente no VS Code.
Importante
O recurso de personalização da equipe do Computador de Desenvolvimento da Microsoft está atualmente em versão prévia. Para obter mais informações sobre o status de visualização, consulte os Termos de Uso Complementares para Visualizações do Microsoft Azure. O documento define os termos legais que se aplicam aos recursos do Azure que estão em beta, em versão prévia ou ainda não lançados para disponibilidade geral.
Pré-requisitos
Para concluir as etapas neste artigo, você deve:
- Tenha um centro de desenvolvimento configurado com uma definição de caixa de desenvolvimento, um pool de caixas de desenvolvimento e um projeto de caixa de desenvolvimento para que você possa criar uma caixa de desenvolvimento.
- Seja membro do grupo de segurança de Usuários do Computador de Desenvolvimento por pelo menos um projeto.
- Tenha um catálogo anexado ao centro de desenvolvimento com tarefas que você pode usar em seu arquivo de personalização. Se você não tiver um catálogo, consulte Adicionar e configurar um catálogo do GitHub ou do Azure Repos.
Permissões necessárias para configurar personalizações
Para executar as ações necessárias para criar e aplicar personalizações a uma caixa de desenvolvimento, você precisa das seguintes permissões:
| Ação | Permissão/Função |
|---|---|
| Habilite catálogos em nível de projeto para um centro de desenvolvimento. | Engenheiro de plataforma com acesso de gravação na assinatura. |
| Habilitar configurações de sincronização de catálogo para um projeto. | Engenheiro de plataforma com acesso de gravação na assinatura. |
| Anexar um catálogo a um projeto. | Permissões de Administrador do Projeto ou Colaborador no projeto. |
| Criar um arquivo de personalização. | Nenhum especificado. Qualquer pessoa pode criar um arquivo de personalização. |
| Use o portal do desenvolvedor para carregar e aplicar um arquivo YAML durante a criação da caixa de desenvolvimento. | Usuário do Computador de Desenvolvimento. |
| Adicionar tarefas a um catálogo. | Permissão para adicionar ao repositório que hospeda o catálogo. |
O que é um arquivo de personalização?
As personalizações do Dev Box usam um arquivo formatado em YAML para especificar uma lista de tarefas a serem aplicadas quando um desenvolvedor cria uma caixa de desenvolvimento. Essas tarefas podem ser tão simples quanto instalar um pacote ou tão sofisticadas quanto executar um conjunto complexo de scripts para configurar uma base de código. As tarefas identificam o catálogo e fornecem parâmetros como o nome do software a ser instalado. O arquivo de personalização é disponibilizado para os desenvolvedores que criam caixas de desenvolvimento.
O exemplo a seguir usa uma tarefa winget para instalar o VS Code e uma tarefa git-clone para clonar um repositório:
# From https://github.com/microsoft/devcenter-examples
$schema: 1.0
tasks:
- name: winget
parameters:
package: Microsoft.VisualStudioCode
runAsUser: true
- name: git-clone
description: Clone this repository into C:\Workspaces
parameters:
repositoryUrl: https://github.com/OrchardCMS/OrchardCore.git
directory: C:\Workspaces
Há duas maneiras de usar um arquivo de personalização: personalizações individuais se aplicam a uma única caixa de desenvolvimento e personalizações de equipe se aplicam a uma equipe inteira.
Arquivos de personalização individuais
- Contenha tarefas que são aplicadas quando um desenvolvedor cria uma caixa de desenvolvimento.
- São carregados pelo desenvolvedor durante a criação de uma caixa de desenvolvimento.
Arquivos de personalização de equipe
- Contenha tarefas que são aplicadas quando um desenvolvedor cria uma caixa de desenvolvimento.
- São compartilhados em uma equipe ou projeto.
- Incluem um campo que especifica a imagem base.
- São nomeados imagedefinition.yaml.
- São carregados no repositório que hospeda um catálogo.
- São usados automaticamente quando um desenvolvedor cria uma caixa de desenvolvimento de um pool configurado.
Importante
As definições de imagem podem usar apenas imagens do Marketplace do Dev Box como imagens base. Para obter uma lista de imagens que o centro de desenvolvimento pode acessar, use este comando da CLI do Azure:
az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"
Criar um arquivo de personalização
Você pode criar e gerenciar arquivos de personalização usando o VS Code. Você pode usar a extensão Computador de Desenvolvimento da Microsoft no VS Code para descobrir as tarefas no catálogo anexado e testar o arquivo de personalização.
Crie uma caixa de desenvolvimento (ou use uma caixa de desenvolvimento existente) para teste.
Na caixa de desenvolvimento de teste, instale o VS Code e instale a extensão Dev Box.
Baixe um arquivo de personalização YAML de exemplo do repositório de exemplos e abra-o no VS Code.
Descubra as tarefas disponíveis no catálogo usando a paleta de comandos. Caixa de desenvolvimento Selecionar Exibição>Paleta de Comandos>: Listar tarefas disponíveis para esta caixa de desenvolvimento.
Teste a personalização no VS Code usando a paleta de comandos. Selecionar Exibição>Paleta de Comandos>: Caixa de desenvolvimento: aplicar tarefas de personalizações.
O arquivo de personalização é executado imediatamente e aplica as tarefas especificadas à caixa de desenvolvimento de teste. Inspecione as alterações e verifique se há erros ou avisos gerados no terminal do VS Code durante a execução da tarefa.
Quando o arquivo de personalização for executado com sucesso, carregue-o no catálogo.
Clonar um repositório privado usando um arquivo de personalização
Você pode usar segredos do cofre de chaves do Azure em suas personalizações YAML para clonar repositórios privados ou com qualquer tarefa personalizada que você criar que exija um token de acesso. Em um arquivo de personalização de equipe, você pode usar um PAT (token de acesso pessoal) armazenado em um cofre de chaves para acessar um repositório privado.
Usar segredos do cofre de chaves em arquivos de personalização de equipe
Para clonar um repositório privado, armazene seu PAT como um segredo do cofre de chaves e use-o quando estiver invocando a tarefa git-clone em sua personalização.
Para configurar seus segredos do cofre de chaves para uso em suas personalizações YAML:
- Verifique se a identidade gerenciada do projeto do centro de desenvolvimento tem a função Leitor do Key Vault e a função de Usuário de Segredos do Key Vault no cofre de chaves.
- Conceda a função de usuário dos segredos do Key Vault para o segredo do Key Vault a cada usuário ou grupo de usuários que deve ser capaz de consumir o segredo durante a personalização de uma caixa de desenvolvimento. O usuário ou grupo que recebe a função deve incluir a identidade gerenciada do centro de desenvolvimento, sua própria conta de usuário e qualquer usuário ou grupo que precise do segredo durante a personalização de uma caixa de desenvolvimento.
Para saber mais, veja:
- Configurar uma identidade gerenciada para um centro de desenvolvimento
- Conceder acesso à identidade gerenciada ao segredo do cofre de chaves
Você pode referenciar o segredo em sua personalização YAML no seguinte formato, que usa a tarefa git-clone como exemplo:
$schema: "1.0"
tasks:
name: git-clone
description: Clone this repository into C:\Workspaces
parameters:
repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
directory: C:\Workspaces
pat: '{{KEY_VAULT_SECRET_URI}}'
Usar segredos do cofre de chaves em arquivos de personalização individuais
Se você quiser clonar um repositório privado do Azure Repos de um arquivo de personalização individual, não será necessário configurar um segredo no Azure Key Vault. Em vez disso, você pode usar {{ado}} ou {{ado://your-ado-organization-name}} como um parâmetro. Esse parâmetro busca um token de acesso em seu nome quando você está criando uma caixa de desenvolvimento. O token de acesso tem permissão somente leitura para o repositório.
A tarefa git-clone no catálogo de início rápido usa o token de acesso para clonar seu repositório. Veja um exemplo:
tasks:
name: git-clone
description: Clone this repository into C:\Workspaces
parameters:
repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
directory: C:\Workspaces
pat: '{{ado://YOUR_ADO_ORG}}'
Seu centro de desenvolvimento precisa ter acesso ao cofre de chaves. Os centros de desenvolvimento não dão suporte a marcas de serviço, portanto, se o cofre de chaves for mantido privado, você deverá permitir que serviços confiáveis da Microsoft ignorem o firewall.
Para saber como permitir que serviços Microsoft confiáveis ignorem o firewall, consulte Configurar as definições de rede do Azure Key Vault.
Personalizar seu computador de desenvolvimento usando arquivos de Configuração do WinGet existentes
A configuração do WinGet usa uma abordagem de configuração como código para definir os conjuntos exclusivos de configurações e software necessários para colocar seu ambiente do Windows em um estado pronto para código. Você também pode usar esses arquivos de configuração para configurar uma caixa de desenvolvimento usando uma tarefa WinGet incluída no catálogo de início rápido fornecido pela Microsoft.
O exemplo a seguir mostra um arquivo de personalização de caixa de desenvolvimento que chama um arquivo DSC (Desired State Configuration) do WinGet existente:
tasks:
- name: winget
parameters:
configure: "projectConfiguration.dsc.yaml"
Para saber mais, confira a configuração do WinGet.
Compartilhar um arquivo de personalização por meio de um repositório de código
Disponibilize seu arquivo de personalização para pools de caixa de desenvolvimento nomeando-o imagedefinition.yaml e carregando-o no repositório que hospeda seu catálogo. Ao criar um pool de computador de desenvolvimento, você pode selecionar o arquivo de personalização no catálogo para aplicar aos computadores de desenvolvimento no pool.