Invoke-Command

Syntax

Invoke-Command
      [-ScriptBlock] <scriptblock>
      [-NoNewScope]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [[-Session] <PSSession[]>]
      [-ScriptBlock] <scriptblock>
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <string>]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [[-Session] <PSSession[]>]
      [-FilePath] <string>
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <string>]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [[-ComputerName] <string[]>]
      [-ScriptBlock] <scriptblock>
      [-Credential <pscredential>]
      [-Port <int>]
      [-UseSSL]
      [-ConfigurationName <string>]
      [-ApplicationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-InDisconnectedSession]
      [-SessionName <string[]>]
      [-HideComputerName]
      [-JobName <string>]
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [-CertificateThumbprint <string>]
      [<CommonParameters>]

Invoke-Command
      [[-ComputerName] <string[]>]
      [-FilePath] <string>
      [-Credential <pscredential>]
      [-Port <int>]
      [-UseSSL]
      [-ConfigurationName <string>]
      [-ApplicationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-InDisconnectedSession]
      [-SessionName <string[]>]
      [-HideComputerName]
      [-JobName <string>]
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [[-ConnectionUri] <uri[]>]
      [-ScriptBlock] <scriptblock>
      [-Credential <pscredential>]
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-InDisconnectedSession]
      [-HideComputerName]
      [-JobName <string>]
      [-AllowRedirection]
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [-CertificateThumbprint <string>]
      [<CommonParameters>]

Invoke-Command
      [[-ConnectionUri] <uri[]>]
      [-FilePath] <string>
      [-Credential <pscredential>]
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-InDisconnectedSession]
      [-HideComputerName]
      [-JobName <string>]
      [-AllowRedirection]
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-VMId] <guid[]>
      [-ScriptBlock] <scriptblock>
      -Credential <pscredential>
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-ScriptBlock] <scriptblock>
      -Credential <pscredential>
      -VMName <string[]>
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-VMId] <guid[]>
      [-FilePath] <string>
      -Credential <pscredential>
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-FilePath] <string>
      -Credential <pscredential>
      -VMName <string[]>
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-ScriptBlock] <scriptblock>
      -HostName <string[]>
      [-Port <int>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <string>]
      [-UserName <string>]
      [-KeyFilePath <string>]
      [-Subsystem <string>]
      [-ConnectingTimeout <int>]
      [-SSHTransport]
      [-Options <hashtable>]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-ScriptBlock] <scriptblock>
      -ContainerId <string[]>
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <string>]
      [-RunAsAdministrator]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-FilePath] <string>
      -ContainerId <string[]>
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <string>]
      [-RunAsAdministrator]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-ScriptBlock] <scriptblock>
      -SSHConnection <hashtable[]>
      [-AsJob]
      [-HideComputerName]
      [-JobName <string>]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      -FilePath <string>
      -HostName <string[]>
      [-AsJob]
      [-HideComputerName]
      [-UserName <string>]
      [-KeyFilePath <string>]
      [-Subsystem <string>]
      [-ConnectingTimeout <int>]
      [-SSHTransport]
      [-Options <hashtable>]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      -FilePath <string>
      -SSHConnection <hashtable[]>
      [-AsJob]
      [-HideComputerName]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Description

The Invoke-Command cmdlet runs commands on a local or remote computer and returns all output from the commands, including errors. Using a single Invoke-Command command, you can run commands on multiple computers.

To run a single command on a remote computer, use the ComputerName parameter. To run a series of related commands that share data, use the New-PSSession cmdlet to create a PSSession (a persistent connection) on the remote computer, and then use the Session parameter of Invoke-Command to run the command in the PSSession. To run a command in a disconnected session, use the InDisconnectedSession parameter. To run a command in a background job, use the AsJob parameter.

You can also use Invoke-Command on a local computer to a run script block as a command. PowerShell runs the script block immediately in a child scope of the current scope.

Before using Invoke-Command to run commands on a remote computer, read about_Remote.

Starting with PowerShell 6.0 you can use Secure Shell (SSH) to establish a connection to and invoke commands on remote computers. SSH must be installed on the local computer and the remote computer must be configured with a PowerShell SSH endpoint. The benefit of an SSH based PowerShell remote session is that it works across multiple platforms (Windows, Linux, macOS). For SSH based session you use the HostName or SSHConnection parameters to specify the remote computer and relevant connection information. For more information about how to set up PowerShell SSH remoting, see PowerShell Remoting Over SSH.

