DSC 腳本資源

發行項
08/08/2024

適用於：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 資源的本文件涵蓋 PowerShell 7.2 版之前隨附的版本。 PSDscResources 模組包含Microsoft正式支援的全新和更新 DSC 資源。您可以從 PowerShell 資源庫取得 PSDscResources 模組。

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

語法

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

注意

GetScript TestScript和 SetScript 區塊會儲存為字串。

性能

財產	描述
GetScript	傳回節點目前狀態的腳本區塊。
SetScript	DSC 在節點未處於預期狀態時，用來強制執行合規性的腳本區塊。
TestScript	腳本區塊，判斷節點是否處於預期狀態。
憑據	指出需要認證時，用於執行此腳本的認證。

通用屬性

財產	描述
DependsOn	表示必須執行另一個資源的設定，才能設定此資源。
PsDscRunAsCredential	將執行整個資源的認證設定為。

注意

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

其他資訊

GetScript

DSC 不會使用來自 GetScript Get-DscConfiguration Cmdlet 的輸出執行 GetScript 來擷取節點的目前狀態。不需要傳回值;如果您指定傳回值，它必須是包含結果索引鍵的哈希表，其值為 String。

TestScript

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

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

注意

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

SetScript

SetScript 修改節點以強制執行所需的狀態。如果 TestScript 腳本區塊傳回 $false，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會將每個腳本區塊中的 $using:version 變數取代為 $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 = ...;
};

已知限制

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

共用方式為