issue 4913 (#4953)

davidsmatlak · sdwheeler · commit d0caf6bbca95 · 2019-10-17T18:12:53.000-07:00
diff --git a/reference/5.1/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/5.1/Microsoft.PowerShell.Core/Invoke-Command.md
@@ -3,7 +3,7 @@ external help file: System.Management.Automation.dll-Help.xml
 keywords: powershell,cmdlet
 locale: en-us
 Module Name: Microsoft.PowerShell.Core
-ms.date: 08/20/2019
+ms.date: 10/17/2019
 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/invoke-command?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Invoke-Command
@@ -393,7 +393,69 @@ process. The output of the first command includes the **PsComputerName** propert
 the name of the computer on which the command ran. The output of the second command, which uses
 **HideComputerName**, doesn't include the **PsComputerName** column.
 
-### Example 11: Run a script on all the computers listed in a text file
+### Example 11: Use the Param keyword in a script block
+
+The `Param` keyword and the **ArgumentList** parameter are used to pass variable values to named
+parameters in a script block. This example displays file names that begin with the letter `a` and
+have the `.pdf` extension.
+
+For more information about the `Param` keyword, see
+[about_Language_Keywords](./about/about_language_keywords.md#param).
+
+```powershell
+$parameters = @{
+    ComputerName = "Server01"
+    ScriptBlock = { Param ($param1,$param2) Get-ChildItem -Name $param1 -Include $param2 }
+    ArgumentList = "a*", "*.pdf"
+}
+Invoke-Command @parameters
+```
+
+```Output
+aa.pdf
+ab.pdf
+ac.pdf
+az.pdf
+```
+
+`Invoke-Command` uses the **ScriptBlock** parameter that defines two variables, `$param1` and
+`$param2`. `Get-ChildItem` uses the named parameters, **Name** and **Include** with the variable
+names. The **ArgumentList** passes the values to the variables.
+
+### Example 12: Use the $args automatic variable in a script block
+
+The `$args` automatic variable and the **ArgumentList** parameter are used to pass array values to
+parameter positions in a script block. This example displays a server's directory contents of `.txt`
+files. The `Get-ChildItem` **Path** parameter is position 0 and the **Filter** parameter is position
+1.
+
+For more information about the `$args` variable, see
+[about_Automatic_Variables](./about/about_automatic_variables.md#args)
+
+```powershell
+$parameters = @{
+    ComputerName = "Server01"
+    ScriptBlock = { Get-ChildItem $args[0] $args[1] }
+    ArgumentList = "C:\Test", "*.txt*"
+}
+Invoke-Command @parameters
+```
+
+```Output
+    Directory: C:\Test
+
+Mode                 LastWriteTime         Length Name
+----                 -------------         ------ ----
+-a---           6/12/2019    15:15            128 alog.txt
+-a---           7/27/2019    15:16            256 blog.txt
+-a---           9/28/2019    17:10             64 zlog.txt
+```
+
+`Invoke-Command` uses a **ScriptBlock** parameter and `Get-ChildItem` specifies the `$args[0]` and
+`$args[1]` array values. The **ArgumentList** passes the `$args` array values to the `Get-ChildItem`
+parameter positions for **Path** and **Filter**.
+
+### Example 13: Run a script on all the computers listed in a text file
 
 This example uses the `Invoke-Command` cmdlet to run the `Sample.ps1` script on all the computers
 listed in the `Servers.txt` file. The command uses the **FilePath** parameter to specify the script
@@ -408,7 +470,7 @@ When you submit the command, the content of the `Sample.ps1` file is copied into
 the script block is run on each of the remote computers. This procedure is equivalent to using the
 **ScriptBlock** parameter to submit the contents of the script.
 
-### Example 12: Run a command on a remote computer by using a URI
+### Example 14: Run a command on a remote computer by using a URI
 
 This example shows how to run a command on a remote computer that's identified by a Uniform Resource
 Identifier (URI). This particular example runs a `Set-Mailbox` command on a remote Exchange server.
@@ -435,7 +497,7 @@ the Exchange server endpoint. The **Credential** parameter specifies the credent
 `$LiveCred` variable. The **AuthenticationMechanism** parameter specifies the use of basic
 authentication. The **ScriptBlock** parameter specifies a script block that contains the command.
 
-### Example 13: Use a session option
+### Example 15: Use a session option
 
 This example shows how to create and use a **SessionOption** parameter.
 
@@ -454,7 +516,7 @@ HTTPS connection. The **SessionOption** object is saved in the `$so` variable.
 The `Invoke-Command` cmdlet runs a `Get-HotFix` command remotely. The **SessionOption** parameter is
 given the `$so` variable.
 
-### Example 14: Manage URI redirection in a remote command
+### Example 16: Manage URI redirection in a remote command
 
 This example shows how to use the **AllowRedirection** and **SessionOption** parameters to manage
 URI redirection in a remote command.
@@ -483,7 +545,7 @@ As a result, if the remote computer specified by **ConnectionURI** returns a red
 PowerShell redirects the connection, but if the new destination returns another redirection message,
 the redirection count value of 1 is exceeded, and `Invoke-Command` returns a non-terminating error.
 
-### Example 15: Access a network share in a remote session
+### Example 17: Access a network share in a remote session
 
 This example shows how to access a network share from a remote session. Three computers are used to
 demonstrate the example. Server01 is the local computer, Server02 is the remote computer, and Net03
@@ -526,7 +588,7 @@ The `$parameters` variable contains the parameter values to connect to the netwo
 from the `\\Net03\Scripts` network share. The command uses the **Authentication** parameter with a
 value of **CredSSP** and the **Credential** parameter with a value of **Domain01\Admin01**.
 
-### Example 16: Start scripts on many remote computers
+### Example 18: Start scripts on many remote computers
 
 This example runs a script on more than a hundred computers. To minimize the impact on the local
 computer, it connects to each computer, starts the script, and then disconnects from each computer.
diff --git a/reference/6/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/6/Microsoft.PowerShell.Core/Invoke-Command.md
@@ -3,7 +3,7 @@ external help file: System.Management.Automation.dll-Help.xml
 keywords: powershell,cmdlet
 locale: en-us
 Module Name: Microsoft.PowerShell.Core
-ms.date: 08/20/2019
+ms.date: 10/17/2019
 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/invoke-command?view=powershell-6&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: Invoke-Command
@@ -434,7 +434,69 @@ process. The output of the first command includes the **PsComputerName** propert
 the name of the computer on which the command ran. The output of the second command, which uses
 **HideComputerName**, doesn't include the **PsComputerName** column.
 
-### Example 11: Run a script on all the computers listed in a text file
+### Example 11: Use the Param keyword in a script block
+
+The `Param` keyword and the **ArgumentList** parameter are used to pass variable values to named
+parameters in a script block. This example displays file names that begin with the letter `a` and
+have the `.pdf` extension.
+
+For more information about the `Param` keyword, see
+[about_Language_Keywords](./about/about_language_keywords.md#param).
+
+```powershell
+$parameters = @{
+    ComputerName = "Server01"
+    ScriptBlock = { Param ($param1,$param2) Get-ChildItem -Name $param1 -Include $param2 }
+    ArgumentList = "a*", "*.pdf"
+}
+Invoke-Command @parameters
+```
+
+```Output
+aa.pdf
+ab.pdf
+ac.pdf
+az.pdf
+```
+
+`Invoke-Command` uses the **ScriptBlock** parameter that defines two variables, `$param1` and
+`$param2`. `Get-ChildItem` uses the named parameters, **Name** and **Include** with the variable
+names. The **ArgumentList** passes the values to the variables.
+
+### Example 12: Use the $args automatic variable in a script block
+
+The `$args` automatic variable and the **ArgumentList** parameter are used to pass array values to
+parameter positions in a script block. This example displays a server's directory contents of `.txt`
+files. The `Get-ChildItem` **Path** parameter is position 0 and the **Filter** parameter is position
+1.
+
+For more information about the `$args` variable, see
+[about_Automatic_Variables](./about/about_automatic_variables.md#args)
+
+```powershell
+$parameters = @{
+    ComputerName = "Server01"
+    ScriptBlock = { Get-ChildItem $args[0] $args[1] }
+    ArgumentList = "C:\Test", "*.txt*"
+}
+Invoke-Command @parameters
+```
+
+```Output
+    Directory: C:\Test
+
+Mode                 LastWriteTime         Length Name
+----                 -------------         ------ ----
+-a---           6/12/2019    15:15            128 alog.txt
+-a---           7/27/2019    15:16            256 blog.txt
+-a---           9/28/2019    17:10             64 zlog.txt
+```
+
+`Invoke-Command` uses a **ScriptBlock** parameter and `Get-ChildItem` specifies the `$args[0]` and
+`$args[1]` array values. The **ArgumentList** passes the `$args` array values to the `Get-ChildItem`
+parameter positions for **Path** and **Filter**.
+
+### Example 13: Run a script on all the computers listed in a text file
 
 This example uses the `Invoke-Command` cmdlet to run the `Sample.ps1` script on all the computers
 listed in the `Servers.txt` file. The command uses the **FilePath** parameter to specify the script
@@ -449,7 +511,7 @@ When you submit the command, the content of the `Sample.ps1` file is copied into
 the script block is run on each of the remote computers. This procedure is equivalent to using the
 **ScriptBlock** parameter to submit the contents of the script.
 
-### Example 12: Run a command on a remote computer by using a URI
+### Example 14: Run a command on a remote computer by using a URI
 
 This example shows how to run a command on a remote computer that's identified by a Uniform Resource
 Identifier (URI). This particular example runs a `Set-Mailbox` command on a remote Exchange server.
@@ -476,7 +538,7 @@ the Exchange server endpoint. The **Credential** parameter specifies the credent
 `$LiveCred` variable. The **AuthenticationMechanism** parameter specifies the use of basic
 authentication. The **ScriptBlock** parameter specifies a script block that contains the command.
 
-### Example 13: Use a session option
+### Example 15: Use a session option
 
 This example shows how to create and use a **SessionOption** parameter.
 
@@ -495,7 +557,7 @@ HTTPS connection. The **SessionOption** object is saved in the `$so` variable.
 The `Invoke-Command` cmdlet runs a `Get-HotFix` command remotely. The **SessionOption** parameter is
 given the `$so` variable.
 
-### Example 14: Manage URI redirection in a remote command
+### Example 16: Manage URI redirection in a remote command
 
 This example shows how to use the **AllowRedirection** and **SessionOption** parameters to manage
 URI redirection in a remote command.
@@ -524,7 +586,7 @@ As a result, if the remote computer specified by **ConnectionURI** returns a red
 PowerShell redirects the connection, but if the new destination returns another redirection message,
 the redirection count value of 1 is exceeded, and `Invoke-Command` returns a non-terminating error.
 
-### Example 15: Access a network share in a remote session
+### Example 17: Access a network share in a remote session
 
 This example shows how to access a network share from a remote session. Three computers are used to
 demonstrate the example. Server01 is the local computer, Server02 is the remote computer, and Net03
@@ -567,7 +629,7 @@ The `$parameters` variable contains the parameter values to connect to the netwo
 from the `\\Net03\Scripts` network share. The command uses the **Authentication** parameter with a
 value of **CredSSP** and the **Credential** parameter with a value of **Domain01\Admin01**.
 
-### Example 16: Start scripts on many remote computers
+### Example 18: Start scripts on many remote computers
 
 This example runs a script on more than a hundred computers. To minimize the impact on the local
 computer, it connects to each computer, starts the script, and then disconnects from each computer.
@@ -594,7 +656,7 @@ and the **IdleTimeout** value is set to **43200000** milliseconds (12 hours).
 To get the results of commands and scripts that run in disconnected sessions, use the
 `Receive-PSSession` cmdlet.
 
-### Example 17: Run a command on a remote computer using SSH
+### Example 19: Run a command on a remote computer using SSH
 
 This example shows how to run a command on a remote computer using Secure Shell (SSH). If SSH is
 configured on the remote computer to prompt for passwords, then you'll get a password prompt.
@@ -604,7 +666,7 @@ Otherwise, you'll have to use SSH key-based user authentication.
 Invoke-Command -HostName UserA@LinuxServer01 -ScriptBlock { Get-MailBox * }
 ```
 
-### Example 18: Run a command on a remote computer using SSH and specify a user authentication key
+### Example 20: Run a command on a remote computer using SSH and specify a user authentication key
 
 This example shows how to run a command on a remote computer using SSH and specifying a key file for
 user authentication. You won't be prompted for a password unless the key authentication fails and
@@ -614,7 +676,7 @@ the remote computer is configured to allow basic password authentication.
 Invoke-Command -HostName UserA@LinuxServer01 -ScriptBlock { Get-MailBox * } -KeyFilePath /UserA/UserAKey_rsa
 ```
 
-### Example 19: Run a script file on multiple remote computers using SSH as a job
+### Example 21: Run a script file on multiple remote computers using SSH as a job
 
 This example shows how to run a script file on multiple remote computers using SSH and the
 **SSHConnection** parameter set. The **SSHConnection** parameter takes an array of hash tables that
diff --git a/reference/7/Microsoft.PowerShell.Core/Invoke-Command.md b/reference/7/Microsoft.PowerShell.Core/Invoke-Command.md
