如何在 Configuration Manager 中使用任务序列变量

项目
04/04/2023

适用于: Configuration Manager(current branch)

Configuration Manager 的 OS 部署功能中的任务序列引擎使用许多变量来控制其行为。使用这些变量可以：

设置步骤的条件
更改特定步骤的行为
在脚本中使用以执行更复杂的操作

有关所有可用任务序列变量的参考，请参阅任务序列变量。

变量的类型

有几种类型的变量：

内置
操作
自定义
只读
数组

内置变量

内置变量提供有关运行任务序列的环境的信息。其值在整个任务序列中可用。通常，任务序列引擎在运行任何步骤之前初始化内置变量。

例如， _SMSTSLogPath 是一个环境变量，指定 Configuration Manager 组件写入日志文件的路径。任何任务序列步骤都可以访问此环境变量。

任务序列在每个步骤之前都会评估一些变量。例如， _SMSTSCurrentActionName 列出当前步骤的名称。

操作变量

任务序列操作变量指定单个任务序列步骤使用的配置设置。默认情况下，该步骤在运行前初始化其设置。这些设置仅在关联的任务序列步骤运行时可用。任务序列在运行步骤之前将操作变量值添加到环境。然后，它会在步骤运行后从环境中删除值。

例如，将 “运行命令行” 步骤添加到任务序列。此步骤包括 Start In 属性。任务序列将此属性的默认值存储为 WorkingDirectory 变量。任务序列在运行 “运行命令行” 步骤之前初始化此值。此步骤正在运行时，从 WorkingDirectory 值访问 Start In 属性值。步骤完成后，任务序列将从环境中删除变量的值 WorkingDirectory 。如果任务序列包含另一个 “运行命令行” 步骤，则会初始化一个新 WorkingDirectory 变量。此时，任务序列将变量设置为当前步骤的起始值。有关详细信息，请参阅 WorkingDirectory。

运行步骤时，存在操作变量的 默认值 。如果设置新值，则它可用于任务序列中的多个步骤。如果替代默认值，新值将保留在环境中。此新值替代任务序列中其他步骤的默认值。例如，添加 “设置任务序列变量 ”步骤作为任务序列的第一步。此步骤将 WorkingDirectory 变量设置为 C:\。任务序列中的任何 “运行命令行” 步骤都使用新的起始目录值。

某些任务序列步骤将某些操作变量标记为输出。任务序列后面的步骤将读取这些输出变量。

注意

并非所有任务序列步骤都有操作变量。例如，尽管存在与 Enable BitLocker 操作关联的变量，但没有与 Disable BitLocker 操作关联的变量。

自定义变量

这些变量是 Configuration Manager 未创建的任何变量。初始化自己的变量以在命令行或脚本中用作条件。

为新的任务序列变量指定名称时，请遵循以下准则：

任务序列变量名称可以包括字母、数字、下划线字符 () _ ，以及连字符 (-) 。
任务序列变量名称的最小长度为 1 个字符，最大长度为 256 个字符。
用户定义的变量必须以字母 (A-Z 或 a-z) 开头。
用户定义的变量名称不能以下划线字符开头。只有只读任务序列变量前面有下划线字符。
任务序列变量名称不区分大小写。例如， OSDVAR 和 osdvar 是相同的任务序列变量。
任务序列变量名称不能以空格开头或结尾。它们也不能有嵌入的空间。任务序列忽略变量名称开头或末尾的任何空格。

可以创建的任务序列变量数没有设置限制。但是，变量数受任务序列环境的大小限制。任务序列环境的总大小限制为 8 KB。有关详细信息，请参阅减小任务序列策略的大小。

只读变量

无法更改某些变量的值，这些变量是只读的。名称通常以下划线字符开头， _ () 。任务序列将其用于其操作。只读变量在任务序列环境中可见。

这些变量在脚本或命令行中很有用。例如，运行命令行并将输出管道到包含其他日志文件的日志文件 _SMSTSLogPath 。

注意

