Create custom artifacts for DevTest Labs

This article describes how to create custom artifact files for Azure DevTest Labs virtual machines (VMs). DevTest Labs artifacts specify actions to take to provision a VM. An artifact consists of an artifact definition file and other script files that you store in a folder in a Git repository.

• For information about adding your artifact repositories to labs, see Add an artifact repository to your lab.
• For information about adding the artifacts you create to VMs, see Add artifacts to DevTest Labs VMs.
• For information about specifying mandatory artifacts to be added to all lab VMs, see Specify mandatory artifacts for DevTest Labs VMs.

Artifact definition files

Artifact definition files are JSON expressions that specify what you want to install on a VM. The files define the name of an artifact, a command to run, and available parameters for the command. You can refer to other script files by name in the artifact definition file.

The following example shows the sections that make up the basic structure of an artifactfile.json artifact definition file:

  {
    "$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": ""
    }
  }

Artifact parameters

In the parameters section of the definition file, specify the values a user can input when installing an artifact. You can refer to these values in the artifact install command.

To define parameters, use the following structure:

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }

The allowed parameter value types are:

Secrets as secure strings

To declare secrets as secure string parameters with masked characters in the UI, use the following syntax in the parameters section of the artifactfile.json file:

    "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
    },

The artifact install command to run the PowerShell script takes the secure string created by using the ConvertTo-SecureString command.

  "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'), '\"')]"
  }

Don't log secrets to the console, because the script captures output for user debugging.

Artifact expressions and functions

You can use expressions and functions to construct the artifact install command. Expressions evaluate when the artifact installs. Expressions can appear anywhere in a JSON string value, and always return another JSON value. Enclose expressions with brackets, [ ]. If you need to use a literal string that starts with a bracket, use two brackets [[.

You usually use expressions with functions to construct a value. Function calls are formatted as functionName(arg1, arg2, arg3).

Common functions include:

The following example uses expressions and functions to construct a value:

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

Create a custom artifact

To create a custom artifact:

• Install a JSON editor to work with artifact definition files. Visual Studio Code is available for Windows, Linux, and macOS.

• Start with a sample artifactfile.json definition file.

  The public DevTest Labs artifact repository has a rich library of artifacts you can use. You can download an artifact definition file and customize it to create your own artifacts.

  This article uses the artifactfile.json definition file and artifact.ps1 PowerShell script at https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes.

• Use IntelliSense to see valid elements and value options that you can use to construct an artifact definition file. For example, when you edit the targetOsType element, IntelliSense shows you Windows or Linux options.

• Store your artifacts in public or private Git artifact repositories.

  • Store each artifactfile.json artifact definition file in a separate directory named the same as the artifact name.
  • Store the scripts that the install command references in the same directory as the artifact definition file.

  The following screenshot shows an example artifact folder:

  

• To store your custom artifacts in the public DevTest Labs artifact repository, open a pull request against the repo.

• To add your private artifact repository to a lab, see Add an artifact repository to your lab in DevTest Labs.

Next steps

• Add artifacts to DevTest Labs VMs
• Diagnose artifact failures in the lab
• Troubleshoot issues when applying artifacts