適用於機器設定的 PowerShell Desired State Configuration 行為變更

開始之前，最好閱讀機器設定概觀。

請參閱此文件的逐步解說影片 (英文)。

機器設定會使用 PowerShell Desired State Configuration (PSDSC) 第 3 版來稽核和設定機器。 DSC 設定會定義機器所應處於的狀態。 在機器設定中實作 DSC 的方式有許多值得注意的差異。

機器設定跨平台使用 PowerShell 7

機器設定的設計目的是讓管理 Windows 和 Linux 的體驗保持一致。 在這兩個作業系統環境中，具有 PowerShell DSC 知識的人員可以使用指令碼技能來建立和發佈設定。

機器設定只會使用 PowerShell DSC 第 3 版，而且不依賴下列項目的先前實作：適用於 Linux 的 DSC 或該存放庫中所含的 nx* 提供者。

從 1.26.33 版起，機器設定會在適用於 Windows 的 PowerShell 7.1.2 以及適用於 Linux 的 PowerShell 7.2 預覽版 6 中運作。 從 7.2 版開始，PSDesiredStateConfiguration 模組已從成為 PowerShell 安裝的一部分移動，並改為安裝為 PowerShell 資源庫中的模組。

多重設定

機器設定支援將多個設定指派給相同機器。 機器設定延伸模組的作業系統內不需要採取任何特殊步驟。 不需要設定部分設定。

相依性是根據設定進行管理

設定是使用可用的工具進行封裝時，設定的必要相依性會包含在 .zip 檔案中。 機器會將內容擷取至每個設定的唯一資料夾。 機器設定延伸模組所提供的代理程式會為每個設定建立專用的 PowerShell 工作階段。 其會使用 $Env:PSModulePath，以限制只會將模組自動載入到擷取套件時所在的路徑。

這項變更有多個好處：

• 在相同的機器上，每個設定都可能使用不同的模組版本。
• 當機器上不再需要設定時，代理程式會安全地刪除擷取設定時所在的整個資料夾。 您不需要管理在多個設定中共用的相依性。
• 不需要管理中央服務中任何模組的多個版本。

成品是以套件形式進行管理

「Azure 自動化狀態設定」功能包括模組和設定指令碼的成品管理。 將兩者都發佈至服務之後，即可將指令碼編譯成 MOF 格式。 同樣地，Windows 提取伺服器也需要管理 Web 服務執行個體上的設定和模組。 相比之下，DSC 延伸模組具有簡化的模型，其中所有成品都會封裝在一起，並儲存至可使用 HTTPS 要求從目標機器存取的位置。 Azure Blob 儲存體是用於裝載成品的熱門選項。

機器設定只會使用簡化的模型，其中所有成品都會封裝在一起，並透過 HTTPS 從目標機器進行存取。 不需要在服務中發佈模組、指令碼或編譯。 其中一項變更是套件應該一律包括已編譯的 MOF。 您無法在套件中包括指令碼檔案，以及在目標機器上編譯。

自訂設定套件的大小上限

在 Azure 自動化狀態設定中，DSC 設定的大小有所限制。 機器設定支援 100 MB 的總套件大小 (壓縮之前)。 套件內的 MOF 檔案大小沒有特定限制。

設定模式設定於套件成品中

建立設定套件時，會使用下列選項來設定模式：

• Audit - 驗證機器的合規性。 不會進行任何變更。
• AuditandSet - 驗證並補救機器的合規性狀態。 如果機器不符合規範，則會進行變更。

模式會設定在套件中，而不是設定在本機 Configuration Manager 服務中，因為每個設定都可能以不同的模式來套用。

透過 Azure Resource Manager 的參數支援

將檔案儲存至機器時，機器設定指派中的 configurationParameter 屬性陣列所設定的參數會覆寫設定 MOF 檔案內的靜態文字。 參數可實現自訂，並可讓操作員控制來自服務 API 的變更，而不需要在機器內執行命令。

Azure 原則中將值傳遞給機器設定指派的參數必須是「字串」類型。 即使 DSC 資源支援陣列，還是無法透過參數來傳遞陣列。

從外部機器設定的觸發程序

舊版 DSC 的挑戰是大規模更正漂移，而不需要太多自訂程式碼和依賴 WinRM 遠端連線。 客體設定可以解決此問題。 機器設定的使用者可以透過補救隨選來控制漂移更正。

序列包括 Get 方法