只读任务序列变量可以通过任务序列中的步骤读取，但无法设置它们。例如，使用只读变量作为运行命令行步骤的命令行的一部分。不能使用“ 设置任务序列 变量”步骤设置只读变量。

数组变量

任务序列将某些变量存储为数组。数组中的每个元素都表示单个对象的设置。当设备有多个要配置的对象时，请使用这些变量。以下任务序列步骤使用数组变量：

如何设置变量

对于自定义变量或非只读变量，有几种方法可以初始化和设置变量的值：

设置任务序列变量步骤
设置动态变量步骤
运行 PowerShell 脚本步骤
集合和设备变量
TSEnvironment COM 对象
预启动命令
任务序列向导
任务序列媒体向导

使用与创建变量相同的方法从环境中删除变量。若要删除变量，请将变量值设置为空字符串。

可以组合方法，将任务序列变量设置为同一序列的不同值。例如，使用任务序列编辑器设置默认值，然后使用脚本设置自定义值。

如果通过不同的方法设置相同的变量，任务序列引擎将使用以下顺序：

它首先评估集合变量。
特定于设备的变量替代集合上的同一变量集。
任务序列期间由任何方法设置的变量优先于集合或设备变量。

任务序列变量值的一般限制

任务序列变量值不能超过 4,000 个字符。
无法更改只读任务序列变量。只读变量的名称以下划线字符开头， _ () 。
任务序列变量值可能区分大小写，具体取决于值的用法。在大多数情况下，任务序列变量值不区分大小写。包含密码的变量区分大小写。

设置任务序列变量

在任务序列中使用此步骤将单个变量设置为单个值。

有关详细信息，请参阅设置任务序列变量。

设置动态变量

在任务序列中使用此步骤可以设置一个或多个任务序列变量。在此步骤中定义规则以确定要使用的变量和值。

有关详细信息，请参阅设置动态变量。

运行 PowerShell 脚本

在任务序列中使用此步骤可以使用 PowerShell 脚本设置任务序列变量。

可以从包中指定脚本名称，或直接在步骤中输入 PowerShell 脚本。然后使用“ 输出到任务序列变量 ”的步骤属性将脚本输出保存到自定义任务序列变量。

有关此步骤的详细信息，请参阅运行 PowerShell 脚本。

注意

还可以使用 PowerShell 脚本通过 TSEnvironment 对象设置一个或多个变量。有关详细信息，请参阅如何在 Configuration Manager SDK 的正在运行的任务序列中使用变量。

使用运行 PowerShell 脚本步骤的示例方案

你的环境中的用户位于多个国家/地区，因此你需要查询 OS 语言，以将设置为多个特定于语言 的应用 OS 步骤的条件。

在应用 OS 步骤之前，将运行 PowerShell 脚本的实例添加到任务序列。
使用“ 输入 PowerShell 脚本 ”选项指定以下命令：
```
(Get-Culture).TwoLetterISOLanguageName
```
有关 cmdlet 的详细信息，请参阅 Get-Culture。有关双字母 ISO 语言名称的详细信息，请参阅 ISO 639-1 代码列表。
对于“ 输出到任务序列变量”选项，请指定 CurrentOSLanguage。
在“为英语语言映像 应用 OS ”步骤中，创建以下条件： Task Sequence Variable CurrentOSLanguage equals "en"

提示

有关如何在步骤上创建条件的详细信息，请参阅如何访问变量 - 步骤条件。
保存并部署任务序列。

当 运行 PowerShell 脚本 步骤在具有英语版本的 Windows 的设备上运行时，命令将返回值 en。然后，它将该值保存到自定义变量中。在同一设备上运行英语映像 的“应用 OS” 步骤时，条件的计算结果为 true。如果有多个适用于不同语言的 “应用 OS” 步骤实例，任务序列会动态运行与 OS 语言匹配的步骤。

集合和设备变量

