For PowerShell cmdlets, can I always pass a script block to a string parameter?

Question

I'm looking at the documentation of PowerShell's Rename-Item cmdlet and there is an example like this.

Get-ChildItem *.txt | Rename-Item -NewName { $_.name -Replace '\.txt','.log' }

This example shows how to use the Replace operator to rename multiple files, even though the NewName parameter does not accept wildcard characters.

This command renames all of the .txt files in the current directory to .log.

The command uses the Get-ChildItem cmdlet to get all of the files in the current folder that have a .txt file name extension. Then, it uses the pipeline operator (|) to send those files to Rename-Item .

The value of NewName is a script block that runs before the value is submitted to the NewName parameter.

Note the last sentence:

The value of NewName is a script block that runs before the value is submitted to the NewName parameter.

Actually NewName is a string:

[-NewName] <String>

So does that means I can always use a script block when the required parameter type is a string?

Cluck

Ogrish Man - as long as the order of operations puts the item before the parameter is triggered, the item can be almost anything that results in a string. you can also use $(<something to evaluate>) in that situation. – Pestiferous

In short: you can use a script block if the parameter is designed to accept pipeline input and is not itself of type [scriptblock] or [object] / untyped. – Bentwood

@Lee_Dailey: delayed script-block binding is different from the regular parameter binding you describe. If regular binding applied, a script block would bind once, by its literal contents. – Bentwood

Answer 1

# Delay-bind script-block argument:
# The code inside { ... } is executed for each input object ($_) and
# the output is passed to the -NewName parameter.
... | Rename-Item -NewName { $_.Name -replace '\.txt$','.log' }

The call above shows an application of a delay-bind script-block ({ ... }) argument, which is an implicit feature that:

• only works with parameters that are designed to take pipeline input,

  • of any type except the following, in which case regular parameter binding happens^[1]:

    • [scriptblock]
    • [object] ([psobject], however, does work, and therefore the equivalent [pscustomobject] too)
    • (no type specified), which is effectively the same as [object]

  • Whether such parameters accept pipeline input by value (ValueFromPipeline) or by property name (ValueFromPipelineByPropertyName), is irrelevant.

  • See this answer for how to discover a given cmdlet's pipeline-binding parameters; in the simplest case, e.g.:

    Get-Help Rename-Item -Parameter * | Where pipelineInput -like True*
    

• enables per-input-object transformations via a script block passed instead of a type-appropriate argument; the script block is evaluated for each pipeline object, which is accessible inside the script block as $_, as usual, and the script block's output - which is assumed to be type-appropriate for the parameter - is used as the argument.

  • Since such ad-hoc script blocks by definition do not match the type of the parameter you're targeting, you must always use the parameter name explicitly when passing them.

  • Delay-bind script blocks unconditionally provide access to the pipeline input objects, even if the parameter would ordinarily not be bound by a given pipeline object, if it is defined as ValueFromPipelineByPropertyName and the object lacks a property by that name.

  • This enables techniques such as the following call to Rename-Item, where the pipeline input from Get-Item is - as usual - bound to the -LiteralPath parameter, but passing a script block to -NewName - which would ordinarily only bind to input objects with a .NewName property - enables access to the same pipeline object and thus deriving the destination filename from the input filename:

    • Get-Item file | Rename-Item -NewName { $_.Name + '1' } # renames 'file' to 'file1'; input binds to both -LiteralPath (implicitly) and the -NewName script block.

  • Note: Unlike script blocks passed to ForEach-Object or Where-Object, for example, delay-bind script blocks run in a child variable scope^[2], which means that you cannot directly modify the caller's variables, such as incrementing a counter across input objects.
    As a workaround, use Get-Variable to gain access to a caller's variable and access its .Value property inside the script block - see this answer for an example.

---

[1] Error conditions:

• If you mistakenly attempt to pass a script block to a parameter that is either not pipeline-binding or is [scriptblock]- or [object]-typed (untyped), regular parameter-binding occurs:

  • The script block is passed once, before pipeline-input processing begins, if any.
    That is, the script block is passed as a (possibly converted) value, and no evaluation happens.
    • For parameters of type [object] or [scriptblock] / a delegate type such as System.Func that is convertible to a script block, the script block will bind as-is.
    • In the case of a (non-pipeline-binding) [string]-typed parameter, the script block's literal contents is passed as the string value.
    • For all other types, parameter binding - and therefore the command as a whole - will simply fail, since conversion from a script block is not possible.

• If you neglect to provide pipeline input while passing a delay-bind script block to a pipeline-binding parameter that does support them, you'll get the following error:

  • Cannot evaluate parameter '<name>' because its argument is specified as a script block and there is no input. A script block cannot be evaluated without input.

---

^{[2] This discrepancy is being discussed in GitHub issue #7157.}

Bentwood

It is good that this feature is finally documented, but it is still hard to discover because of its implicit nature. I've just created a GitHub issue suggesting to improve upon its discoverability. – Bernina

This is still such a heard concept for me to understand. – Monostich

@AbrahamZinala: Yes, it isn't trivial, but it's a technique worth adding to one's tool belt, because it enables solutions that are both more concise and more efficient. – Bentwood

Answer 2

So does that means I can always use a script block when the required parameter type is a string? : NO

Here the technique is called Delay Binding, which is very useful this scenario.

What happens when you do delay binding ?

PowerShell ParameteBinder will understand the usage of delay binding and will execute the ScriptBlock first and the output is then converted to respective parameter's expected type, here it is string.

Below is an example.

#Working one
'Path'|Join-Path -Path {$_} -ChildPath 'File'  

#Not working one
Join-Path -Path {'path'} -ChildPath 'File'
Join-Path : Cannot evaluate parameter 'Path' because its argument is specified as a script block and there is no input. A script block cannot be evaluated without input.

To know more about ParameterBinding, you can do a Trace-Command like below.

Trace-Command ParameterBinding -Expression {'Path'|Join-Path -Path {$_} -ChildPath 'File'} -PSHost

Collum

Answer 3

With Delay Binding, the parameter can receive a value from the pipeline using a scriptblock instead of the actual data type of the parameter.

In the scriptblock, $_ stands for the piped value.

It is only available when there is input coming on the pipeline.

Georgeta