Créer des artefacts personnalisés pour DevTest Labs

  • Article

Cet article explique comment créer des fichiers d’artefacts personnalisés pour des machines virtuelles Azure DevTest Labs. Les artefacts DevTest Labs spécifient les actions à entreprendre pour approvisionner une machine virtuelle. Un artefact se compose d’un fichier de définition d’artefact et d’autres fichiers de script que vous stockez dans un dossier d’un référentiel Git.

Fichiers de définition d’artefact

Les fichiers de définition d’artefact sont des expressions JSON qui spécifient ce que vous voulez installer sur une machine virtuelle. Les fichiers définissent le nom d’un artefact, une commande à exécuter et les paramètres disponibles pour la commande. Vous pouvez faire référence à d’autres fichiers de script par leur nom dans le fichier de définition d’artefact.

L’exemple suivant indique les sections qui composent la structure de base d’un fichier de définition d’artefact 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": ""
    }
  }
Nom de l'élément Description
$schema Emplacement du fichier de schéma JSON. Le fichier de schéma JSON peut vous aider à tester la validité du fichier de définition.
title Nom de l’artefact à afficher dans le laboratoire. Obligatoire.
description Description de l’artefact à afficher dans le laboratoire. Obligatoire.
iconUri URI de l’icône d’artefact à afficher dans le laboratoire.
targetOsType Système d’exploitation de la machine virtuelle sur laquelle installer l’artefact. Valeurs prises en charge : Windows, Linux. Obligatoire.
parameters Valeurs pour personnaliser l’artefact lors de l’installation sur la machine virtuelle.
runCommand Commande d’installation de l’artefact à exécuter sur la machine virtuelle. Obligatoire.

Paramètres d'artefact

Dans la section des paramètres du fichier de définition, spécifiez les valeurs qu’un utilisateur peut entrer lors de l’installation d’un artefact. Vous pouvez faire référence à ces valeurs dans la commande d'installation d'artefact.

Pour définir des paramètres, utilisez la structure suivante :

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }
Nom de l'élément Description
type Type de la valeur du paramètre. Obligatoire.
displayName Nom du paramètre à afficher à l’utilisateur du laboratoire. Obligatoire.
description Description du paramètre à afficher à l’utilisateur du laboratoire. Obligatoire.

Les types de valeurs de paramètres autorisés sont les suivants :

Type Description
string N’importe quelle chaîne JSON valide
int N’importe quel entier JSON valide
bool N’importe quelle valeur booléenne JSON valide
array N’importe quel tableau JSON valide

Secrets sous forme de chaînes sécurisées

Pour déclarer des secrets en tant que paramètres de chaînes sécurisées avec des caractères masqués dans l’interface utilisateur, utilisez la syntaxe suivante dans la section parameters du fichier 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
    },

La commande d’installation de l’artefact pour exécuter le script PowerShell accepte la chaîne sécurisée créée à l’aide de la commande 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’enregistrez pas de secrets dans la console, car le script capture la sortie pour le débogage utilisateur.

Expressions et fonctions d'artefact

Vous pouvez utiliser des expressions et des fonctions pour construire la commande d’installation d’artefact. Les expressions sont évaluées lors de l’installation de l’artefact. Les expressions peuvent apparaître n’importe où dans une valeur de chaîne JSON et retournent toujours une autre valeur JSON. Placez les expressions entre crochets, [ ]. Si vous avez besoin d’utiliser une chaîne littérale qui commence par un crochet, utilisez deux crochets [[.

Vous utilisez généralement les expressions avec des fonctions pour construire une valeur. Les appels de fonction suivent le format functionName(arg1, arg2, arg3).

Les fonctions courantes sont les suivantes :

Fonction Description
parameters(parameterName) Renvoie une valeur de paramètre à fournir lors de l’exécution de la commande de l’artefact.
concat(arg1, arg2, arg3, ...) combine plusieurs valeurs de chaîne. Cette fonction peut prendre plusieurs arguments.

L’exemple suivant utilise des expressions et des fonctions pour construire une valeur :

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

Création d'un artefact personnalisé

Pour créer un artefact personnalisé :

  • Installez un éditeur JSON pour utiliser des fichiers de définition d’artefact. Visual Studio Code est disponible pour Windows, Linux et macOS.

  • Commencez par un exemple de fichier de définition artifactfile.json.

    Le référentiel d’artefacts DevTest Labs public contient une bibliothèque complète d’artefacts que vous pouvez utiliser. Vous pouvez télécharger un fichier de définition d’artefact et le personnaliser pour créer vos propres artefacts.

    Cet article utilise le fichier de définition artifactfile.json et le script PowerShell artifact.ps1 accessibles à l’adresse https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

  • Utilisez IntelliSense pour voir les éléments valides et les options de valeur que vous pouvez utiliser pour construire un fichier de définition d’artefact. Par exemple, lorsque vous modifiez l’élément targetOsType, IntelliSense vous indique les options Windows ou Linux.

  • Stockez vos artefacts dans des référentiels d’artefacts Git publics ou privés.

    • Stockez chaque fichier de définition d’artefact artifactfile.json dans un répertoire distinct portant le même nom que celui de l’artefact.
    • Stockez les scripts auxquels la commande d’installation fait référence dans le même répertoire que le fichier de définition d’artefact.

    La capture d’écran suivante montre un exemple de dossier d’artefact :

    Capture d’écran montrant un exemple de dossier d’artefacts.

  • Pour stocker vos artefacts personnalisés dans le référentiel d’artefacts DevTest Labs public, ouvrez une demande de tirage (pull request) sur le référentiel.

  • Pour ajouter votre référentiel d’artefacts privé à un laboratoire, consultez Ajouter un référentiel d’artefacts à votre laboratoire dans DevTest Labs.

Étapes suivantes