You may have noticed in some cmdlets that you can apply a scriptblock to certain parameters and have the scriptblock run during the code execution of the cmdlet. Take Sort-Object for example. I can use a scriptblock to perform a sort by the length of the filenames.

Why Use a ScriptBlock?

So why do this? Well, if a cmdlet supports pipeline input, you don’t want to pipe that information into  ForEach {} and have to iterate through each item because that defeats the purpose of just being able to chain commands together. What looks better?

This:

 
Get-ChildItem | Invoke-SomeAction -Action {$($_.name).OLD}

Or This:

 
Get-ChildItem | ForEach {
    Invoke-SomeAction -Action "$($_.Name).OLD
}

Personally, I am more of a fan of utilizing the pipeline to its maximum capability if allowed to do so.

Let’s take a look at a couple of examples that use parameters which support a scriptblock.

 
Get-ChildItem -File | 
Sort-Object {$_.Name.length} -Descending | 
Select Name

Rename-Item is another cmdlet that has similar capabilities.

 
Get-ChildItem -Filter *.Zip | 
Rename-Item -NewName  {$_.Name -replace 'zip','OLD'} –WhatIf

Here I found any .ZIP file and renamed it to .OLD instead.

So the next question is “How can I do something like this with my own functions?”. Glad you asked that! It really isn’t too difficult to setup a parameter which supports scriptblock use in your script or function.

Edit: Fellow PowerShell MVP Dave Wyatt pointed out in the comments that the scriptblock evaluation happens on its own through an undocumented feature in PowerShell that will invoke the scriptblock, thus erasing the need for any of the code samples that I use below. I am keeping this though for historical reasons and because this continues to show why I blog because if I am wrong, I promise that the correct information will show up at some point by someone who has more knowledge of the subject.

Basically the parameter binder will invoke the scriptblock as long as the parameter supports pipeline input. A quick look at this can be done using Dave’s function as an example and then running a Trace-Command against ParameterBinding.

 
Function Test-ScriptBlockParam {
    Param (
    [parameter(Mandatory, ValueFromPipelineByPropertyName)]
    [string] $Name
    )

    Process {
        $Name
    }  
}

Trace-Command ParameterBinding -PSHost {
    Get-ChildItem | Test-ScriptBlockParam -Name {$_.fullName -replace '(.*)\..*','$1'}
}

Here you can see where the scriptblock is being invoked and the results of it are shown a couple lines later. Much easier to let PowerShell do all of the heavy lifting than to code it youself :).

Build Your Own Parameter

My function that I am going to build out will be called Test-ScriptBlockParam and I will allow a couple of parameters: InputObject and Name. I need one of these parameters to have pipeline support and the other can function without pipeline support (but will be my scriptblock parameter).

 
Function Test-ScriptBlockParam {
    Param (
        [parameter(Mandatory,ValueFromPipeline)]
        [Object[]]$InputObject,
        [parameter(Mandatory)]
        [Object]$Name
    )

So far so good. I am going to define how Name will be used as a scriptblock in the beginning of the function (or Begin{] block since I am using pipeline parameters).

 
Begin {
    If ($PSBoundParameters['Name']) {
        If ($Name -isnot [scriptblock]) {
            $Name = [scriptblock]::Create("Write-Output $Name")
        } Else {
            $Name = [scriptblock]::Create( ($Name -replace '\$_','$Object'))
        }
    }   
}

I want this to work regardless of whether a scriptblock was assigned as the parameter type or not. If a string is used, then it will build out a scriptblock using [scriptblock]::Create() and if a scriptblock has been applied, it makes an adjustment so it works properly in the Process block by replacing the $Name with $Object. This will make more sense after you see the Process{} block.

 
    Process {
        ForEach ($Object in $InputObject) {
            $Name.InvokeReturnAsIs()
        }
    }  
}

Here is the Process block where you see why I had to replace $Name with $Object. Because $Object is the variable that represents an item in the $InputObject collection, it can now run the scriptblock using InvokeReturnAsIs(). This means that whatever I have defined in the scriptblock will run and return the output.

Let’s give this a run and see what happens!

 
Get-ChildItem | 
Test-ScriptBlockParam -Name {"Name of File is: $($_.Name)"}

 
Get-ChildItem | 
Test-ScriptBlockParam -Name {$_.Name -replace '(.*)\..*','$1'}

 
Get-ChildItem | 
Test-ScriptBlockParam -Name {
    If ($_.PSIsContainer) {
        Write-host $_ -ForegroundColor Green
    } Else {
        Write-Host $_ -ForegroundColor Yellow
    }
}

So there you go! We have created a function that allows the use of a scriptblock parameter to perform an action that still allows us to use the pipeline more efficiently rather than working with ForEach.

In Closing

Of course, these are very simple examples of what you can do, but I would love to see what you have done using this a scriptblock parameter. So feel free to drop me a comment letting me know what you have done.