DSC 資源撰寫檢查清單

發行項
01/11/2024

此檢查清單是撰寫新 DSC 資源時的最佳做法清單。

模組包含指令清單

包含 DSC 資源的模組應該會有模組指令清單 (.psd1) 檔案。指令清單的 DscResourcesToExport 設定應該列出每個 DSC 資源的名稱。

您未包含在 DscResourcesToExport 設定中的任何類別型 DSC 資源將無法透過 Get-DscResource Cmdlet 探索、無法與 Cmdlet 搭配 Invoke-DscResource 使用，而且 DSC 組態作者在 VS Code 中撰寫 DSC 設定時，不會取得這些 DSC 資源的 IntelliSense。

每個MOF型 DSC 資源都有架構檔案

檢查您的 DSC 資源是否具有正確的結構，並包含所有必要的檔案。每個MOF型 DSC 資源都應該有檔案 schema.mof 。沒有架構檔案的MOF型 DSC 資源將不會列出， Get-DscResource 而且 DSC 設定作者在 VS Code 撰寫 DSC 組態時，不會取得這些 DSC 資源的 IntelliSense。

DSC 資源的目錄結構 xRemoteFile ，屬於 xPSDesiredStateConfiguration 模組的一部分，如下所示：

xPSDesiredStateConfiguration
    DSCResources
        MSFT_xRemoteFile
            MSFT_xRemoteFile.psm1
            MSFT_xRemoteFile.schema.mof
    Examples
        xRemoteFile_DownloadFile.ps1
    ResourceDesignerScripts
        GenerateXRemoteFileSchema.ps1
    Tests
        ResourceDesignerTests.ps1
    xPSDesiredStateConfiguration.psd1

DSC 資源載入時不會發生錯誤

DSC 資源應該載入而不會發生錯誤。若要確認，請執行 Import-Module <resource_module> -Force 並確認命令不會引發任何錯誤。

DSC 資源具有等冪性

DSC 資源應具有等冪性。當您可以使用相同的屬性多次叫用 DSC 資源的 Set 方法，且一律達到相同的結果時，DSC 資源是等冪的。

例如，使用此參數哈希，使用 PSDscResources 模組的 Registry DSC 資源定義登錄機碼值的預期狀態：

$DscParameters = @{
    Name       = 'Registry'
    ModuleName = 'PSDscResources'
    Property   = @{
        Key       = 'HKEY_CURRENT_USER\DscExample'
        Ensure    = 'Present'
        Force     = $true
        ValueName = 'Test'
        ValueData = 'Example'
        ValueType = 'String'
    }
}

第一次呼叫 Invoke-DscResource -Method Set @DscParameters時， DscExample 登錄機碼應該會出現在Hive中 HKEY_CURRENT_USER ，並將 Test 值設定為 Example。未來的調用不應該變更系統的狀態。

若要確保資源具有等冪性，您可以直接或使用 Invoke-DscResource測試資源。

若要直接測試MOF型 DSC 資源：

執行 DSC 資源的函式 Set-TargetResource 。
檢查系統狀態，確認其處於不需要的設定狀態。
再次執行 DSC 資源的『Set-TargetResource 函式。它不應該引發任何錯誤。
重複步驟 2-3，直到您滿意呼叫 Set-TargetResource 時，只會將所需的狀態設定為預期，且沒有任何錯誤。

若要直接測試以類別為基礎的 DSC 資源：

建立 DSC 資源類別的新實例，並將它儲存至變數做為物件。
將每個屬性的值設定為物件上所需的狀態。
在物件上呼叫 Set 方法。
檢查系統狀態，確認其處於不需要的設定狀態。
再次在物件上呼叫 Set 方法。它不應該引發任何錯誤。
重複步驟 4-5，直到您滿意呼叫 Set 方法時，只會如預期般設定所需的狀態，而不會發生任何錯誤。

若要使用 Invoke-DscResource測試 DSC 資源：

使用 Set 方法執行Invoke-DscResource。
檢查系統狀態，確認其處於不需要的設定狀態。
使用 Set 方法執行Invoke-DscResource。
重複步驟 2-3，直到您滿意使用 Set 方法呼叫Invoke-DscResource時，只會如預期般設定所需的狀態，且沒有任何錯誤。

測試使用者修改案例

即使使用者手動在 DSC 外部變更系統的狀態，DSC 資源仍應該有可預測的行為。以下是當使用者修改系統時，您應該採取的步驟來驗證 DSC 資源的行為：

從系統開始，而不是處於所需狀態。
使用您的資源執行Invoke-DscResource -Method Set
確認 Invoke-DscResource -Method Test 傳回 $true
將設定的項目設定為離開所需的狀態
確認 Invoke-DscResource -Method Test 傳回 $false

以下是使用 Registry DSC 資源更具體的範例：

