DSC Script 資源

發行項
12/02/2023

適用於：Windows PowerShell 4.0、Windows PowerShell 5.x

Windows PowerShell 預期狀態設定 (DSC) 的 Script 資源提供了在目標節點執行 Windows PowerShell 指令碼區塊的機制。 Script 資源會使用 GetScriptSetScript 和 TestScript 屬性，其包含定義來執行對應 DSC 狀態作業的指令碼區塊。

提示

可能的話，最佳做法是使用定義的 DSC 資源，而不是這個資源。資源 Script 有缺點，讓測試、維護和預測更為困難。

不同于其他 DSC 資源，資源的每個屬性 Script 都是索引鍵屬性，而此資源的 Get 方法只能傳回目前狀態的單一字串。不保證此資源會以等冪方式實作，或在任何系統上如預期般運作，因為它使用自訂程式碼。在目標系統上叫用它，就無法進行測試。

使用 Script 資源之前，請考慮您是否可以改為撰寫資源。使用定義完善的 DSC 資源可讓您的設定更容易閱讀和維護。

注意

此 DSC 資源的這份檔涵蓋 7.2 版之前 PowerShell 隨附的版本。 PSDscResources模組包含 Microsoft 正式支援的全新和更新 DSC 資源。 PSDscResources 模組可從 PowerShell 資源庫中取得。

如需詳細資訊和更新的檔，請參閱 PSDscResources 參考檔。

Syntax

Script [string] #ResourceName
{
    GetScript = [string]
    SetScript = [string]
    TestScript = [string]
    [ Credential = [PSCredential] ]
    [ DependsOn = [string[]] ]
    [ PsDscRunAsCredential = [PSCredential] ]
}

注意

GetScriptTestScript、和 SetScript 區塊會儲存為字串。

屬性

屬性	描述
GetScript	指令碼區塊，會傳回節點的目前狀態。
SetScript	DSC 在節點未處於所需狀態時，用來強制執行合規性的腳本區塊。
TestScript	指令碼區塊，可判斷節點是否處於預期狀態。
認證	如果需要認證，表示執行這個指令碼所要使用的認證。

通用屬性

屬性	描述
DependsOn	表示必須先執行另一個資源的設定，再設定這個資源。
PsDscRunAsCredential	設定用於執行整個資源的認證。

注意

已在 WMF 5.0 中新增 PsDscRunAsCredential 通用屬性，以允許在其他認證的內容中執行任何 DSC 資源。如需詳細資訊，請參閱搭配 DSC 資源使用認證。

其他資訊

GetScript

DSC 不會使用Get-DscConfiguration Cmdlet GetScript 執行的輸出 GetScript 來擷取節點的目前狀態。如果指定傳回值，則不需要傳 GetScript 回值，它必須是包含 值為 String 之 Result 索引鍵的雜湊表。

TestScript

DSC 會 TestScript 執行以判斷是否 SetScript 應該執行。如果 TestScript 傳回 $false，DSC 就會執行 SetScript，以讓節點回到預期狀態。它必須傳回布林值。的結果 $true 表示節點符合規範且 SetScript 不應該執行。

Test-DscConfiguration Cmdlet 會 TestScript 執行以擷取節點與 Script 資源的合規性。不過，在此情況下， SetScript 不論哪個 TestScript 區塊傳回，都不會執行。

注意

來自您 TestScript 的所有輸出都是其傳回值的一部分。 PowerShell 會將未壓縮的輸出解譯為非零，這表示不論節點的狀態為何，都會 TestScript 傳回 $true 。這會產生無法預期的結果、誤判，並導致疑難排解期間出現問題。

SetScript

SetScript 會修改節點以強制進入預期狀態。如果腳本區塊傳 $false 回， TestScript DSC 會呼叫 SetScript 。 SetScript 應該不會傳回值。

範例

範例 1：使用指令碼資源撰寫範例文字

此範例會在每個節點上測試 C:\TempFolder\TestFile.txt 是否存在。如果不存在，它會使用建立 SetScript 它。會 GetScript 傳回檔案的內容，而且不會使用其傳回值。