Some code samples use splatting to reduce the line length. For more information, see about_Splatting.

Examples

Example 1: Run a script on a server

This example runs the Test.ps1 script on the Server01 computer.

Invoke-Command -FilePath c:\scripts\test.ps1 -ComputerName Server01

The FilePath parameter specifies a script that is located on the local computer. The script runs on the remote computer and the results are returned to the local computer.

Example 2: Run a command on a remote server

This example runs a Get-Culture command on the Server01 remote computer.

Invoke-Command -ComputerName Server01 -Credential Domain01\User01 -ScriptBlock {
    Get-Culture
}

The ComputerName parameter specifies the name of the remote computer. The Credential parameter is used to run the command in the security context of Domain01\User01, a user who has permission to run commands. The ScriptBlock parameter specifies the command to be run on the remote computer.

In response, PowerShell requests the password and an authentication method for the User01 account. It then runs the command on the Server01 computer and returns the result.

Example 3: Run a command in a persistent connection

This example runs the same Get-Culture command in a session, using a persistent connection, on the remote computer named Server02.

$s = New-PSSession -ComputerName Server02 -Credential Domain01\User01
Invoke-Command -Session $s -ScriptBlock { Get-Culture }

The New-PSSession cmdlet creates a session on the Server02 remote computer and saves it in the $s variable. Typically, you create a session only when you run a series of commands on the remote computer.

The Invoke-Command cmdlet runs the Get-Culture command on Server02. The Session parameter specifies the session saved in the $s variable.

In response, PowerShell runs the command in the session on the Server02 computer.

Example 4: Use a session to run a series of commands that share data

This example compares the effects of using ComputerName and Session parameters of Invoke-Command. It shows how to use a session to run a series of commands that share the same data.

Invoke-Command -ComputerName Server02 -ScriptBlock { $p = Get-Process PowerShell }
Invoke-Command -ComputerName Server02 -ScriptBlock { $p.VirtualMemorySize }
$s = New-PSSession -ComputerName Server02
Invoke-Command -Session $s -ScriptBlock { $p = Get-Process PowerShell }
Invoke-Command -Session $s -ScriptBlock { $p.VirtualMemorySize }

17930240

The first two commands use the ComputerName parameter of Invoke-Command to run commands on the Server02 remote computer. The first command uses the Get-Process cmdlet to get the PowerShell process on the remote computer and to save it in the $p variable. The second command gets the value of the VirtualMemorySize property of the PowerShell process.

When you use the ComputerName parameter, PowerShell creates a new session to run the command. The session is closed when the command completes. The $p variable was created in one connection, but it doesn't exist in the connection created for the second command.

The problem is solved by creating a persistent session on the remote computer, then running both of the commands in the same session.

The New-PSSession cmdlet creates a persistent session on the computer Server02 and saves the session in the $s variable. The Invoke-Command lines that follow use the Session parameter to run both of the commands in the same session. Since both commands run in the same session, the $p value remains active.

Example 5: Invoke a command with a script block stored in a variable

This example shows how to run a command that is stored as a script block in a variable. When the script block is saved in a variable, you can specify the variable as the value of the ScriptBlock parameter.

$command = {
    Get-WinEvent -LogName PowerShellCore/Operational |
      Where-Object -FilterScript { $_.Message -like '*certificate*' }
}
Invoke-Command -ComputerName S1, S2 -ScriptBlock $command

The $command variable stores the Get-WinEvent command that's formatted as a script block. The Invoke-Command runs the command stored in $command on the S1 and S2 remote computers.

Example 6: Run a single command on several computers

This example demonstrates how to use Invoke-Command to run a single command on multiple computers.

$parameters = @{
  ComputerName      = 'Server01', 'Server02', 'TST-0143', 'localhost'
  ConfigurationName = 'MySession.PowerShell'
  ScriptBlock       = { Get-WinEvent -LogName PowerShellCore/Operational }
}
Invoke-Command @parameters

