DSC スクリプト リソース

適用対象: Windows PowerShell 4.0、Windows PowerShell 5.x

Windows PowerShell Desired State Configuration (DSC) の Script リソースには、ターゲット ノードで Windows PowerShell スクリプト ブロックを実行するメカニズムが用意されています。 Script リソースは、GetScriptSetScriptと、対応する DSC 状態操作を実行するために定義したスクリプト ブロックを含むプロパティを TestScript します。

先端

可能であれば、このリソースではなく、定義済みの DSC リソースを使用することをお勧めします。 Script リソースには、テスト、保守、予測がより困難になる欠点があります。

他の DSC リソースとは異なり、Script リソースのすべてのプロパティはキー プロパティであり、このリソースの Get メソッドは現在の状態の 1 つの文字列のみを返すことができます。 このリソースがべき等的に実装されていること、またはカスタム コードを使用しているため、どのシステムでも想定どおりに動作するという保証はありません。 ターゲット システムで呼び出されないと、テストできません。

リソースを使用する前に、代わりにリソース を作成 かどうかを検討してください。 適切に定義された DSC リソースを使用すると、構成の読みやすさと保守性が高くなります。

手記

この DSC リソースのこのドキュメントでは、バージョン 7.2 より前の PowerShell に含まれているバージョンについて説明します。 PSDscResources モジュールには、Microsoft によって正式にサポートされている新規および更新された DSC リソースが含まれています。 PSDscResources モジュールは、PowerShell ギャラリーから入手できます。

詳細および更新されたドキュメントについては、PSDscResources リファレンス ドキュメントを参照してください。

構文

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

手記

GetScript TestScript、および SetScript ブロックは文字列として格納されます。

プロパティ

財産	形容
GetScript	Node の現在の状態を返すスクリプト ブロック。
SetScript	ノードが目的の状態でない場合に、DSC がコンプライアンスを適用するために使用するスクリプト ブロック。
TestScript	Node が目的の状態であるかどうかを判断するスクリプト ブロック。
資格 情報	資格情報が必要な場合に、このスクリプトの実行に使用する資格情報を示します。

共通プロパティ

財産	形容
DependsOn	このリソースを構成する前に、別のリソースの構成を実行する必要があることを示します。
PsDscRunAsCredential	リソース全体を実行するための資格情報を次のように設定します。

手記

PsDscRunAsCredential 共通プロパティが WMF 5.0 に追加され、他の資格情報のコンテキストで DSC リソースを実行できるようになります。 詳細については、「DSC リソースで資格情報を使用する」を参照してください。

追加情報

GetScript

DSC では、GetScript からの出力は使用されません。Get-DscConfiguration コマンドレットは、ノードの現在の状態を取得するために GetScript 実行します。 戻り値は、GetScript から必要ありません戻り値を指定する場合は、値が文字列である 結果 キーを含むハッシュテーブルである必要があります。

TestScript

DSC は TestScript を実行して、SetScript を実行する必要があるかどうかを判断します。 TestScript が $falseを返す場合、DSC は SetScript を実行してノードを目的の状態に戻します。 ブール値を返す必要があります。 $true の結果は、ノードが準拠しており、SetScript は実行できないことを示します。

Test-DscConfiguration コマンドレットは、TestScript を実行して、Script リソースに準拠しているノードを取得します。 ただし、この場合、SetScript は、TestScript ブロックが返しても実行されません。

手記

TestScript からの出力はすべて、その戻り値の一部です。 PowerShell は、抑制されていない出力を 0 以外と解釈します。つまり、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 スコープを介してアクセスされる変数とその値が含まれます。 変数を使用する各スクリプト ブロックに挿入されます。 簡潔にするために、テスト スクリプトと Set スクリプトが削除されます。

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 = ...;
};

既知の制限事項

• プル サーバー モデルまたはプッシュ サーバー モデルを使用する場合、スクリプト リソース内で渡される資格情報は常に信頼できるとは限りません。 この場合は、スクリプト リソースを使用するのではなく、完全なリソースを使用します。