Configuration ScriptTest
{
    Import-DscResource -ModuleName 'PSDesiredStateConfiguration'

    Node localhost
    {
        Script ScriptExample
        {
            SetScript = {
                $sw = New-Object System.IO.StreamWriter("C:\TempFolder\TestFile.txt")
                $sw.WriteLine("Some sample string")
                $sw.Close()
            }
            TestScript = { Test-Path "C:\TempFolder\TestFile.txt" }
            GetScript = { @{ Result = (Get-Content C:\TempFolder\TestFile.txt) } }
        }
    }
}

範例 2：使用指令碼資源比較版本資訊

此範例會從撰寫電腦上的文字檔擷取「符合規範」的版本資訊，並將它儲存在 $version 變數中。產生節點的 MOF 檔案時，DSC 會使用 $version 變數的值，來取代每個指令碼區塊中的 $using:version 變數。執行期間，「符合規範」的版本會儲存在每個節點的文字檔中，並與後續執行進行比較及更新。

$version = Get-Content 'version.txt'

Configuration ScriptTest
{
    Import-DscResource -ModuleName 'PSDesiredStateConfiguration'

    Node localhost
    {
        Script UpdateConfigurationVersion
        {
            GetScript = {
                $currentVersion = Get-Content (Join-Path -Path $env:SYSTEMDRIVE -ChildPath 'version.txt')
                return @{ 'Result' = "$currentVersion" }
            }
            TestScript = {
                # Create and invoke a scriptblock using the $GetScript automatic variable, which contains a string representation of the GetScript.
                $state = [scriptblock]::Create($GetScript).Invoke()

                if( $state.Result -eq $using:version )
                {
                    Write-Verbose -Message ('{0} -eq {1}' -f $state.Result,$using:version)
                    return $true
                }
                Write-Verbose -Message ('Version up-to-date: {0}' -f $using:version)
                return $false
            }
            SetScript = {
                $using:version | Set-Content -Path (Join-Path -Path $env:SYSTEMDRIVE -ChildPath 'version.txt')
            }
        }
    }
}

範例 3：利用指令碼資源中的參數

此範例使用 using 範圍，存取指令碼資源中的參數。 ConfigurationData 可以類似的方式存取。如同範例 2，實作預期版本會儲存在目標節點上的本機檔案內。本機路徑和版本都是可設定的，可從組態資料分離程式碼。

Configuration ScriptTest
{
    param
    (
        [Version]
        $Version,

        [string]
        $FilePath
    )

    Import-DscResource -ModuleName 'PSDesiredStateConfiguration'

    Node localhost
    {
        Script UpdateConfigurationVersion
        {
            GetScript = {
                $currentVersion = Get-Content -Path $using:FilePath
                return @{ 'Result' = "$currentVersion" }
            }
            TestScript = {
                # Create and invoke a scriptblock using the $GetScript automatic variable,
                # which contains a string representation of the GetScript.
                $state = [scriptblock]::Create($GetScript).Invoke()

                if( $state['Result'] -eq $using:Version )
                {
                    Write-Verbose -Message ('{0} -eq {1}' -f $state['Result'],$using:version)
                    return $true
                }

                Write-Verbose -Message ('Version up-to-date: {0}' -f $using:version)
                return $false
            }
            SetScript = {
                Set-Content -Path $using:FilePath -Value $using:Version
            }
        }
    }
}

產生的 MOF 檔案包含透過 using 範圍存取的變數及其值。它們會插入每個 scriptblock，以使用變數。為了簡潔起見，會移除測試和設定腳本：

instance of MSFT_ScriptResource as $MSFT_ScriptResource1ref
{
 GetScript = "$FilePath ='C:\\Config.ini'\n\n $currentVersion = Get-Content -Path $FilePath\n return @{ 'Result' = \"$currentVersion\" }\n";
 TestScript = ...;
 SetScript = ...;
};

已知限制

使用提取或推送伺服器模型時，腳本資源內傳遞的認證不一定可靠。在此情況下，請使用完整資源，而不是使用腳本資源。

共用方式為