可以为设备和集合定义自定义任务序列变量。为设备定义的变量称为按设备任务序列变量。为集合定义的变量称为按集合任务序列变量。如果存在冲突，则每个设备变量优先于每个集合变量。此行为意味着分配给特定设备的任务序列变量自动具有比分配给包含设备的集合的变量更高的优先级。

例如，设备 XYZ 是集合 ABC 的成员。将 MyVariable 分配到值为 1 的集合 ABC。还将 MyVariable 分配给值为 2 的设备 XYZ。分配给 XYZ 的变量的优先级高于分配给集合 ABC 的变量。当具有此变量的任务序列在 XYZ 上运行时，MyVariable 的值为 2。

可以隐藏每个设备和每个集合的变量，以便它们在 Configuration Manager 控制台中不可见。在 Configuration Manager 控制台中使用“不显示此值”选项时，该变量的值不会显示在控制台中。任务序列日志文件 (smsts.log) 或任务序列调试器也不会显示变量值。该变量在运行时仍可由任务序列使用。如果不再希望隐藏这些变量，请先将其删除。然后，在不选择隐藏变量的选项的情况下重新定义变量。

警告

如果在 “运行命令行” 步骤的命令行中包含变量，任务序列日志文件将显示包含变量值的完整命令行。若要防止潜在的敏感数据出现在日志文件中，请将任务序列变量 OSDDoNotLogCommand 设置为 TRUE。

可以在主站点或管理中心站点上管理每个设备变量。 Configuration Manager 不支持为设备分配超过 1,000 个变量。

重要

将每个集合变量用于任务序列时，请考虑以下行为：

始终在整个层次结构中复制对集合所做的更改。对集合变量所做的任何更改不仅应用于当前网站的成员，也适用于整个层次结构中的集合的所有成员。
删除集合时，此操作还会删除为集合配置的任务序列变量。

为设备创建任务序列变量

在 Configuration Manager 控制台中，转到 “资产和符合性” 工作区，然后选择“ 设备” 节点。
选择目标设备，然后选择 “属性”。
在“ 属性 ”对话框中，切换到“ 变量 ”选项卡。
对于要创建的每个变量，请选择“ 新建 ”图标。 指定任务序列变量的名称和值。如果要隐藏变量，使其在 Configuration Manager 控制台中不可见，请选择选项 “不在 Configuration Manager 控制台中显示此值”。
将所有变量添加到设备属性后，选择“ 确定”。

为集合创建任务序列变量

在 Configuration Manager 控制台中，转到 “资产和符合性” 工作区，然后选择“ 设备集合” 节点。选择目标集合，然后选择“属性”。
在“ 属性 ”对话框中，切换到“ 集合变量 ”选项卡。
对于要创建的每个变量，请选择“ 新建 ”图标。 指定任务序列变量的名称和值。如果要隐藏变量，使其在 Configuration Manager 控制台中不可见，请选择选项 “不在 Configuration Manager 控制台中显示此值”。
（可选）指定在评估任务序列变量时要使用的 Configuration Manager 的优先级。
将所有变量添加到集合属性后，选择“ 确定”。

TSEnvironment COM 对象

若要使用脚本中的变量，请使用 TSEnvironment 对象。

有关详细信息，请参阅如何在 Configuration Manager SDK 的正在运行的任务序列中使用变量。

预启动命令

预启动命令是在用户选择任务序列之前在 Windows PE 中运行的脚本或可执行文件。预启动命令可以查询变量或提示用户输入信息，然后将其保存在环境中。使用 TSEnvironment COM 对象从预启动命令读取和写入变量。

有关详细信息，请参阅任务序列媒体的预启动命令。

任务序列向导

在“任务序列向导”窗口中选择任务序列后，用于编辑任务序列变量的页面将包含“ 编辑” 按钮。可以使用可访问的键盘快捷方式来编辑变量。如果鼠标不可用，此更改会有所帮助。

任务序列媒体向导

为从媒体运行的任务序列指定变量。使用媒体部署 OS 时，添加任务序列变量并在创建媒体时指定其值。变量及其值存储在媒体上。

注意

