如何在 Configuration Manager 中使用工作順序變數

發行項
07/04/2024

適用於：Configuration Manager (目前的分支)

Configuration Manager OS 部署功能中的工作順序引擎會使用許多變數來控制其行為。使用這些變數來：

設定步驟的條件
變更特定步驟的行為
在腳本中使用以進行更複雜的動作

如需所有可用工作順序變數的參考，請參閱工作順序變數。

變數類型

變數有數種類型：

內建
動作
自訂
唯讀
Array

內建變數

內建變數提供工作順序執行所在環境的相關信息。其值可在整個工作順序中使用。一般而言，工作順序引擎會先初始化內建變數，再執行任何步驟。

例如， _SMSTSLogPath 是一個環境變數，指定 Configuration Manager 元件寫入記錄檔的路徑。任何工作順序步驟都可以存取此環境變數。

工作順序會在每個步驟之前評估一些變數。例如， _SMSTSCurrentActionName 會列出目前步驟的名稱。

動作變數

工作順序動作變數會指定單一工作順序步驟所使用的組態設定。根據預設，此步驟會在執行之前初始化其設定。只有在執行相關聯的工作順序步驟時，才能使用這些設定。工作順序會在執行步驟之前，將動作變數值新增至環境。然後，它會在步驟執行之後，從環境中移除值。

例如，您會將執行 命令行 步驟新增至工作順序。此步驟包含 Start In 屬性。工作順序會將這個屬性的預設值儲存為 WorkingDirectory 變數。工作順序會先初始化此值，再執行執行 命令行 步驟。當此步驟正在執行時，請從 WorkingDirectory 值存取 Start In 屬性值。步驟完成之後，工作順序會從環境中移除變數的 WorkingDirectory 值。如果工作順序包含另一個 執行命令行 步驟，它會初始化新的 WorkingDirectory 變數。屆時，工作順序會將變數設定為目前步驟的開始值。如需詳細資訊，請參閱 WorkingDirectory。

當步驟執行時，會出現動作變數的預設值。如果您設定新的值，則可在工作順序中使用多個步驟。如果您覆寫預設值，新值會保留在環境中。這個新值會覆寫工作順序中其他步驟的預設值。例如，您將 [ 設定工作順序變數 ] 步驟新增為工作順序的第一個步驟。此步驟會將 WorkingDirectory 變數設定為 C:\。工作順序中的任何執行 命令行 步驟都會使用新的起始目錄值。

某些工作順序步驟會將特定動作變數標示為輸出。稍後在工作順序中的步驟會讀取這些輸出變數。

注意事項

並非所有工作順序步驟都有動作變數。例如，雖然有與 [啟用 BitLocker ] 動作相關聯的變數，但沒有任何變數與 [停用 BitLocker] 動作相關聯。

自訂變數

這些變數是 Configuration Manager 未建立的任何變數。初始化您自己的變數，以做為條件、在命令行或腳本中使用。

當您指定新工作順序變數的名稱時，請遵循下列指導方針：

工作順序變數名稱可以包含字母、數位、底線字元 () _ ，以及連字元 (-) 。
工作順序變數名稱的最小長度為一個字元，最大長度為 256 個字元。
用戶定義變數的開頭必須是字母 (A-Z 或 a-z) 。
用戶定義的變數名稱不能以底線字元開頭。只有唯讀工作順序變數前面會加上底線字元。
工作順序變數名稱不區分大小寫。例如， OSDVAR 和 osdvar 是相同的工作順序變數。
工作順序變數名稱不能以空格開頭或結尾。它們也不能有內嵌空格。工作順序會忽略變數名稱開頭或結尾的任何空格。

您可以建立的工作順序變數數目沒有設定的限制。不過，變數數目受限於工作順序環境的大小。工作順序環境的總大小限制為8 KB。如需詳細資訊，請參閱減少工作順序原則的大小。

唯讀變數

您無法變更某些變數的值，這些變數是唯讀的。名稱的開頭通常是底線字元 (_) 。工作順序會將它們用於其作業。只讀變數會顯示在工作順序環境中。

這些變數在腳本或命令行中很有用。例如，執行命令行，並將輸出與其他記錄檔一起管線傳送至中的 _SMSTSLogPath 記錄檔。

注意事項

只讀工作順序變數可由工作順序中的步驟讀取，但無法設定。例如，在執行命令行步驟的命令行中使用只讀變數。您無法使用 [設定工作順序變數] 步驟來設定唯讀變數。

陣列變數

工作順序會將一些變數儲存為陣列。陣列中的每個元素都代表單一對象的設定。當裝置有多個要設定的物件時，請使用這些變數。下列工作順序步驟會使用數位變數：

如何設定變數

對於非只讀的自定義變數或變數，有數種方法可以初始化和設定變數的值：

設定工作順序變數步驟
設定動態變數步驟
執行 PowerShell 腳本步驟
集合和裝置變數
TSEnvironment COM 物件
啟動前置命令
工作順序精靈
工作順序媒體精靈

使用與建立變數相同的方法，從環境中刪除變數。若要刪除變數，請將變數值設定為空字串。

您可以結合方法，將工作順序變數設定為相同序列的不同值。例如，使用工作順序編輯器設定預設值，然後使用腳本設定自定義值。

如果您透過不同的方法設定相同的變數，工作順序引擎會使用下列順序：