從未處於所需狀態的登錄機碼開始。
使用所需的狀態屬性執行 Invoke-DscResource -Method Test ，並確定結果的 InDesiredState 屬性為 $false。
使用必要的屬性執行 Invoke-DscResource -Method Get ，並確定報告狀態不符合所需的狀態屬性。
使用所需的狀態屬性執行 Invoke-DscResource -Method Set ，並確定它不會發生錯誤。
再次執行 Invoke-DscResource -Method Test ，並確定結果的 InDesiredState 屬性現在為 true。
再次執行 Invoke-DscResource -Method Get ，並確定報告狀態符合所需的狀態屬性。
設定索引鍵的值，使其不在所需的狀態。
再次執行 Invoke-DscResource -Method Get 以確認已修改的狀態。
再次執行 Invoke-DscResource -Method Test ，並確認它傳回 false。

直接呼叫 DSC 資源函式和方法

請直接呼叫以類別為基礎的 DSC) 資源，並確認它們如預期般運作，以確定您測試 *-TargetResource MOF 基底 DSC 資源 (函式) 和 Get、 Set 和 Test 方法 (。

在每個支援的平台上測試相容性

DSC 資源應該在支援任何平臺 DSC 上運作。如果您的 DSC 資源設計無法在這些平台上運作，請傳回特定的錯誤訊息。請確定 DSC 資源會檢查您正在呼叫的 Cmdlet 是否存在於特定電腦上。

注意

其中一個常見的測試差距是只在伺服器版本的 Windows 上驗證 DSC 資源。 DSC 資源通常也設計為在用戶端 SKU 上運作。如果您的 DSC 資源不支援用戶端 SKU，請確定您測試用戶端 SKU 的行為或錯誤。

Get-DSCResource 列出 DSC 資源

安裝模組時， Get-DscResource 應該在 Cmdlet 輸出中包含 DSC 資源。

模組包含範例

建立品質範例，以協助用戶瞭解如何使用 DSC 資源。這很重要，因為使用者通常會將範例程式代碼視為檔。

首先，決定要包含在模組中的範例。您應該至少涵蓋 DSC 資源最重要的使用案例。

如果您的模組包含數個 DSC 資源，這些資源需要一起處理端對端案例，請先撰寫基本的端對端範例。

盡可能以基本和簡短的方式撰寫您的初始範例。示範如何以小型可管理的區塊開始使用 DSC 資源，例如建立新的 VHD。撰寫稍後的範例以舊版 (為基礎建置，例如從 VHD) 建立 VM，並顯示進階功能 (，例如使用動態記憶體建立 VM) 。

針對每個範例：

撰寫簡短描述，說明其用途，以及如何使用任何參數。
請確認每個範例執行時沒有意外的錯誤或警告，並強制執行所需的狀態。

錯誤訊息是可理解的，並協助使用者解決問題

良好的錯誤訊息應：

存在：如果沒有錯誤訊息，使用者甚至不會知道發生錯誤。
人類可讀：沒有遮蔽的錯誤碼。
精確：確切描述問題。
有意見：提供如何修正問題的建議。
有好感：不要抱怨使用者或讓他們覺得不好。

請確定您在端對端案例中確認錯誤，因為它們可能會與直接針對以類別為基礎的 DSC 資源執行函式 (時所傳回的錯誤) 或方法 () 。

DSC 資源實作不包含硬式編碼路徑

請確定任何 DSC 資源實作中沒有任何硬式編碼路徑，特別是假設語言時，例如 en-US。盡可能使用系統環境變數。

例如，不要這樣撰寫：

$tempPath = "C:\Users\kkaczma\AppData\Local\Temp\MyResource"
$programFilesPath = "C:\Program Files (x86)"

寫入：

$tempPath = Join-Path $env:temp "MyResource"
$programFilesPath = ${env:ProgramFiles(x86)}

DSC 資源實作不包含用戶資訊

DSC 資源不應該在程式代碼中包含個人標識資訊。請確認程式碼中沒有任何電子郵件名稱、帳戶資訊或人名。

使用有效和無效的認證進行測試

如果您的 DSC 資源採用認證作為參數：

確認當帳戶沒有存取權時，DSC 資源的行為會如預期般運作。
確認 DSC 資源適用於針對 Get、 Set 和 Test 指定的認證。
如果您的 DSC 資源存取共用，請測試您需要支援的所有變體，例如：
- 標準窗口共用
- DFS 共用
- 如果您想要支援 Linux) ，SAMBA 共用 (

DSC 資源不需要互動式輸入

DSC 資源不應該提示輸入。相反地，所有必要的值應該是 DSC 資源的屬性。例如，不要提示使用者輸入 Get-Credential，而是將 Credential 屬性新增至 DSC 資源。

徹底測試

此檢查清單包含要測試且經常遺漏的重要專案。您也應該為 DSC 資源撰寫功能和端對端測試案例，以確保預期的行為。請務必使用負面測試案例，並測試無效的輸入。

共用方式為