你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

为开发测试实验室创建自定义项目

  • 项目

本文介绍如何为 Azure 开发测试实验室虚拟机 (VM) 创建自定义项目文件。 开发测试实验室项目指定在预配 VM 时要执行的操作。 项目由项目定义文件和存储在 Git 存储库的文件夹中的其他脚本文件组成。

项目定义文件

项目定义文件是用于指定要在 VM 上安装的内容的 JSON 表达式。 这些文件定义项目名称、要运行的命令，以及命令可用的参数。 可以在项目定义文件中按名称引用其他脚本文件。

以下示例显示了组成 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": ""
    }
  }
元素名称 描述
$schema JSON 架构文件的位置。 JSON 架构文件可帮助测试定义文件的有效性。
title 要显示在实验室中的项目的名称。 必填。
description 要显示在实验室中的项目的说明。 必填。
iconUri 要显示在实验室中的项目图标的 URI。
targetOsType 项目要安装到的 VM 的操作系统。 支持的值：Windows、Linux。 必填。
parameters 用于在 VM 上安装时自定义项目的值。
runCommand 要在 VM 上执行的项目安装命令。 必填。

项目参数

在定义文件的参数部分中，指定用户在安装项目时可以输入的值。 可以在项目安装命令中引用这些值。

若要定义参数，请使用以下结构：

  "parameters": {
    "<parameterName>": {
      "type": "<type-of-parameter-value>",
      "displayName": "<display-name-of-parameter>",
      "description": "<description-of-parameter>"
    }
  }
元素名称 描述
type 参数值的类型。 必填。
displayName 要向实验室用户显示的参数的名称。 必填。
description 要向实验室用户显示的参数的说明。 必填。

允许的参数值类型为：

类型 描述
string 任何有效的 JSON 字符串
int 任何有效的 JSON 整数
bool 任何有效的 JSON 布尔值
array 任何有效的 JSON 数组

安全字符串形式的机密

若要在 UI 中将机密声明为带有掩码字符的安全字符串参数，请在 artifactfile.json 文件的 parameters 部分中使用以下语法：


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

用于运行 PowerShell 脚本的项目安装命令采用通过使用 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'), '\"')]"
  }

不要将机密记录到控制台，因为脚本会捕获输出以供用户进行调试。

项目表达式和函数

可以使用表达式和函数构建项目安装命令。 表达式在安装项目时进行计算。 表达式可以出现在 JSON 字符串值中的任何位置，并始终返回另一个 JSON 值。 用方括号 [ ] 将表达式括起。 如果需要使用以方括号开头的文本字符串，请使用两个方括号 [[。

通常将表达式与函数配合使用来构造值。 函数调用的格式为 functionName(arg1, arg2, arg3)。

常见函数包括：

函数 描述
parameters(parameterName) 返回一个参数值，以提供项目命令的运行时间。
concat(arg1, arg2, arg3, ...) 合并多个字符串值。 此函数可以接受多个参数。

以下示例使用表达式和函数来构造值：

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

创建自定义项目

若要创建自定义项目，请执行以下操作：

  • 安装一个 JSON 编辑器来处理项目定义文件。 Visual Studio Code 适用于 Windows、Linux 和 macOS。

  • 从示例 artifactfile.json 定义文件入手。

    公共开发测试实验室项目存储库包含你可使用的丰富的项目库。 可以下载项目定义文件并对其进行自定义以创建自己的项目。

    本文使用 https://github.com/Azure/azure-devtestlab/tree/master/Artifacts/windows-test-paramtypes 上的 artifactfile.json 定义文件和和 artifact.ps1 PowerShell 脚本。

  • 使用 IntelliSense 查看可用于构造项目定义文件的有效元素和值选项。 例如，当你编辑 targetOsType 元素时，IntelliSense 会显示 Windows 或 Linux 选项。

  • 将项目存储在公共或专用 Git 项目存储库中。

    • 将每个 artifactfile.json 项目定义文件存储在一个名称与项目名称相同的单独目录中。
    • 在项目定义文件所在的同一目录中存储“安装”命令所引用的脚本。

    以下屏幕截图显示了一个示例项目文件夹：

    显示项目文件夹示例的屏幕截图。

  • 若要将自定义项目存储在公共开发测试实验室项目存储库中，请针对存储库创建拉取请求。

  • 若要将专用项目存储库添加到实验室，请参阅在开发测试实验室中将项目存储库添加到实验室。

后续步骤