它會先評估集合變數。
裝置特定變數會覆寫集合上設定的相同變數。
工作順序期間由任何方法設定的變數優先於集合或裝置變數。

工作順序變數值的一般限制

工作順序變數值不能超過 4,000 個字元。
您無法變更唯讀工作順序變數。唯讀變數的名稱開頭為底線字元 () _ 。
工作順序變數值可以區分大小寫，視值的使用方式而定。在大部分情況下，工作順序變數值不會區分大小寫。包含密碼的變數會區分大小寫。

設定工作順序變數

在工作順序中使用此步驟，將單一變數設定為單一值。

如需詳細資訊，請參閱設定工作順序變數。

設定動態變數

在工作順序中使用此步驟來設定一或多個工作順序變數。您可以在此步驟中定義規則，以判斷要使用的變數和值。

如需詳細資訊，請參閱設定動態變數。

執行 PowerShell 腳本

在工作順序中使用此步驟，使用 PowerShell 腳本來設定工作順序變數。

您可以從封裝指定文本名稱，或直接在步驟中輸入PowerShell腳本。然後使用 [ 輸出至工作順序變數 ] 的步驟屬性，將腳本輸出儲存至自定義工作順序變數。

如需此步驟的詳細資訊，請參閱執行 PowerShell 腳本。

注意事項

您也可以使用PowerShell腳本，透過 TSEnvironment 物件設定一或多個變數。如需詳細資訊，請參閱 How to use variables in a running task sequence in the 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 物件。

如需詳細資訊，請參閱 How to use variables in a running task sequence in the Configuration Manager SDK。

啟動前置命令

啟動前置命令是腳本或可執行檔，可在用戶選取工作順序之前於 Windows PE 中執行。啟動前置命令可以查詢變數或提示使用者提供資訊，然後將它儲存在環境中。使用 TSEnvironment COM 物件從啟動前置命令讀取和寫入變數。

如需詳細資訊，請參閱工作順序媒體的啟動前置命令。

工作順序精靈

在 [工作順序精靈] 視窗中選取工作順序之後，編輯工作順序變數的頁面會包含 [ 編輯 ] 按鈕。您可以使用可存取的鍵盤快捷方式來編輯變數。在滑鼠無法使用的情況下，這項變更會有所説明。

工作順序媒體精靈

指定從媒體執行之工作順序的變數。使用媒體部署 OS 時，您可以新增工作順序變數，並在建立媒體時指定其值。變數及其值會儲存在媒體上。

注意事項

工作順序會儲存在獨立媒體上。不過，所有其他類型的媒體，例如預先設置的媒體，都會從管理點擷取工作順序。

當您從媒體執行工作順序時，可以在精靈的 [ 自定義 ] 頁面上新增變數。

使用媒體變數來取代每個集合或每部計算機的變數。如果工作順序是從媒體執行，則不會套用每部計算機和每個集合變數，也不會使用。

提示

工作順序會將套件標識碼和啟動前置命令行寫入執行 Configuration Manager 控制台之電腦上的 CreateTSMedia.log 檔案。此記錄檔包含任何工作順序變數的值。檢閱此記錄檔，以確認工作順序變數的值。

如需詳細資訊，請參閱建立工作順序媒體。

如何存取變數

使用上一節的其中一個方法來指定變數及其值之後，請在工作順序中使用它。例如，存取內建工作順序變數的預設值，或對變數的值設定步驟條件。

使用下列方法來存取工作順序環境中的變數值：

在步驟中使用
步驟條件
自訂腳本
Windows 安裝程式回應檔案

在步驟中使用

為工作順序步驟中的設定指定變數值。在工作順序編輯器中，編輯步驟，並將變數名稱指定為域值。以百分比符弧括住變數名稱 (%) 。

例如，使用變數名稱作為 [執行 命令行 ] 步驟之 [ 命令行 ] 字段的一部分。下列命令列會將計算機名稱寫入文字檔。

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

步驟條件

使用內建或自定義工作順序變數作為步驟或群組上條件的一部分。工作順序會在執行步驟或群組之前評估變數值。

若要新增評估變數值的條件，請執行下列步驟：

在工作順序編輯器中，選取您要新增條件的步驟或群組。
切換至步驟或群組的 [ 選項] 索引標籤。按兩下 [新增條件]，然後選取 [ 工作順序變數]。
在 [ 工作順序變數 ] 對話框中，指定下列設定：
- 變數：變數的名稱。例如，_SMSTSInWinPE。
- 條件：要評估變數值的條件。有下列條件可供使用：
  - Exists
  - 不存在
  - 等於
  - 不等於
  - 大於
  - 大於或等於
  - 小於
  - 小於或等於
  - 就像 (支援和 ?) 的*通配符
  - 不像 (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。

共用方式為

如何在 Configuration Manager 中使用工作順序變數

變數類型

內建變數

動作變數

自訂變數

唯讀變數

陣列變數

如何設定變數

工作順序變數值的一般限制

設定工作順序變數

設定動態變數

執行 PowerShell 腳本

使用執行 PowerShell 腳本步驟的範例案例

集合和裝置變數

建立裝置的工作順序變數

建立集合的工作順序變數

TSEnvironment COM 物件

啟動前置命令

工作順序精靈

工作順序媒體精靈

如何存取變數

在步驟中使用

步驟條件

自訂腳本

Windows 安裝程式回應檔案

另請參閱

意見反應

其他資源