機器設定稽核或設定機器時，將會針對 Windows 和 Linux 使用相同的事件序列。 值得注意的行為變更是 Get 方法，而服務會呼叫此方法來傳回機器狀態詳細資料。

1. 代理程式會先執行 Test 來判斷設定是否處於正確狀態。
2. 如果套件設定為 Audit，則函數所傳回的布林值可判斷客體指派的 Azure Resource Manager 狀態應該是 Compliant 還是 NonCompliant。
3. 如果套件設定為 AuditandSet，則布林值可決定是否要補救機器，方法是使用 Set 方法來套用設定。 如果 Test 方法傳回 $false，則會執行 Set。 如果 Test 傳回 $true，則不會執行 Set。
4. 最後，提供者會執行 Get 以傳回每個設定的目前狀態，藉此得知為何機器不符合規範以及確認目前的狀態是否符合規範這兩項詳細資料。

Get 的特殊需求

DSC Get 方法對於 DSC 不需要的機器設定有特殊需求。

• 所傳回的雜湊表應該包括名為 Reasons 的屬性。
• Reasons 屬性必須為陣列。
• 陣列中的每個項目都應該是一個雜湊表，並具有名為 Code 與 Phrase 的索引鍵。
• 不應該傳回雜湊表以外的值。

服務會使用 Reasons 屬性來標準化合規性資訊的呈現方式。 您可以將 Reasons 中的每個項目都視為是有關該資源為何符合規範或不符合規範的訊息。 屬性是一個陣列，因為資源可能會因為一個以上的原因而不符合規範。

服務會預期 Code 與 Phrase 的屬性。 撰寫自訂資源時，請將想要顯示的文字，設定為資源不符合 Phrase 值規範的原因。 Code 有特定的格式設定需求，因此報告可清楚顯示用來執行稽核的資源資訊。 這項解決方案讓客體設定可具有擴充性。 只要可將輸出作為 Phrase 屬性的字串值傳回，即可執行任何命令。

• Code (字串)：資源的名稱，重複一次名稱，再以不含空格的簡短名稱作為原因識別碼。 這三個值應以冒號來分隔，且不含空格。
  • 例如 registry:registry:keynotpresent
• Phrase (字串)：人類可讀取的文字，以說明為何設定不符合規範。
  • 例如 The registry key $key isn't present on the machine.

$reasons = @()
$reasons += @{
  Code   = 'Name:Name:ReasonIdentifer'
  Phrase = 'Explain why the setting is not compliant'
}
return @{
    reasons = $reasons
}

使用命令列工具來取得會在 Get 中傳回的資訊時，您可能會發現此工具傳回您未預期的輸出。 即使您在 PowerShell 中擷取輸出，輸出還是可能會寫入至標準錯誤。 若要避免此問題，請考慮將輸出重新導向至 Null。

Reasons 屬性內嵌類別

在指令碼型資源中 (僅限 Windows)，結構描述 MOF 檔案包含 Reasons 類別，如下所示。

[ClassVersion("1.0.0.0")]
class Reason
{
  [Read] String Phrase;
  [Read] String Code;
};

[ClassVersion("1.0.0.0"), FriendlyName("ResourceName")]
class ResourceName : OMI_BaseResource
{
  [Key, Description("Example description")] String Example;
  [Read, EmbeddedInstance("Reason")] String Reasons[];
};

在類別型資源 (Windows 和 Linux) 中，Reason 類別會包含在 PowerShell 模組中，如下所示。 Linux 區分大小寫，因此 Code 中的 C 和 Phrase 中的 P 必須大寫。

enum ensure {
  Absent
  Present
}

class Reason {
  [DscProperty()]
  [string] $Code

  [DscProperty()]
  [string] $Phrase
}

[DscResource()]
class Example {

  [DscProperty(Key)]
  [ensure] $ensure

  [DscProperty()]
  [Reason[]] $Reasons

  [Example] Get() {
    # return current current state
  }

  [void] Set() {
    # set the state
  }

  [bool] Test() {
    # check whether state is correct
  }
}

如果資源具有必要屬性，則 Get 也應該與 Reason 類別一起平行傳回這些屬性。 如果未包括 Reason，則服務會包括「全部攔截」行為，而此行為會比較 Get 的值輸入與 Get 所傳回的值，並提供詳細的比較作為 Reason。

設定名稱

自訂設定的名稱在任何位置都必須一致。 這些項目必須有相同的名稱：

