Escrever 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 Visual Studio Code (VS Code) e o Dev Home.
Há duas maneiras de usar um arquivo de personalização no Microsoft Dev Box. As personalizações de equipe são aplicadas automaticamente quando os desenvolvedores as configuram em um pool. 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 suas caixas de desenvolvimento e testar essas personalizações diretamente no VS Code.
Importante
O recurso de personalizações da equipe da Caixa de Desenvolvimento está atualmente em visualização. Para obter mais informações sobre o status da visualização, consulte os Termos de Uso Suplementares para Visualizações do Microsoft Azure. O documento define termos legais que se aplicam a recursos do Azure que estão em versão beta, em visualização ou ainda não lançados em 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, pool de caixa de desenvolvimento e projeto de caixa de desenvolvimento para que você possa criar uma caixa de desenvolvimento.
- Seja membro do grupo de segurança Usuários da Caixa de Desenvolvimento de 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 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 no nível do projeto para um centro de desenvolvimento. | Engenheiro de plataforma com acesso de gravação na assinatura. |
| Habilite as configurações de sincronização de catálogo para um projeto. | Engenheiro de plataforma com acesso de gravação na assinatura. |
| Anexe um catálogo a um projeto. | Permissões de Administrador ou Colaborador do Projeto no projeto. |
| Crie 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 Dev Box. |
| 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 da Caixa de Desenvolvimento 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 é então disponibilizado para os desenvolvedores que criam caixas de desenvolvimento.
O exemplo a seguir usa uma winget tarefa para instalar o VS Code e uma git-clone tarefa 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
- Contêm 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 da equipe
- Contêm tarefas que são aplicadas quando um desenvolvedor cria uma caixa de desenvolvimento.
- São compartilhados entre uma equipe ou projeto.
- Inclua um campo que especifique a imagem base.
- São denominados 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 a partir de um pool configurado.
Importante
As definições de imagem podem usar apenas imagens do mercado Dev Box como imagens base. Para obter uma lista de imagens que seu 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 Microsoft Dev Box 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, em seguida, instale a extensão Dev Box.
Baixe um arquivo de personalização YAML de exemplo do repositório de amostras e abra-o no VS Code.
Descubra as tarefas disponíveis no catálogo usando a paleta de comandos. Selecione View>Command Palette>Dev Box: Liste tarefas disponíveis para esta caixa de desenvolvimento.
Teste a personalização no VS Code usando a paleta de comandos. Selecione View>Command Palette>Dev Box: Apply Customizations Tasks.
O arquivo de personalização é executado imediatamente e aplica as tarefas especificadas à sua caixa de desenvolvimento de teste. Inspecione as alterações e verifique o terminal VS Code para quaisquer erros ou avisos gerados durante a execução da tarefa.
Quando o arquivo de personalização for executado com êxito, carregue-o para o catálogo.
Clone um repositório privado usando um arquivo de personalização
Você pode usar segredos do seu cofre de chaves do Azure em suas personalizações do YAML para clonar repositórios privados ou com qualquer tarefa personalizada criada que exija um token de acesso. Em um arquivo de personalização de equipe, você pode usar um token de acesso pessoal (PAT) 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 a sua PAT como um segredo do cofre de chaves e utilize-a quando invocar a git-clone tarefa na sua personalização.
Para configurar os segredos do cofre de chaves para uso em suas personalizações do YAML:
- Certifique-se de que a identidade gerenciada do seu projeto do centro de desenvolvimento tenha a função Key Vault Reader e a função Key Vault Secrets User no seu cofre de chaves.
- Conceda a função Usuário de Segredos do Cofre de Chaves para o segredo do cofre de chaves 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 recebeu a função deve incluir a identidade gerenciada para o 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 obter mais informações, consulte:
- Configurar uma identidade gerenciada para um centro de desenvolvimento
- Conceder à identidade gerenciada acesso ao segredo do cofre de chaves
Você pode fazer referência ao segredo em sua personalização do YAML no seguinte formato, que usa a git-clone tarefa 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 quiser clonar um repositório privado do Azure Repos de um arquivo de personalização individual, não é necessário configurar um segredo no Cofre da Chave do Azure. Em vez disso, você pode usar {{ado}} ou {{ado://your-ado-organization-name}} como um parâmetro. Este 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 git-clone tarefa no catálogo de início rápido usa o token de acesso para clonar seu repositório. Eis 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 de acesso ao seu cofre de chaves. Os centros de desenvolvimento não suportam etiquetas de serviço, por isso, se o cofre de chaves for mantido privado, tem de permitir que os serviços fidedignos da Microsoft ignorem a firewall.
Para saber como permitir que serviços confiáveis da Microsoft ignorem o firewall, consulte Configurar configurações de rede do Cofre da Chave do Azure.
Personalize sua caixa de desenvolvimento usando arquivos de configuração do WinGet existentes
A configuração do WinGet adota uma abordagem de configuração como código para definir os conjuntos exclusivos de software e definições de configuração necessários para colocar seu ambiente Windows em um estado pronto para codificar. 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 da caixa de desenvolvimento que chama um arquivo existente de Configuração de Estado Desejado (DSC) do WinGet:
tasks:
- name: winget
parameters:
configure: "projectConfiguration.dsc.yaml"
Para saber mais, consulte Configuração do WinGet.
Compartilhar um arquivo de personalização de um repositório de código
Disponibilize seu arquivo de personalização para pools de caixas de desenvolvimento nomeando-o imagedefinition.yaml e carregando-o no repositório que hospeda seu catálogo. Ao criar um pool de caixas de desenvolvimento, você pode selecionar o arquivo de personalização do catálogo para aplicar às caixas de desenvolvimento no pool.