From 6f87dbd187e8d126f592a6ba00623106dafcb43e Mon Sep 17 00:00:00 2001 From: Bobby Reed Date: Thu, 9 May 2019 08:56:18 -0400 Subject: [PATCH 1/2] Fixes #3014 - Clarify delay bind script blocks --- .../about_Functions_Advanced_Parameters.md | 22 ++++++----- .../About/about_Parameters.md | 16 ++++---- .../About/about_Script_Blocks.md | 37 +++++++++++++++---- .../about_Functions_Advanced_Parameters.md | 22 ++++++----- .../About/about_Parameters.md | 16 ++++---- .../About/about_Script_Blocks.md | 35 +++++++++++++++--- .../about_Functions_Advanced_Parameters.md | 22 ++++++----- .../About/about_Parameters.md | 16 ++++---- .../About/about_Script_Blocks.md | 35 +++++++++++++++--- .../about_Functions_Advanced_Parameters.md | 22 ++++++----- .../About/about_Parameters.md | 16 ++++---- .../About/about_Script_Blocks.md | 35 +++++++++++++++--- .../about_Functions_Advanced_Parameters.md | 21 ++++++----- .../About/about_Parameters.md | 16 ++++---- .../About/about_Script_Blocks.md | 35 +++++++++++++++--- 15 files changed, 251 insertions(+), 115 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index b80a58714438..928920715a10 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -250,16 +250,6 @@ Param( ) ``` -> [!NOTE] -> A parameter that accepts pipeline input (`by Value`) will enable use of -> **delay-bind** script blocks on all other parameters defined to accept -> pipeline input. The **delay-bind** script block is run automatically during -> ParameterBinding. The result is bound to the parameter. Delay binding -> does **not** work for parameters defined as type `System.Object`, the -> script block is passed through **without** being invoked. -> -> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) - ### ValueFromPipelineByPropertyName Argument The `ValueFromPipelineByPropertyName` argument indicates that the parameter @@ -283,6 +273,18 @@ Param( ) ``` +> [!NOTE] +> A typed parameter that accepts pipeline input (`by Value`) or +> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. +> +> The **delay-bind** script block is run automatically during +> **ParameterBinding**. The result is bound to the parameter. Delay binding +> does **not** work for parameters defined as type `ScriptBlock` or +> `System.Object`, the script block is passed through +> **without** being invoked. +> +> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) + ### ValueFromRemainingArguments Argument The `ValueFromRemainingArguments` argument indicates that the parameter diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md index e57e87e1affe..b5e8f2bb39c6 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Parameters.md @@ -207,14 +207,16 @@ For example, you can pipe a value to a **Name** parameter only when the value has a property called **Name**. > [!NOTE] -> A parameter that accepts pipeline input (`by Value`) will enable use of -> **delay-bind** script blocks on all other parameters defined to accept -> pipeline input. The **delay-bind** script block is run automatically -> during ParameterBinding. The result is bound to the parameter. Delay -> binding does **not** work for parameters defined as type `System.Object`, -> the script block is passed through **without** being invoked. +> A typed parameter that accepts pipeline input (`by Value`) or +> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. > -> You can read about **delay-bind** script blocks in [about_Script_Blocks](about_Script_Blocks.md). +> The **delay-bind** script block is run automatically during +> **ParameterBinding**. The result is bound to the parameter. Delay binding +> does **not** work for parameters defined as type `ScriptBlock` or +> `System.Object`, the script block is passed through +> **without** being invoked. +> +> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) #### Accepts Wildcard Characters diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md index 96fcf6b44d0a..8b8909f73702 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md @@ -138,25 +138,48 @@ For more information about the call operator, see [about_Operators](about_Operat ## Using delay-bind script blocks with parameters -A **delay-bind** script block allows you to pipe input to a given parameter, -then use script blocks for other parameters using the pipeline variable `$_` to -reference the same object. +A **delay-bind** script block allows access to the pipeline input object using +the pipeline variable `$_`. You can pass **delay-bind** script blocks to +any parameters that accept pipeline input (`by Value`) or (`by PropertyName`). ```powershell # Renames config.log to old_config.log dir config.log | Rename-Item -NewName {"old_" + $_.Name} ``` -The additional parameters must accept pipeline input -(`by Value`) or (`by PropertyName`). - In more complex cmdlets, delay-bind script blocks allow the reuse of one piped in object to populate other parameters. +Notes on **delay-bind** script blocks as parameters: + +- You must explicitly specify any parameter names you use with **delay-bind** + script blocks. +- The parameter must not be untyped, and the parameter's type cannot be + `[scriptblock]` or `[object]`. +- You receive an error if you use a **delay-bind** script block without + providing pipeline input. + + ```powershell + Rename-Item -NewName {$_.Name + ".old"} + ``` + + ```Output + Rename-Item : Cannot evaluate parameter 'NewName' because its argument is + specified as a script block and there is no input. A script block cannot + be evaluated without input. + At line:1 char:23 + + Rename-Item -NewName {$_.Name + ".old"} + + ~~~~~~~~~~~~~~~~~~ + + CategoryInfo : MetadataError: (:) [Rename-Item], + ParameterBindingException + + FullyQualifiedErrorId : ScriptBlockArgumentNoInput, + Microsoft.PowerShell.Commands.RenameItemCommand + ``` + ## See Also [about_Functions](about_Functions.md) [about_Functions_Advanced](about_Functions_Advanced.md) -[about_Operators](about_Operators.md) \ No newline at end of file +[about_Operators](about_Operators.md) diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index b80a58714438..928920715a10 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -250,16 +250,6 @@ Param( ) ``` -> [!NOTE] -> A parameter that accepts pipeline input (`by Value`) will enable use of -> **delay-bind** script blocks on all other parameters defined to accept -> pipeline input. The **delay-bind** script block is run automatically during -> ParameterBinding. The result is bound to the parameter. Delay binding -> does **not** work for parameters defined as type `System.Object`, the -> script block is passed through **without** being invoked. -> -> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) - ### ValueFromPipelineByPropertyName Argument The `ValueFromPipelineByPropertyName` argument indicates that the parameter @@ -283,6 +273,18 @@ Param( ) ``` +> [!NOTE] +> A typed parameter that accepts pipeline input (`by Value`) or +> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. +> +> The **delay-bind** script block is run automatically during +> **ParameterBinding**. The result is bound to the parameter. Delay binding +> does **not** work for parameters defined as type `ScriptBlock` or +> `System.Object`, the script block is passed through +> **without** being invoked. +> +> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) + ### ValueFromRemainingArguments Argument The `ValueFromRemainingArguments` argument indicates that the parameter diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md index e57e87e1affe..b5e8f2bb39c6 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Parameters.md @@ -207,14 +207,16 @@ For example, you can pipe a value to a **Name** parameter only when the value has a property called **Name**. > [!NOTE] -> A parameter that accepts pipeline input (`by Value`) will enable use of -> **delay-bind** script blocks on all other parameters defined to accept -> pipeline input. The **delay-bind** script block is run automatically -> during ParameterBinding. The result is bound to the parameter. Delay -> binding does **not** work for parameters defined as type `System.Object`, -> the script block is passed through **without** being invoked. +> A typed parameter that accepts pipeline input (`by Value`) or +> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. > -> You can read about **delay-bind** script blocks in [about_Script_Blocks](about_Script_Blocks.md). +> The **delay-bind** script block is run automatically during +> **ParameterBinding**. The result is bound to the parameter. Delay binding +> does **not** work for parameters defined as type `ScriptBlock` or +> `System.Object`, the script block is passed through +> **without** being invoked. +> +> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) #### Accepts Wildcard Characters diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md index 96fcf6b44d0a..efab2e556236 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md @@ -138,21 +138,44 @@ For more information about the call operator, see [about_Operators](about_Operat ## Using delay-bind script blocks with parameters -A **delay-bind** script block allows you to pipe input to a given parameter, -then use script blocks for other parameters using the pipeline variable `$_` to -reference the same object. +A **delay-bind** script block allows access to the pipeline input object using +the pipeline variable `$_`. You can pass **delay-bind** script blocks to +any parameters that accept pipeline input (`by Value`) or (`by PropertyName`). ```powershell # Renames config.log to old_config.log dir config.log | Rename-Item -NewName {"old_" + $_.Name} ``` -The additional parameters must accept pipeline input -(`by Value`) or (`by PropertyName`). - In more complex cmdlets, delay-bind script blocks allow the reuse of one piped in object to populate other parameters. +Notes on **delay-bind** script blocks as parameters: + +- You must explicitly specify any parameter names you use with **delay-bind** + script blocks. +- The parameter must not be untyped, and the parameter's type cannot be + `[scriptblock]` or `[object]`. +- You receive an error if you use a **delay-bind** script block without + providing pipeline input. + + ```powershell + Rename-Item -NewName {$_.Name + ".old"} + ``` + + ```Output + Rename-Item : Cannot evaluate parameter 'NewName' because its argument is + specified as a script block and there is no input. A script block cannot + be evaluated without input. + At line:1 char:23 + + Rename-Item -NewName {$_.Name + ".old"} + + ~~~~~~~~~~~~~~~~~~ + + CategoryInfo : MetadataError: (:) [Rename-Item], + ParameterBindingException + + FullyQualifiedErrorId : ScriptBlockArgumentNoInput, + Microsoft.PowerShell.Commands.RenameItemCommand + ``` + ## See Also [about_Functions](about_Functions.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index bf418b0ab159..b3154737a112 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -249,16 +249,6 @@ Param( ) ``` -> [!NOTE] -> A parameter that accepts pipeline input (`by Value`) will enable use of -> **delay-bind** script blocks on all other parameters defined to accept -> pipeline input. The **delay-bind** script block is run automatically during -> ParameterBinding. The result is bound to the parameter. Delay binding -> does **not** work for parameters defined as type `System.Object`, the -> script block is passed through **without** being invoked. -> -> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) - ### ValueFromPipelineByPropertyName Argument The `ValueFromPipelineByPropertyName` argument indicates that the parameter @@ -282,6 +272,18 @@ Param( ) ``` +> [!NOTE] +> A typed parameter that accepts pipeline input (`by Value`) or +> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. +> +> The **delay-bind** script block is run automatically during +> **ParameterBinding**. The result is bound to the parameter. Delay binding +> does **not** work for parameters defined as type `ScriptBlock` or +> `System.Object`, the script block is passed through +> **without** being invoked. +> +> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) + ### ValueFromRemainingArguments Argument The `ValueFromRemainingArguments` argument indicates that the parameter diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters.md index e57e87e1affe..b5e8f2bb39c6 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Parameters.md @@ -207,14 +207,16 @@ For example, you can pipe a value to a **Name** parameter only when the value has a property called **Name**. > [!NOTE] -> A parameter that accepts pipeline input (`by Value`) will enable use of -> **delay-bind** script blocks on all other parameters defined to accept -> pipeline input. The **delay-bind** script block is run automatically -> during ParameterBinding. The result is bound to the parameter. Delay -> binding does **not** work for parameters defined as type `System.Object`, -> the script block is passed through **without** being invoked. +> A typed parameter that accepts pipeline input (`by Value`) or +> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. > -> You can read about **delay-bind** script blocks in [about_Script_Blocks](about_Script_Blocks.md). +> The **delay-bind** script block is run automatically during +> **ParameterBinding**. The result is bound to the parameter. Delay binding +> does **not** work for parameters defined as type `ScriptBlock` or +> `System.Object`, the script block is passed through +> **without** being invoked. +> +> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) #### Accepts Wildcard Characters diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md index 2f7a0b6e59be..2748a020d907 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md @@ -137,21 +137,44 @@ For more information about the call operator, see [about_Operators](about_Operat ## Using delay-bind script blocks with parameters -A **delay-bind** script block allows you to pipe input to a given parameter, -then use script blocks for other parameters using the pipeline variable `$_` to -reference the same object. +A **delay-bind** script block allows access to the pipeline input object using +the pipeline variable `$_`. You can pass **delay-bind** script blocks to +any parameters that accept pipeline input (`by Value`) or (`by PropertyName`). ```powershell # Renames config.log to old_config.log dir config.log | Rename-Item -NewName {"old_" + $_.Name} ``` -The additional parameters must accept pipeline input -(`by Value`) or (`by PropertyName`). - In more complex cmdlets, delay-bind script blocks allow the reuse of one piped in object to populate other parameters. +Notes on **delay-bind** script blocks as parameters: + +- You must explicitly specify any parameter names you use with **delay-bind** + script blocks. +- The parameter must not be untyped, and the parameter's type cannot be + `[scriptblock]` or `[object]`. +- You receive an error if you use a **delay-bind** script block without + providing pipeline input. + + ```powershell + Rename-Item -NewName {$_.Name + ".old"} + ``` + + ```Output + Rename-Item : Cannot evaluate parameter 'NewName' because its argument is + specified as a script block and there is no input. A script block cannot + be evaluated without input. + At line:1 char:23 + + Rename-Item -NewName {$_.Name + ".old"} + + ~~~~~~~~~~~~~~~~~~ + + CategoryInfo : MetadataError: (:) [Rename-Item], + ParameterBindingException + + FullyQualifiedErrorId : ScriptBlockArgumentNoInput, + Microsoft.PowerShell.Commands.RenameItemCommand + ``` + ## See Also [about_Functions](about_Functions.md) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index c7bc534cd381..acbdc70a1ae1 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -250,16 +250,6 @@ Param( ) ``` -> [!NOTE] -> A parameter that accepts pipeline input (`by Value`) will enable use of -> **delay-bind** script blocks on all other parameters defined to accept -> pipeline input. The **delay-bind** script block is run automatically during -> ParameterBinding. The result is bound to the parameter. Delay binding -> does **not** work for parameters defined as type `System.Object`, the -> script block is passed through **without** being invoked. -> -> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) - ### ValueFromPipelineByPropertyName Argument The `ValueFromPipelineByPropertyName` argument indicates that the parameter @@ -283,6 +273,18 @@ Param( ) ``` +> [!NOTE] +> A typed parameter that accepts pipeline input (`by Value`) or +> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. +> +> The **delay-bind** script block is run automatically during +> **ParameterBinding**. The result is bound to the parameter. Delay binding +> does **not** work for parameters defined as type `ScriptBlock` or +> `System.Object`, the script block is passed through +> **without** being invoked. +> +> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) + ### ValueFromRemainingArguments Argument The `ValueFromRemainingArguments` argument indicates that the parameter diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters.md index e57e87e1affe..b5e8f2bb39c6 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parameters.md @@ -207,14 +207,16 @@ For example, you can pipe a value to a **Name** parameter only when the value has a property called **Name**. > [!NOTE] -> A parameter that accepts pipeline input (`by Value`) will enable use of -> **delay-bind** script blocks on all other parameters defined to accept -> pipeline input. The **delay-bind** script block is run automatically -> during ParameterBinding. The result is bound to the parameter. Delay -> binding does **not** work for parameters defined as type `System.Object`, -> the script block is passed through **without** being invoked. +> A typed parameter that accepts pipeline input (`by Value`) or +> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. > -> You can read about **delay-bind** script blocks in [about_Script_Blocks](about_Script_Blocks.md). +> The **delay-bind** script block is run automatically during +> **ParameterBinding**. The result is bound to the parameter. Delay binding +> does **not** work for parameters defined as type `ScriptBlock` or +> `System.Object`, the script block is passed through +> **without** being invoked. +> +> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) #### Accepts Wildcard Characters diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Blocks.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Blocks.md index 96fcf6b44d0a..efab2e556236 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Blocks.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Blocks.md @@ -138,21 +138,44 @@ For more information about the call operator, see [about_Operators](about_Operat ## Using delay-bind script blocks with parameters -A **delay-bind** script block allows you to pipe input to a given parameter, -then use script blocks for other parameters using the pipeline variable `$_` to -reference the same object. +A **delay-bind** script block allows access to the pipeline input object using +the pipeline variable `$_`. You can pass **delay-bind** script blocks to +any parameters that accept pipeline input (`by Value`) or (`by PropertyName`). ```powershell # Renames config.log to old_config.log dir config.log | Rename-Item -NewName {"old_" + $_.Name} ``` -The additional parameters must accept pipeline input -(`by Value`) or (`by PropertyName`). - In more complex cmdlets, delay-bind script blocks allow the reuse of one piped in object to populate other parameters. +Notes on **delay-bind** script blocks as parameters: + +- You must explicitly specify any parameter names you use with **delay-bind** + script blocks. +- The parameter must not be untyped, and the parameter's type cannot be + `[scriptblock]` or `[object]`. +- You receive an error if you use a **delay-bind** script block without + providing pipeline input. + + ```powershell + Rename-Item -NewName {$_.Name + ".old"} + ``` + + ```Output + Rename-Item : Cannot evaluate parameter 'NewName' because its argument is + specified as a script block and there is no input. A script block cannot + be evaluated without input. + At line:1 char:23 + + Rename-Item -NewName {$_.Name + ".old"} + + ~~~~~~~~~~~~~~~~~~ + + CategoryInfo : MetadataError: (:) [Rename-Item], + ParameterBindingException + + FullyQualifiedErrorId : ScriptBlockArgumentNoInput, + Microsoft.PowerShell.Commands.RenameItemCommand + ``` + ## See Also [about_Functions](about_Functions.md) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md b/reference/6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md index e873a84ccdbb..3cd571c01df3 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Functions_Advanced_Parameters.md @@ -249,15 +249,6 @@ Param( ) ``` -> [!NOTE] -> A parameter that accepts pipeline input (`by Value`) enables you to use **delay-bind** script blocks on all other parameters defined to accept -> pipeline input. The **delay-bind** script block is run automatically during -> ParameterBinding. The result is bound to the parameter. Delay binding -> does **not** work for parameters defined as type `System.Object`, the -> script block is passed through **without** being invoked. -> -> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) - ### ValueFromPipelineByPropertyName Argument The `ValueFromPipelineByPropertyName` argument indicates that the parameter @@ -281,6 +272,18 @@ Param( ) ``` +> [!NOTE] +> A typed parameter that accepts pipeline input (`by Value`) or +> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. +> +> The **delay-bind** script block is run automatically during +> **ParameterBinding**. The result is bound to the parameter. Delay binding +> does **not** work for parameters defined as type `ScriptBlock` or +> `System.Object`, the script block is passed through +> **without** being invoked. +> +> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) + ### ValueFromRemainingArguments Argument The `ValueFromRemainingArguments` argument indicates that the parameter diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Parameters.md b/reference/6/Microsoft.PowerShell.Core/About/about_Parameters.md index 409fa7943fd6..6d4db05db31a 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Parameters.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Parameters.md @@ -207,14 +207,16 @@ For example, you can pipe a value to a **Name** parameter only when the value has a property called **Name**. > [!NOTE] -> A parameter that accepts pipeline input (`by Value`) will enable use of -> **delay-bind** script blocks on all other parameters defined to accept -> pipeline input. The **delay-bind** script block is run automatically -> during ParameterBinding. The result is bound to the parameter. Delay -> binding does **not** work for parameters defined as type `System.Object`, -> the script block is passed through **without** being invoked. +> A typed parameter that accepts pipeline input (`by Value`) or +> (`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. > -> You can read about **delay-bind** script blocks in [about_Script_Blocks](about_Script_Blocks.md). +> The **delay-bind** script block is run automatically during +> **ParameterBinding**. The result is bound to the parameter. Delay binding +> does **not** work for parameters defined as type `ScriptBlock` or +> `System.Object`, the script block is passed through +> **without** being invoked. +> +> You can read about **delay-bind** script blocks here [about_Script_Blocks.md](about_Script_Blocks.md) #### Accepts Wildcard Characters diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Script_Blocks.md b/reference/6/Microsoft.PowerShell.Core/About/about_Script_Blocks.md index 2f7a0b6e59be..2748a020d907 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Script_Blocks.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Script_Blocks.md @@ -137,21 +137,44 @@ For more information about the call operator, see [about_Operators](about_Operat ## Using delay-bind script blocks with parameters -A **delay-bind** script block allows you to pipe input to a given parameter, -then use script blocks for other parameters using the pipeline variable `$_` to -reference the same object. +A **delay-bind** script block allows access to the pipeline input object using +the pipeline variable `$_`. You can pass **delay-bind** script blocks to +any parameters that accept pipeline input (`by Value`) or (`by PropertyName`). ```powershell # Renames config.log to old_config.log dir config.log | Rename-Item -NewName {"old_" + $_.Name} ``` -The additional parameters must accept pipeline input -(`by Value`) or (`by PropertyName`). - In more complex cmdlets, delay-bind script blocks allow the reuse of one piped in object to populate other parameters. +Notes on **delay-bind** script blocks as parameters: + +- You must explicitly specify any parameter names you use with **delay-bind** + script blocks. +- The parameter must not be untyped, and the parameter's type cannot be + `[scriptblock]` or `[object]`. +- You receive an error if you use a **delay-bind** script block without + providing pipeline input. + + ```powershell + Rename-Item -NewName {$_.Name + ".old"} + ``` + + ```Output + Rename-Item : Cannot evaluate parameter 'NewName' because its argument is + specified as a script block and there is no input. A script block cannot + be evaluated without input. + At line:1 char:23 + + Rename-Item -NewName {$_.Name + ".old"} + + ~~~~~~~~~~~~~~~~~~ + + CategoryInfo : MetadataError: (:) [Rename-Item], + ParameterBindingException + + FullyQualifiedErrorId : ScriptBlockArgumentNoInput, + Microsoft.PowerShell.Commands.RenameItemCommand + ``` + ## See Also [about_Functions](about_Functions.md) From 6ba728a7534d5efa3b554282cd774847d9fa45ec Mon Sep 17 00:00:00 2001 From: Bobby Reed Date: Thu, 9 May 2019 12:17:36 -0400 Subject: [PATCH 2/2] Editorial review --- .../About/about_Script_Blocks.md | 7 ++++--- .../About/about_Script_Blocks.md | 10 +++++----- .../About/about_Script_Blocks.md | 7 ++++--- .../About/about_Script_Blocks.md | 8 ++++---- .../About/about_Script_Blocks.md | 7 ++++--- 5 files changed, 21 insertions(+), 18 deletions(-) diff --git a/reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md b/reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md index 8b8909f73702..4d83aedaa530 100644 --- a/reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md +++ b/reference/3.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md @@ -138,9 +138,10 @@ For more information about the call operator, see [about_Operators](about_Operat ## Using delay-bind script blocks with parameters -A **delay-bind** script block allows access to the pipeline input object using -the pipeline variable `$_`. You can pass **delay-bind** script blocks to -any parameters that accept pipeline input (`by Value`) or (`by PropertyName`). +A typed parameter that accepts pipeline input (`by Value`) or +(`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. +Within the **delay-bind** script block, you can reference the piped in object +using the pipeline variable `$_`. ```powershell # Renames config.log to old_config.log diff --git a/reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md b/reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md index efab2e556236..3dadff9759bb 100644 --- a/reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md +++ b/reference/4.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md @@ -8,7 +8,6 @@ title: about_Script_Blocks # About Script Blocks ## Short description - Defines what a script block is and explains how to use script blocks in the PowerShell programming language. @@ -138,9 +137,10 @@ For more information about the call operator, see [about_Operators](about_Operat ## Using delay-bind script blocks with parameters -A **delay-bind** script block allows access to the pipeline input object using -the pipeline variable `$_`. You can pass **delay-bind** script blocks to -any parameters that accept pipeline input (`by Value`) or (`by PropertyName`). +A typed parameter that accepts pipeline input (`by Value`) or +(`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. +Within the **delay-bind** script block, you can reference the piped in object +using the pipeline variable `$_`. ```powershell # Renames config.log to old_config.log @@ -182,4 +182,4 @@ Notes on **delay-bind** script blocks as parameters: [about_Functions_Advanced](about_Functions_Advanced.md) -[about_Operators](about_Operators.md) \ No newline at end of file +[about_Operators](about_Operators.md) diff --git a/reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md b/reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md index 2748a020d907..7728f9ba5405 100644 --- a/reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md +++ b/reference/5.0/Microsoft.PowerShell.Core/About/about_Script_Blocks.md @@ -137,9 +137,10 @@ For more information about the call operator, see [about_Operators](about_Operat ## Using delay-bind script blocks with parameters -A **delay-bind** script block allows access to the pipeline input object using -the pipeline variable `$_`. You can pass **delay-bind** script blocks to -any parameters that accept pipeline input (`by Value`) or (`by PropertyName`). +A typed parameter that accepts pipeline input (`by Value`) or +(`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. +Within the **delay-bind** script block, you can reference the piped in object +using the pipeline variable `$_`. ```powershell # Renames config.log to old_config.log diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Blocks.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Blocks.md index efab2e556236..7728f9ba5405 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Blocks.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Script_Blocks.md @@ -8,7 +8,6 @@ title: about_Script_Blocks # About Script Blocks ## Short description - Defines what a script block is and explains how to use script blocks in the PowerShell programming language. @@ -138,9 +137,10 @@ For more information about the call operator, see [about_Operators](about_Operat ## Using delay-bind script blocks with parameters -A **delay-bind** script block allows access to the pipeline input object using -the pipeline variable `$_`. You can pass **delay-bind** script blocks to -any parameters that accept pipeline input (`by Value`) or (`by PropertyName`). +A typed parameter that accepts pipeline input (`by Value`) or +(`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. +Within the **delay-bind** script block, you can reference the piped in object +using the pipeline variable `$_`. ```powershell # Renames config.log to old_config.log diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Script_Blocks.md b/reference/6/Microsoft.PowerShell.Core/About/about_Script_Blocks.md index 2748a020d907..7728f9ba5405 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Script_Blocks.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Script_Blocks.md @@ -137,9 +137,10 @@ For more information about the call operator, see [about_Operators](about_Operat ## Using delay-bind script blocks with parameters -A **delay-bind** script block allows access to the pipeline input object using -the pipeline variable `$_`. You can pass **delay-bind** script blocks to -any parameters that accept pipeline input (`by Value`) or (`by PropertyName`). +A typed parameter that accepts pipeline input (`by Value`) or +(`by PropertyName`) enables use of **delay-bind** script blocks on the parameter. +Within the **delay-bind** script block, you can reference the piped in object +using the pipeline variable `$_`. ```powershell # Renames config.log to old_config.log