The ComputerName parameter specifies a comma-separated list of computer names. The list of computers includes the localhost value, which represents the local computer. The ConfigurationName parameter specifies an alternate session configuration. The ScriptBlock parameter runs Get-WinEvent to get the PowerShellCore/Operational event logs from each computer.

Example 7: Get the version of the host program on multiple computers

This example gets the version of the PowerShell host program running on 200 remote computers.

$version = Invoke-Command -ComputerName (Get-Content Machines.txt) -ScriptBlock {
    (Get-Host).Version
}

Because only one command is run, you don't have to create persistent connections to each of the computers. Instead, the command uses the ComputerName parameter to indicate the computers. To specify the computers, it uses the Get-Content cmdlet to get the contents of the Machine.txt file, a file of computer names.

The Invoke-Command cmdlet runs a Get-Host command on the remote computers. It uses dot notation to get the Version property of the PowerShell host.

These commands run one at a time. When the commands complete, the output of the commands from all of the computers is saved in the $version variable. The output includes the name of the computer from which the data originated.

Example 8: Run a background job on several remote computers

This example runs a command on two remote computers. The Invoke-Command command uses the AsJob parameter so that the command runs as a background job. The commands run on the remote computers, but the job exists on the local computer. The results are transmitted to the local computer.

$s = New-PSSession -ComputerName Server01, Server02
Invoke-Command -Session $s -ScriptBlock { Get-EventLog system } -AsJob

Id   Name    State      HasMoreData   Location           Command
---  ----    -----      -----         -----------        ---------------
1    Job1    Running    True          Server01,Server02  Get-EventLog system

$j = Get-Job
$j | Format-List -Property *

HasMoreData   : True
StatusMessage :
Location      : Server01,Server02
Command       : Get-EventLog system
JobStateInfo  : Running
Finished      : System.Threading.ManualResetEvent
InstanceId    : e124bb59-8cb2-498b-a0d2-2e07d4e030ca
Id            : 1
Name          : Job1
ChildJobs     : {Job2, Job3}
Output        : {}
Error         : {}
Progress      : {}
Verbose       : {}
Debug         : {}
Warning       : {}
StateChanged  :

$results = $j | Receive-Job

The New-PSSession cmdlet creates sessions on the Server01 and Server02 remote computers. The Invoke-Command cmdlet runs a background job in each of the sessions. The command uses the AsJob parameter to run the command as a background job. This command returns a job object that contains two child job objects, one for each of the jobs run on the two remote computers.

The Get-Job command saves the job object in the $j variable. The $j variable is then piped to the Format-List cmdlet to display all properties of the job object in a list. The last command gets the results of the jobs. It pipes the job object in $j to the Receive-Job cmdlet and stores the results in the $results variable.

Example 9: Include local variables in a command run on a remote computer

This example shows how to include the values of local variables in a command run on a remote computer. The command uses the Using scope modifier to identify a local variable in a remote command. By default, all variables are assumed to be defined in the remote session. The Using scope modifier was introduced in PowerShell 3.0. For more information about the Using scope modifier, see about_Remote_Variables and about_Scopes.

$Log = 'PowerShellCore/Operational'
Invoke-Command -ComputerName Server01 -ScriptBlock {
    Get-WinEvent -LogName $Using:Log -MaxEvents 10
}

The $Log variable stores the name of the event log, PowerShellCore/Operational. The Invoke-Command cmdlet runs Get-WinEvent on Server01 to get the ten newest events from the event log. The value of the LogName parameter is the $Log variable that is prefixed by the Using scope modifier to indicate that it was created in the local session, not in the remote session.

Example 10: Hide the computer name

This example shows the effect of using the HideComputerName parameter of Invoke-Command. HideComputerName doesn't change the object that this cmdlet returns. It changes only the display. You can still use the Format cmdlets to display the PsComputerName property of any of the affected objects.

Invoke-Command -ComputerName S1, S2 -ScriptBlock { Get-Process PowerShell }

PSComputerName    Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id   ProcessName
--------------    -------  ------    -----      ----- -----   ------     --   -----------
S1                575      15        45100      40988   200     4.68     1392 PowerShell
S2                777      14        35100      30988   150     3.68     67   PowerShell

