Criar artefatos personalizados para Laboratórios do DevTest Labs

  • Artigo

Este artigo descreve como criar arquivos de artefato personalizados para VMs (máquinas virtuais) do Azure DevTest Labs. Os artefatos do DevTest Labs especificam as ações a serem tomadas para provisionar uma VM. Um artefato é composto por um arquivo de definição de artefato e outros arquivos de script que são armazenados em uma pasta em um repositório Git.

Arquivos de definição de artefato

Arquivos de definição de artefato são expressões JSON que especificam o que você deseja instalar em uma VM. Os arquivos definem o nome de um artefato, um comando a ser executado e parâmetros disponíveis para o comando. Você pode consultar outros arquivos de script por nome dentro do arquivo de definição de artefato.

O seguinte exemplo mostra as seções que compõem a estrutura básica de um arquivo de definição de artefato artifactfile.json:

  {
    "$schema": "https://raw.githubusercontent.com/Azure/azure-devtestlab/master/schemas/2016-11-28/dtlArtifacts.json",
    "title": "",
    "description": "",
    "iconUri": "",
    "targetOsType": "",
    "parameters": {
      "<parameterName>": {
        "type": "",
        "displayName": "",
        "description": ""
      }
    },
    "runCommand": {
      "commandToExecute": ""
    }
  }
Nome do elemento Descrição
$schema Local do arquivo de esquema JSON. O arquivo de esquema JSON pode lhe ajudar a testar a validade do arquivo de definição.
title Nome do artefato a ser exibido no laboratório. Necessário.
description Descrição do artefato a ser exibido no laboratório. Necessário.
iconUri URI do artefato a ser exibido no laboratório.
targetOsType Sistema operacional da VM na qual instalar o artefato. Valores com suporte: Windows e Linux. Necessário.
parameters Valores para personalizar o artefato ao instalá-lo na VM.
runCommand O comando de instalação do artefato a ser executado na VM. Necessário.

Parâmetros do artefato

Na seção de parâmetros do arquivo de definição, especifique os valores que um usuário pode inserir ao instalar um artefato. Você pode consultar esses valores no comando de instalação do artefato.

Para definir parâmetros, use a seguinte estrutura:

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }
Nome do elemento Descrição
type Tipo do valor do parâmetro. Necessário.
displayName Nome do parâmetro a ser exibido para o usuário do laboratório. Necessário.
description Descrição do parâmetro a ser exibido para o usuário do laboratório. Necessário.

Os tipos de valor de parâmetro permitidos são:

Tipo Descrição
string Qualquer cadeia de caracteres JSON válida
int Qualquer inteiro JSON válido
bool Qualquer booliano JSON válido
array Qualquer matriz JSON válida

Segredos como cadeias de caracteres seguras

Para declarar segredos como parâmetros de cadeia de caracteres seguros com caracteres mascarados na interface do usuário, use a seguinte sintaxe na seção parameters do arquivo artifactfile.json:


    "securestringParam": {
      "type": "securestring",
      "displayName": "Secure String Parameter",
      "description": "Any text string is allowed, including spaces, and will be presented in UI as masked characters.",
      "allowEmpty": false
    },

O comando de instalação do artefato para executar o script do PowerShell usa a cadeia de caracteres segura criada com o comando ConvertTo-SecureString.

  "runCommand": {
    "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./artifact.ps1 -StringParam ''', parameters('stringParam'), ''' -SecureStringParam (ConvertTo-SecureString ''', parameters('securestringParam'), ''' -AsPlainText -Force) -IntParam ', parameters('intParam'), ' -BoolParam:$', parameters('boolParam'), ' -FileContentsParam ''', parameters('fileContentsParam'), ''' -ExtraLogLines ', parameters('extraLogLines'), ' -ForceFail:$', parameters('forceFail'), '\"')]"
  }

Não registre segredos no console, pois o script captura a saída para depuração do usuário.

Expressões e funções de artefatos

Você pode usar expressões e funções para construir o comando de instalação do artefato. As expressões são avaliadas quando o artefato é instalado. As expressões podem aparecer em qualquer lugar em um valor de cadeia de caracteres JSON e sempre retornam outro valor JSON. Coloque expressões entre colchetes, [ e ]. Se precisar usar uma cadeia de caracteres literal que começa com um colchete, use dois colchetes ([[).

Normalmente, você usa expressões com funções para construir um valor. Chamadas de função são formatadas como functionName(arg1, arg2, arg3).

As funções comuns incluem:

Função Descrição
parameters(parameterName) Retorna um valor de parâmetro a ser fornecido quando o comando de artefato é executado.
concat(arg1, arg2, arg3, ...) Combina vários valores de cadeia de caracteres. Essa função pode conter vários argumentos.

O seguinte exemplo usa expressões e funções para construir um valor:

  runCommand": {
      "commandToExecute": "[concat('powershell.exe -ExecutionPolicy bypass \"& ./startChocolatey.ps1'
  , ' -RawPackagesList ', parameters('packages')
  , ' -Username ', parameters('installUsername')
  , ' -Password ', parameters('installPassword'))]"
  }

Criar um artefato personalizado

Para criar um artefato personalizado:

  • Instale um editor de JSON para trabalhar com arquivos de definição de artefato. O Visual Studio Code está disponível para Windows, Linux e macOS.

  • Comece com um exemplo de arquivo de definição artifactfile.json.

    O repositório público de artefatos do DevTest Labs tem uma biblioteca de artefatos que você pode usar. Você pode baixar um arquivo de definição de artefato e personalizá-lo para criar seus artefatos.

    Este artigo usa o arquivo de definição artifactfile.json e o script do PowerShell artifact.ps1 em https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

  • Use o IntelliSense para ver os elementos válidos e as opções de valor que você pode usar para construir um arquivo de definição de artefato. Por exemplo, quando você edita o elemento targetOsType, o IntelliSense mostra a você as duas opções, Windows ou Linux.

  • Armazene seus artefatos em repositórios públicos ou privados de artefato Git.

    • Armazene cada arquivo de definição de artefato artifactfile.json em um diretório separado chamado igual ao nome do artefato.
    • Armazene os scripts referenciados pelo comando de instalação no mesmo diretório que o arquivo de definição de artefato.

    A seguinte captura de tela mostra um exemplo de pasta de artefato:

    Captura de tela que mostra um exemplo de pasta de artefato.

  • Para armazenar seus artefatos personalizados no repositório público de artefatos do DevTest Labs, abra uma solicitação de pull no repositório.

  • Para adicionar seu repositório privado de artefatos a um laboratório, confira Adicionar um repositório de artefatos ao laboratório no DevTest Labs.

Próximas etapas