• 內容套件的 .zip 檔案
• MOF 檔案中的設定名稱
• Azure Resource Manager 範本中的機器設定指派名稱

在 Windows PowerShell 中執行命令

在 DSC 資源中使用下列模式，即可在 PowerShell 中執行 Windows 模組。 下列模式會暫時將 PSModulePath 設定為執行 Windows PowerShell 而非 PowerShell，以探索 Windows PowerShell 中可用的必要模組。 此範例是改寫自安全網頁伺服器內建 DSC 資源中所用 DSC 資源的程式碼片段。

這個模式會暫時將 PowerShell 執行路徑設定為從 Windows PowerShell 執行，並探索必要的 Cmdlet，在此案例中為 Get-WindowsFeature。 系統隨即傳回命令的輸出，然後將其標準化以滿足相容性要求。 執行 Cmdlet 之後，就會將 $env:PSModulePath 設定回原始路徑。

# The Get-WindowsFeature cmdlet needs to be run through Windows PowerShell
# rather than through PowerShell, which is what the Policy engine runs.
$null = Invoke-Command -ScriptBlock {
    param ([string]$FileName)

    $InitialPSModulePath   = $env:PSModulePath
    $WindowsPSFolder       = "$env:SystemRoot\System32\WindowsPowershell\v1.0"
    $WindowsPSExe          = "$WindowsPSFolder\powershell.exe"
    $WindowsPSModuleFolder = "$WindowsPSFolder\Modules"
    $GetFeatureScriptBlock = {
        param([string]$FileName)

        if (Get-Command -Name Get-WindowsFeature -ErrorAction SilentlyContinue) {
            Get-WindowsFeature -Name Web-Server |
                ConvertTo-Json |
                Out-File $FileName
        } else {
            Add-Content -Path $FileName -Value 'NotServer'
        }
    }

    try {
        # Set env variable to include Windows Powershell modules so we can find
        # the Get-WindowsFeature cmdlet.
        $env:PSModulePath = $WindowsPSModuleFolder
        # Call Windows PowerShell to get the info about the Web-Server feature
        & $WindowsPSExe -command $WindowsFeatureScriptBlock -args $FileName
    } finally {
        # Reset the env variable even if there's an error.
        $env:PSModulePath = $InitialPSModulePath
    }
}

機器設定公開預覽期間無法使用的常見 DSC 功能

在公開預覽期間，機器設定不支援使用 WaitFor* 資源來指定跨機器相依性。 一部機器無法先監看並等候另一部機器進入某個狀態再繼續進行。

機器設定的公開預覽發行版本中無法進行重新開機處理，包括無法使用 $global:DSCMachineStatus。 設定無法在設定結束時或期間重新啟動節點。

所支援模組的已知相容性問題

PowerShell 資源庫中的 PsDscResources 模組以及 Windows 隨附的 PSDesiredStateConfiguration 模組受到 Microsoft 支援，並且已是 DSC 的一組通用資源。 更新 DSCv3 的 PSDscResources 模組之前，請注意下列已知的相容性問題。

• 請不要使用 Windows 所隨附 PSDesiredStateConfiguration 模組中的資源。 請改為切換至 PSDscResources。
• 請不要在 PsDscResources 中使用 WindowsFeature、WindowsFeatureSet、WindowsOptionalFeature 和 WindowsOptionalFeatureSet 資源。 在 Windows Server 上，於 PowerShell 7.1.3 中載入 DISM 模組時有已知問題，需要更新。

DSC for Linux 存放庫中包含的適用於 Linux 的 nx* 資源是結合 C 與 Python 語言所撰寫的。 因為 Linux 上 DSC 的路徑轉接使用 PowerShell，所以現有的 nx* 資源與 DSCv3 不相容。 在包含 Linux 所支援資源的新模組可供使用之前，您需要撰寫自訂資源。

與 DSC 第 3 版和舊版本共存

機器設定中的 DSC 第 3 版可以與 Windows 和 Linux 中所安裝的舊版本共存。 實作是各自獨立的。 不過，DSC 版本之間沒有衝突偵測，因此請不要嘗試管理相同的設定。

下一步

• 閱讀機器設定概觀。
• 開發自訂機器設定套件。
• 使用 GuestConfiguration 模組來為您的環境建立大規模管理的 Azure 原則定義。
• 使用 Azure 入口網站指派您的自訂原則定義。
• 了解如何檢視機器設定的合規性詳細資料原則指派。