DSC Script Resource

Applies To: Windows PowerShell 4.0, Windows PowerShell 5.x

The Script resource in Windows PowerShell Desired State Configuration (DSC) provides a mechanism to run Windows PowerShell script blocks on target nodes. The Script resource uses GetScript SetScript, and TestScript properties that contain script blocks you define to perform the corresponding DSC state operations.

Syntax

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

Properties

Common properties

Additional information

GetScript

DSC doesn't use the output from GetScript The Get-DscConfiguration cmdlet executes GetScript to retrieve a node's current state. A return value isn't required from GetScript If you specify a return value, it must be a hashtable containing a Result key whose value is a String.

TestScript

DSC executes TestScript to determine if SetScript should be run. If TestScript returns $false, DSC executes SetScript to bring the node back to the desired state. It must return a boolean value. A result of $true indicates that the node is compliant and SetScript shouldn't execute.

The Test-DscConfiguration cmdlet executes TestScript to retrieve the nodes compliance with the Script resources. However, in this case, SetScript doesn't run, no matter what TestScript block returns.

SetScript

SetScript modifies the node to enforce the desired state. DSC calls SetScript if the TestScript script block returns $false. The SetScript should have no return value.

Examples

Example 1: Write sample text using a Script resource

This example tests for the existence of C:\TempFolder\TestFile.txt on each node. If it doesn't exist, it creates it using the SetScript. The GetScript returns the contents of the file, and its return value isn't used.

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) } }
        }
    }
}

Example 2: Compare version information using a Script resource

This example retrieves the compliant version information from a text file on the authoring computer and stores it in the $version variable. When generating the node's MOF file, DSC replaces the $using:version variables in each script block with the value of the $version variable. During execution, the compliant version is stored in a text file on each Node and compared and updated on subsequent executions.

$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')
            }
        }
    }
}

Example 3: Utilizing parameters in a Script resource

This example accesses parameters from within the Script resource by making use of the using scope. ConfigurationData can be accessed in a similar way. Like example 2, the implementation expects a version to be stored inside a local file on the target node. Both the local path and the version are configurable, decoupling code from configuration data.

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
            }
        }
    }
}

The resulting MOF file includes the variables and their values accessed through the using scope. They're injected into each scriptblock, which uses the variables. Test and Set scripts are removed for brevity:

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

Known Limitations

• Credentials being passed within a script resource aren't always reliable when using a pull or push server model. Use a full resource rather than use a script resource in this case.