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

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

项目
07/15/2024

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

有关将项目存储库添加到实验室的信息，请参阅将项目存储库添加到实验室。
有关将创建的项目添加到 VM 的信息，请参阅将项目添加到开发测试实验室 VM。
有关指定要添加到所有实验室 VM 的必需项目的信息，请参阅为开发测试实验室 VM 指定必需的项目。

项目定义文件

项目定义文件是用于指定要在 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 项目定义文件存储在一个名称与项目名称相同的单独目录中。
- 在项目定义文件所在的同一目录中存储“安装”命令所引用的脚本。
以下屏幕截图显示了一个示例项目文件夹：
若要将自定义项目存储在公共开发测试实验室项目存储库中，请针对存储库创建拉取请求。
若要将专用项目存储库添加到实验室，请参阅在开发测试实验室中将项目存储库添加到实验室。

通过