Invoke-Command -ComputerName S1, S2 -HideComputerName -ScriptBlock {
    Get-Process PowerShell
}

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id   ProcessName
-------  ------    -----      ----- -----   ------     --   -----------
575      15        45100      40988   200     4.68     1392 PowerShell
777      14        35100      30988   150     3.68     67   PowerShell

The first two commands use Invoke-Command to run a Get-Process command for the PowerShell process. The output of the first command includes the PsComputerName property, which contains 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: 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 filenames that begin with the letter a and have the .pdf extension.

For more information about the Param keyword, see about_Language_Keywords.

$parameters = @{
    ComputerName = 'Server01'
    ScriptBlock  = {
        Param ($param1, $param2)
        Get-ChildItem -Name $param1 -Include $param2
    }
    ArgumentList = 'a*', '*.pdf'
}
Invoke-Command @parameters

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

$parameters = @{
    ComputerName = 'Server01'
    ScriptBlock  = { Get-ChildItem $args[0] $args[1] }
    ArgumentList = 'C:\Test', '*.txt*'
}
Invoke-Command @parameters

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 file. This command lets you run the script on the remote computers, even if the script file isn't accessible to the remote computers.

$parameters = @{
    ComputerName = (Get-Content Servers.txt)
    FilePath     = 'C:\Scripts\Sample.ps1'
    ArgumentList = 'Process', 'Service'
}
Invoke-Command @parameters

When you submit the command, the content of the Sample.ps1 file is copied into a script block and 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 14: Run a command on a remote computer 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.

$LiveCred = Get-Credential
$parameters = @{
  ConfigurationName = 'Microsoft.Exchange'
  ConnectionUri     = 'https://ps.exchangelabs.com/PowerShell'
  Credential        = $LiveCred
  Authentication    = 'Basic'
  ScriptBlock       = { Set-Mailbox Dan -DisplayName 'Dan Park' }
}
Invoke-Command @parameters

The first line uses the Get-Credential cmdlet to store Windows Live ID credentials in the $LiveCred variable. PowerShell prompts the user to enter Windows Live ID credentials.

The $parameters variable is a hash table containing the parameters to be passed to the Invoke-Command cmdlet. The Invoke-Command cmdlet runs a Set-Mailbox command using the Microsoft.Exchange session configuration. The ConnectionURI parameter specifies the URL of the Exchange server endpoint. The Credential parameter specifies the credentials stored in the $LiveCred variable. The AuthenticationMechanism parameter specifies the use of basic authentication. The ScriptBlock parameter specifies a script block that contains the command.

Example 15: Use a session option

This example shows how to create and use a SessionOption parameter.

$so = New-PSSessionOption -SkipCACheck -SkipCNCheck -SkipRevocationCheck
$parameters = @{
    ComputerName  = 'server01'
    UseSSL        = $true
    ScriptBlock   = { Get-HotFix }
    SessionOption = $so
    Credential    = 'server01\user01'
}
Invoke-Command @parameters

The New-PSSessionOption cmdlet creates a session option object that causes the remote end not to verify the Certificate Authority, Canonical Name, and Revocation Lists while evaluating the incoming 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 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.

$max = New-PSSessionOption -MaximumRedirection 1
$parameters = @{
  ConnectionUri    = 'https://ps.exchangelabs.com/PowerShell'
  ScriptBlock      = { Get-Mailbox dan }
  AllowRedirection = $true
  SessionOption    = $max
}
Invoke-Command @parameters

The New-PSSessionOption cmdlet creates a PSSessionOption object that is saved in the $max variable. The command uses the MaximumRedirection parameter to set the MaximumConnectionRedirectionCount property of the PSSessionOption object to 1.

The Invoke-Command cmdlet runs a Get-Mailbox command on a remote Microsoft Exchange Server. The AllowRedirection parameter provides explicit permission to redirect the connection to an alternate endpoint. The SessionOption parameter uses the session object stored in the $max variable.

As a result, if the remote computer specified by ConnectionURI returns a redirection message, 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 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 contains the network share. Server01 connects to Server02, and then Server02 does a second hop to Net03 to access the network share. For more information about how PowerShell Remoting supports hops between computers, see Making the second hop in PowerShell Remoting.