任务序列存储在独立媒体上。但是，所有其他类型的媒体（例如预留媒体）都会从管理点检索任务序列。

从媒体运行任务序列时，可以在向导的 “自定义” 页上添加变量。

使用媒体变量代替每个集合或每计算机变量。如果任务序列从媒体运行，则每台计算机和每集合变量不适用，也不会使用。

提示

任务序列将包 ID 和预启动命令行写入运行 Configuration Manager 控制台的计算机上的 CreateTSMedia.log 文件。此日志文件包括任何任务序列变量的值。查看此日志文件以验证任务序列变量的值。

有关详细信息，请参阅创建任务序列媒体。

如何访问变量

使用上一部分中的方法之一指定变量及其值后，请在任务序列中使用它。例如，访问内置任务序列变量的默认值，或根据变量的值设置步骤条件。

使用以下方法访问任务序列环境中的变量值：

在步骤中使用
步骤条件
自定义脚本
Windows 安装程序应答文件

在步骤中使用

为任务序列步骤中的设置指定变量值。在任务序列编辑器中，编辑步骤，并将变量名称指定为字段值。将变量名称括在百分号 (%) 。

例如，使用变量名称作为“运行命令行”步骤的“命令行”字段的一部分。以下命令行将计算机名称写入文本文件。

cmd.exe /c echo %_SMSTSMachineName% > C:\File.txt

步骤条件

使用内置或自定义任务序列变量作为步骤或组条件的一部分。任务序列在运行步骤或组之前评估变量值。

若要添加计算变量值的条件，请执行以下步骤：

在任务序列编辑器中，选择要向其添加条件的步骤或组。
切换到步骤或组的“ 选项 ”选项卡。单击“ 添加条件”，然后选择“ 任务序列变量”。
在“ 任务序列变量 ”对话框中，指定以下设置：
- 变量：变量的名称。例如，_SMSTSInWinPE。
- 条件：用于计算变量值的条件。以下条件可用：
  - Exists
  - 不存在
  - 等于
  - 不等于
  - 大于
  - 大于或等于
  - 小于
  - 小于或等于
  - like (支持通配符 * 和 ?)
  - 不像 (版本 2103 或更高版本)
- 值：要检查的变量的值。例如，false。

上面的三个示例构成了一个常见条件，用于测试任务序列是否从 Windows PE 中的启动映像运行：

任务序列变量_SMSTSInWinPE equals "false"

有关默认任务序列模板的 捕获文件和设置 组，请参阅此条件，以安装现有 OS 映像。

有关条件的详细信息，请参阅任务序列编辑器 - 条件。

自定义脚本

在任务序列运行时，使用 Microsoft.SMS.TSEnvironment COM 对象读取和写入变量。

以下 Windows PowerShell 示例查询 _SMSTSLogPath 变量以获取当前日志位置。该脚本还设置自定义变量。

# Create an object to access the task sequence environment
$tsenv = New-Object -ComObject Microsoft.SMS.TSEnvironment

# Query the environment to get an existing variable
# Set a variable for the task sequence log path
$LogPath = $tsenv.Value("_SMSTSLogPath")

# Or, convert all of the variables currently in the environment to PowerShell variables
$tsenv.GetVariables() | % { Set-Variable -Name "$_" -Value "$($tsenv.Value($_))" }

# Write a message to a log file
Write-Output "Hello world!" | Out-File -FilePath "$LogPath\mylog.log" -Encoding "Default" -Append

# Set a custom variable "startTime" to the current time
$tsenv.Value("startTime") = (Get-Date -Format HH:mm:ss) + ".000+000"

Windows 安装程序应答文件

提供的 Windows 安装程序应答文件可以包含嵌入的任务序列变量。使用格式 %varname%，其中 varname 是变量的名称。 安装程序 Windows 和 ConfigMgr 步骤将替换实际变量值的变量名称字符串。这些嵌入的任务序列变量不能在 unattend.xml 应答文件的仅数值字段中使用。

有关详细信息，请参阅设置 Windows 和 ConfigMgr。

通过