Carbon_Script

DSC resource for running PowerShell script blocks, including the ability to pass arguments to those blocks.

Syntax

Carbon_Script [string] #ResourceName
{
    GetScript = [string]
    SetScript = [string]
    TestScript = [string]
    [ DependsOn = [string[]] ]
    [ GetArgumentList = [string[]] ]
    [ SetArgumentList = [string[]] ]
    [ TestArgumentList = [string[]] ]
}

Description

The Carbon_Script resource runs custom PowerShell script blocks, with support for passing arguments to those blocks. Passing arguments is optional.

This is useful if you want to run custom code on multiple computers, but the code needs to vary slightly between those computers.

The GetScript script must return a hashtable.

The TestScript script must return a bool. If you want to call the GetScript from your TestScript, simply add a call to Get-TargetResource:

TestScript = {
    $resource = Get-TargetResource @PSBoundParameters
}

In fact, you can call any of the *-TargetResource functions from your scripts.

All arguments are passed as strings, so if you need them converted to other types, you'll have to do the converting. If you get an error about an invalid MOF file, double-check that you're calling ToString() on all non-string objects. Be careful!

Parameters

Name Type Description Required? Pipeline Input Default Value
GetScript String The script block to run when getting resource information. true false
GetArgumentList String[] The arguments to pass to the GetScript script block. false false
SetScript String The script block to run to set/remove your resource. true false
SetArgumentList String[] The arguments to pass to the SetScript script block. false false
TestScript String The script block to run when testing your resource. Must return $true or $false. true false
TestArgumentList String[] The arguments to pass to the TestScrtip script block. false false

EXAMPLE 1

Demonstrates how to use the Carbon_Script resource.

Carbon_Script CustomizeIt
{
    GetScript = {
        param(
            $Name
        )

        if( Get-Service -Name $Name -ErrorACtion Ignore )
        {
            return @{
                Ensure = 'Present'
            }
        }
        else
        {
            return @{
                Ensure = 'Absent';
            }
        }
    }
    GetArgumentList = @( 'CarbonNoOpService' ;
    SetScript = {
        param(
            $Name
        )

        $resource = Get-TargetResource -Name $Name
        if( $resource.Ensure -eq 'Present' )
        {
            Restart-Service -Name $Name
        }
    }
    SetARgumentList = @( 'CarbonNoOpService' );
    TestScript = {
        param(
            $Name
        )

        $resource = Get-TargetResource -Name $Name
        return ($resource -eq 'Absent')
    }
    TestArgumentList = @( 'CarbonNoOpService' );
}

In this example, we are restarting a service, if it is present, and passing the name of that service into our script blocks, which is really useful if the name of the service changes between computers.