The required Credential Security Support Provider (CredSSP) delegation is enabled in the client settings on the local computer, and in the service settings on the remote computer. To run the commands in this example, you must be a member of the Administrators group on the local computer and the remote computer.

Enable-WSManCredSSP -Role Client -DelegateComputer Server02
$s = New-PSSession Server02
Invoke-Command -Session $s -ScriptBlock { Enable-WSManCredSSP -Role Server -Force }
$parameters = @{
  ComputerName   = 'Server02'
  ScriptBlock    = { Get-Item \\Net03\Scripts\LogFiles.ps1 }
  Authentication = 'CredSSP'
  Credential     = 'Domain01\Admin01'
}
Invoke-Command @parameters

The Enable-WSManCredSSP cmdlet enables CredSSP delegation from the Server01 local computer to the Server02 remote computer. The Role parameter specifies Client to configure the CredSSP client setting on the local computer.

New-PSSession creates a PSSession object for Server02 and stores the object in the $s variable.

The Invoke-Command cmdlet uses the $s variable to connect to the remote computer, Server02. The ScriptBlock parameter runs Enable-WSManCredSSP on the remote computer. The Role parameter specifies Server to configure the CredSSP server setting on the remote computer.

The $parameters variable contains the parameter values to connect to the network share. The Invoke-Command cmdlet runs a Get-Item command in the session in $s. This command gets a script 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 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. The script continues to run in the disconnected sessions.

$parameters = @{
  ComputerName          = (Get-Content -Path C:\Test\Servers.txt)
  InDisconnectedSession = $true
  FilePath              = '\\Scripts\Public\ConfigInventory.ps1'
  SessionOption         = @{
      OutputBufferingMode = 'Drop'
      IdleTimeout         = [timespan]::FromHours(12)
  }
}
Invoke-Command @parameters

The command uses Invoke-Command to run the script. The value of the ComputerName parameter is a Get-Content command that gets the names of the remote computers from a text file. The InDisconnectedSession parameter disconnects the sessions as soon as it starts the command. The value of the FilePath parameter is the script that Invoke-Command runs on each computer.

The value of SessionOption is a hash table. The OutputBufferingMode value is set to Drop and the IdleTimeout value is set to 12 hours.

To get the results of commands and scripts that run in disconnected sessions, use the Receive-PSSession cmdlet.

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. Otherwise, you'll have to use SSH key-based user authentication.

Invoke-Command -HostName UserA@LinuxServer01 -ScriptBlock { Get-MailBox * }

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 the remote computer is configured to allow basic password authentication.

$parameters = @{
    HostName    = 'UserA@LinuxServer01'
    ScriptBlock = { Get-MailBox * }
    KeyFilePath = '/UserA/UserAKey_rsa'
}
Invoke-Command

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 contain connection information for each computer. This example requires that the target remote computers have SSH configured to support key-based user authentication.

$sshConnections = @(
    @{
        HostName    = "WinServer1"
        UserName    = "Domain\UserA"
        KeyFilePath = "C:\Users\UserA\id_rsa"
    }
    @{
        HostName    = "UserB@LinuxServer5"
        KeyFilePath = "/Users/UserB/id_rsa"
    }
)
$results = Invoke-Command -FilePath c:\Scripts\GetInfo.ps1 -SSHConnection $sshConnections

Example 22: Connect to a remote SSH session using SSH options

This example shows how to run a script file on a remote Linux-based machine using SSH options. The Options parameter takes a hashtable of values that are passed as options to the underlying ssh command the established the connection to the remote system.

$options = @{
    Port=22
    User = 'UserB'
    Host = 'LinuxServer5'
}
$results = Invoke-Command -FilePath c:\Scripts\CollectEvents.ps1 -KeyFilePath '/Users/UserB/id_rsa' -Options $options

Parameters

-AllowRedirection

-ApplicationName

-ArgumentList

-AsJob

-Authentication

-CertificateThumbprint

-ComputerName

-ConfigurationName

-ConnectingTimeout

-ConnectionUri

-ContainerId

-Credential

-EnableNetworkAccess

-FilePath

-HideComputerName

-HostName

-InDisconnectedSession

-InputObject

-JobName

