DSC Script リソース

  • [アーティクル]

適用先:Windows PowerShell 4.0、Windows PowerShell 5.x

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

ヒント

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

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

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

注意

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

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

構文

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

Note

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

プロパティ

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

共通プロパティ

プロパティ 説明
DependsOn このリソースを構成する前に、他のリソースの構成を実行する必要があることを示します。
PsDscRunAsCredential リソース全体を実行するための資格情報を設定します。

注意

PsDscRunAsCredential という共通プロパティは、他の資格情報という文脈の中であらゆる DSC リソースを実行するために WMF 5.0 で追加されました。 詳細については、「DSC リソースに対して資格情報を使用する」を参照してください。

関連情報

GetScript

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

TestScript

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

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

注意

TestScript からの出力はすべて、戻り値の一部です。 PowerShell は、抑制されていない出力を 0 以外として解釈します。つまり、ノードの状態に関係なく が返$trueされることをTestScript意味します。 これにより、誤検知という予期しない結果となり、トラブルシューティングの際に困難が生じます。

SetScript

SetScript ではノードを変更して、目的の状態を適用します。 スクリプト ブロックが を返す場合、TestScriptDSC は を呼び出SetScriptします$false。 SetScript には、戻り値はありません。

例

例 1:Script リソースを使用して、サンプル テキストを作成する

この例では、各ノード上の 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:Script リソースを使用してバージョン情報を比較する

この例は、オーサリング コンピューター上のテキスト ファイルから compliant バージョン情報を取得して、これを $version 変数に格納します。 ノードの MOF ファイルを生成するときに、各スクリプト ブロックの $using:version 変数は、DSC によって $version 変数の値に置き換えられます。 実行時に compliant バージョンが各ノード上のテキスト ファイルに格納され、以降の実行で比較され更新されます。

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

既知の制限事項

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