-KeyFilePath

-NoNewScope

-Options

-Port

-RemoteDebug

-RunAsAdministrator

-ScriptBlock

-Session

-SessionName

-SessionOption

-SSHConnection

-SSHTransport

-Subsystem

-ThrottleLimit

-UserName

-UseSSL

-VMId

-VMName

Inputs

ScriptBlock

You can pipe a command in a script block to Invoke-Command. Use the $Input automatic variable to represent the input objects in the command.

Outputs

System.Management.Automation.PSRemotingJob

If you use the AsJob parameter, this cmdlet returns a job object.

PSSession

If you use the InDisconnectedSession parameter, this cmdlet returns a PSSession object.

Object

By default, this cmdlet returns the output of the invoked command, which is the value of the ScriptBlock parameter.

Notes

PowerShell includes the following aliases for Invoke-Command:

• All platforms:
  • icm

On Windows Vista, and later versions of the Windows operating system, to use the ComputerName parameter of Invoke-Command to run a command on the local computer, you must run PowerShell using the Run as administrator option.

When you run commands on multiple computers, PowerShell connects to the computers in the order in which they appear in the list. However, the command output is displayed in the order that it's received from the remote computers, which might be different.

Errors that result from the command that Invoke-Command runs are included in the command results. Errors that would be terminating errors in a local command are treated as non-terminating errors in a remote command. This strategy makes sure that terminating errors on one computer don't close the command on all computers on which it's run. This practice is used even when a remote command is run on a single computer.

If the remote computer isn't in a domain that the local computer trusts, the computer might not be able to authenticate the user's credentials. To add the remote computer to the list of trusted hosts in WS-Management, use the following command in the WSMAN provider, where <Remote-Computer-Name> is the name of the remote computer:

Set-Item -Path WSMan:\Localhost\Client\TrustedHosts -Value \<Remote-Computer-Name\>

When you disconnect a PSSession using the InDisconnectedSession parameter, the session state is Disconnected and the availability is None. The value of the State property is relative to the current session. A value of Disconnected means that the PSSession isn't connected to the current session. However, it doesn't mean that the PSSession is disconnected from all sessions. It might be connected to a different session. To determine whether you can connect or reconnect to the session, use the Availability property.

An Availability value of None indicates that you can connect to the session. A value of Busy indicates that you can't connect to the PSSession because it's connected to another session. For more information about the values of the State property of sessions, see RunspaceState. For more information about the values of the Availability property of sessions, see RunspaceAvailability.

The HostName and SSHConnection parameters were included starting with PowerShell 6.0. They were added to provide PowerShell remoting based on Secure Shell (SSH). PowerShell and SSH are supported on multiple platforms (Windows, Linux, macOS) and PowerShell remoting works over these platforms where PowerShell and SSH are installed and configured. This is separate from the previous Windows only remoting that is based on WinRM and many of the WinRM specific features and limitations don't apply. For example WinRM based quotas, session options, custom endpoint configuration, and disconnect/reconnect features are currently not supported. For more information about how to set up PowerShell SSH remoting, see PowerShell Remoting Over SSH.

The ssh executable obtains configuration data from the following sources in the following order:

1. command-line options
2. user's configuration file (~/.ssh/config)
3. system-wide configuration file (/etc/ssh/ssh_config)

The following cmdlet parameters get mapped into ssh parameters and options:

Cmdlet parameter	ssh parameter	equivalent ssh -o option
-KeyFilePath	-i <KeyFilePath>	-o IdentityFile=<KeyFilePath>
-UserName	-l <UserName>	-o User=<UserName>
-Port	-p <Port>	-o Port=<Port>
-ComputerName -Subsystem	-s <ComputerName> <Subsystem>	-o Host=<ComputerName>

Any values explicitly passed by parameters take precedence over values passed in the Options hashtable. For more information about ssh_config files, see ssh_config(5).

Related Links

• about_PSSessions
• about_Remote
• about_Remote_Disconnected_Sessions
• about_Remote_Troubleshooting
• about_Remote_Variables
• about_Scopes
• Enter-PSSession
• Exit-PSSession
• Get-PSSession
• Invoke-Item
• New-PSSession
• Remove-PSSession
• WSMan Provider