Invoke-Command

Sintaxe

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

O cmdlet Invoke-Command executa comandos em um computador local ou remoto e retorna toda a saída dos comandos, incluindo erros. Usando um único comando Invoke-Command, você pode executar comandos em vários computadores.

Para executar um único comando em um computador remoto, use o parâmetro ComputerName. Para executar uma série de comandos relacionados que compartilham dados, use o cmdlet para criar um PSSession (uma conexão persistente) no computador remoto e, em seguida, use o parâmetro Session de para executar o comando no PSSession. Para executar um comando em uma sessão desconectada, use o parâmetro InDisconnectedSession. Para executar um comando em um trabalho em segundo plano, use o parâmetro AsJob.

Você também pode usar Invoke-Command em um computador local para um bloco de script de execução como um comando. O PowerShell executa o bloco de script imediatamente em um escopo filho do escopo atual.

Antes de usar Invoke-Command para executar comandos em um computador remoto, leia about_Remote.

A partir do PowerShell 6.0, você pode usar o Secure Shell (SSH) para estabelecer uma conexão e invocar comandos em computadores remotos. O SSH deve ser instalado no computador local e o computador remoto deve ser configurado com um ponto de extremidade SSH do PowerShell. O benefício de uma sessão remota do PowerShell baseada em SSH é que ela funciona em várias plataformas (Windows, Linux, macOS). Para sessão baseada em SSH, use o HostName ou parâmetros SSHConnection para especificar o computador remoto e as informações de conexão relevantes. Para obter mais informações sobre como configurar a comunicação remota SSH do PowerShell, consulte PowerShell Remoting Over SSH.

Alguns exemplos de código usam splatting para reduzir o comprimento da linha. Para obter mais informações, consulte about_Splatting.

Exemplos

Exemplo 1: Executar um script em um servidor

Este exemplo executa o script Test.ps1 no computador Server01.

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

O parâmetro FilePath especifica um script localizado no computador local. O script é executado no computador remoto e os resultados são retornados para o computador local.

Exemplo 2: Executar um comando em um servidor remoto

Este exemplo executa um comando Get-Culture no computador remoto Server01.

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

O parâmetro ComputerName especifica o nome do computador remoto. O parâmetro Credential é usado para executar o comando no contexto de segurança de Domain01\User01, um usuário que tem permissão para executar comandos. O parâmetro ScriptBlock especifica o comando a ser executado no computador remoto.

Em resposta, o PowerShell solicita a senha e um método de autenticação para a conta User01. Em seguida, ele executa o comando no computador Server01 e retorna o resultado.

Exemplo 3: Executar um comando em uma conexão persistente

Este exemplo executa o mesmo comando Get-Culture em uma sessão, usando uma conexão persistente, no computador remoto chamado Server02.

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

O cmdlet New-PSSession cria uma sessão no computador remoto Server02 e a salva na variável $s. Normalmente, você cria uma sessão somente quando executa uma série de comandos no computador remoto.

O cmdlet Invoke-Command executa o comando Get-Culture no Server02. O parâmetro Session especifica a sessão salva na variável $s.

Em resposta, o PowerShell executa o comando na sessão no computador Server02.

Exemplo 4: Usar uma sessão para executar uma série de comandos que compartilham dados

Este exemplo compara os efeitos do uso de ComputerName e parâmetros Session de Invoke-Command. Ele mostra como usar uma sessão para executar uma série de comandos que compartilham os mesmos dados.

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

Os dois primeiros comandos usam o parâmetro ComputerName de Invoke-Command para executar comandos no computador remoto Server02. O primeiro comando usa o cmdlet Get-Process para obter o processo do PowerShell no computador remoto e salvá-lo na variável $p. O segundo comando obtém o valor da propriedade VirtualMemorySize do processo do PowerShell.

Quando você usa o parâmetro ComputerName, o PowerShell cria uma nova sessão para executar o comando. A sessão é encerrada quando o comando é concluído. A variável $p foi criada em uma conexão, mas não existe na conexão criada para o segundo comando.

O problema é resolvido criando uma sessão persistente no computador remoto e, em seguida, executando ambos os comandos na mesma sessão.

O cmdlet New-PSSession cria uma sessão persistente no computador Server02 e salva a sessão na variável $s. As Invoke-Command linhas a seguir usam o parâmetro Session para executar ambos os comandos na mesma sessão. Como ambos os comandos são executados na mesma sessão, o valor $p permanece ativo.

Exemplo 5: Invocar um comando com um bloco de script armazenado em uma variável

Este exemplo mostra como executar um comando que é armazenado como um bloco de script em uma variável. Quando o bloco de script é salvo em uma variável, você pode especificar a variável como o valor do parâmetro ScriptBlock.

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

A variável $command armazena o comando Get-WinEvent formatado como um bloco de script. O Invoke-Command executa o comando armazenado em $command nos computadores remotos S1 e S2.

Exemplo 6: Executar um único comando em vários computadores

Este exemplo demonstra como usar Invoke-Command para executar um único comando em vários computadores.

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

O parâmetro ComputerName especifica uma lista separada por vírgulas de nomes de computadores. A lista de computadores inclui o valor localhost, que representa o computador local. O parâmetro ConfigurationName especifica uma configuração de sessão alternativa. O parâmetro ScriptBlock é executado Get-WinEvent para obter os logs de eventos PowerShellCore/Operational de cada computador.

Exemplo 7: Obter a versão do programa host em vários computadores

Este exemplo obtém a versão do programa host do PowerShell em execução em 200 computadores remotos.

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

Como apenas um comando é executado, não é necessário criar conexões persistentes com cada um dos computadores. Em vez disso, o comando usa o parâmetro ComputerName para indicar os computadores. Para especificar os computadores, ele usa o cmdlet Get-Content para obter o conteúdo do arquivo Machine.txt, um arquivo de nomes de computador.

O cmdlet Invoke-Command executa um comando Get-Host nos computadores remotos. Ele usa notação de ponto para obter a propriedade Versão do host do PowerShell.

Esses comandos são executados um de cada vez. Quando os comandos são concluídos, a saída dos comandos de todos os computadores é salva na variável $version. A saída inclui o nome do computador do qual os dados se originaram.

Exemplo 8: Executar um trabalho em segundo plano em vários computadores remotos

Este exemplo executa um comando em dois computadores remotos. O comando Invoke-Command usa o parâmetro AsJob para que o comando seja executado como um trabalho em segundo plano. Os comandos são executados nos computadores remotos, mas o trabalho existe no computador local. Os resultados são transmitidos para o computador local.

$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

O cmdlet New-PSSession cria sessões nos computadores remotos Server01 e Server02. O cmdlet Invoke-Command executa um trabalho em segundo plano em cada uma das sessões. O comando usa o parâmetro AsJob para executar o comando como um trabalho em segundo plano. Este comando retorna um objeto de trabalho que contém dois objetos de trabalho filho, um para cada um dos trabalhos executados nos dois computadores remotos.

O comando Get-Job salva o objeto de trabalho na variável $j. A variável $j é então canalizada para o cmdlet Format-List para exibir todas as propriedades do objeto de trabalho em uma lista. O último comando obtém os resultados dos trabalhos. Ele canaliza o objeto de trabalho em $j para o cmdlet Receive-Job e armazena os resultados na variável $results.

Exemplo 9: Incluir variáveis locais em um comando executado em um computador remoto

Este exemplo mostra como incluir os valores de variáveis locais em um comando executado em um computador remoto. O comando usa o modificador de escopo Using para identificar uma variável local em um comando remoto. Por padrão, todas as variáveis são consideradas definidas na sessão remota. O Using modificador de escopo foi introduzido no PowerShell 3.0. Para obter mais informações sobre o modificador de escopo Using, consulte about_Remote_Variables e about_Scopes.

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

A variável $Log armazena o nome do log de eventos, PowerShellCore/Operational. O cmdlet Invoke-Command executa Get-WinEvent no Server01 para obter os dez eventos mais recentes do log de eventos. O valor do parâmetro LogName é a variável $Log prefixada pelo modificador de escopo Using para indicar que ela foi criada na sessão local, não na sessão remota.

Exemplo 10: Ocultar o nome do computador

Este exemplo mostra o efeito do uso do parâmetro HideComputerName de Invoke-Command. HideComputerName não altera o objeto retornado por esse cmdlet. Altera apenas o ecrã. Você ainda pode usar os cmdlets Format para exibir a propriedade PsComputerName de qualquer um dos objetos afetados.

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

Os dois primeiros comandos usam Invoke-Command para executar um comando Get-Process para o processo do PowerShell. A saída do primeiro comando inclui a propriedade PsComputerName, que contém o nome do computador no qual o comando foi executado. A saída do segundo comando, que usa HideComputerName, não inclui a coluna PsComputerName.

Exemplo 11: Usar a palavra-chave Param em um bloco de script

A palavra-chave Param e o parâmetro ArgumentList são usados para passar valores de variáveis para parâmetros nomeados em um bloco de script. Este exemplo exibe nomes de arquivos que começam com a letra a e têm a extensão .pdf.

Para obter mais informações sobre a palavra-chave Param, consulte 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 usa o parâmetro ScriptBlock que define duas variáveis, $param1 e $param2. Get-ChildItem usa os parâmetros nomeados, Nome e Incluir com os nomes das variáveis. O ArgumentList passa os valores para as variáveis.

Exemplo 12: Usar a variável automática $args em um bloco de script

A variável automática $args e o parâmetro ArgumentList são usados para passar valores de matriz para posições de parâmetros em um bloco de script. Este exemplo exibe o conteúdo do diretório de um servidor de arquivos .txt. O parâmetro Get-ChildItemPath é a posição 0 e o parâmetro Filter é a posição 1.

Para obter mais informações sobre a variável $args, consulte 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 usa um parâmetro ScriptBlock e Get-ChildItem especifica os valores de matriz $args[0] e $args[1]. O ArgumentList passa os valores da matriz de para as posições dos parâmetros para de Caminho ede Filtro de .

Exemplo 13: Executar um script em todos os computadores listados em um arquivo de texto

Este exemplo usa o cmdlet Invoke-Command para executar o script Sample.ps1 em todos os computadores listados no arquivo Servers.txt. O comando usa o parâmetro FilePath para especificar o arquivo de script. Este comando permite executar o script nos computadores remotos, mesmo que o arquivo de script não esteja acessível aos computadores remotos.

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

Quando você envia o comando, o conteúdo do arquivo Sample.ps1 é copiado para um bloco de script e o bloco de script é executado em cada um dos computadores remotos. Este procedimento é equivalente a usar o parâmetro ScriptBlock para enviar o conteúdo do script.

Exemplo 14: Executar um comando em um computador remoto usando um URI

Este exemplo mostra como executar um comando em um computador remoto identificado por um URI (Uniform Resource Identifier). Este exemplo em particular executa um comando Set-Mailbox em um servidor remoto do Exchange.

$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

A primeira linha usa o cmdlet Get-Credential para armazenar credenciais do Windows Live ID na variável $LiveCred. O PowerShell solicita que o usuário insira credenciais do Windows Live ID.

A variável $parameters é uma tabela de hash que contém os parâmetros a serem passados para o cmdlet Invoke-Command. O cmdlet executa um comando usando a configuração de sessão Microsoft.Exchange. O parâmetro ConnectionURI especifica a URL do ponto de extremidade do servidor Exchange. O parâmetro Credential especifica as credenciais armazenadas na variável $LiveCred. O parâmetro AuthenticationMechanism especifica o uso da autenticação básica. O parâmetro ScriptBlock especifica um bloco de script que contém o comando.

Exemplo 15: Usar uma opção de sessão

Este exemplo mostra como criar e usar um parâmetro SessionOption.

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

O cmdlet New-PSSessionOption cria um objeto de opção de sessão que faz com que a extremidade remota não verifique a Autoridade de Certificação, o Nome Canônico e as Listas de Revogação ao avaliar a conexão HTTPS de entrada. O objeto SessionOption é salvo na variável .

O cmdlet Invoke-Command executa um comando Get-HotFix remotamente. O parâmetro SessionOption recebe a variável $so.

Exemplo 16: Gerenciar o redirecionamento de URI em um comando remoto

Este exemplo mostra como usar os parâmetros AllowRedirection e SessionOption para gerenciar o redirecionamento de URI em um comando remoto.

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

O cmdlet New-PSSessionOption cria um objeto PSSessionOption que é salvo na variável $max. O comando usa o parâmetro MaximumRedirection para definir a propriedade MaximumConnectionRedirectionCount do objeto PSSessionOption como 1.

O cmdlet Invoke-Command executa um comando Get-Mailbox em um Microsoft Exchange Server remoto. O parâmetro AllowRedirection fornece permissão explícita para redirecionar a conexão para um ponto de extremidade alternativo. O parâmetro SessionOption usa o objeto de sessão armazenado na variável $max.

Como resultado, se o computador remoto especificado por ConnectionURI retornar uma mensagem de redirecionamento, o PowerShell redirecionará a conexão, mas se o novo destino retornar outra mensagem de redirecionamento, o valor de contagem de redirecionamento de 1 será excedido e Invoke-Command retornará um erro de não terminação.

Exemplo 17: Acessar um compartilhamento de rede em uma sessão remota

Este exemplo mostra como acessar um compartilhamento de rede a partir de uma sessão remota. Três computadores são usados para demonstrar o exemplo. Server01 é o computador local, Server02 é o computador remoto e Net03 contém o compartilhamento de rede. Server01 se conecta ao Server02 e, em seguida, Server02 faz um segundo salto para Net03 para acessar o compartilhamento de rede. Para obter mais informações sobre como a comunicação remota do PowerShell dá suporte a saltos entre computadores, consulte Making the second hop in PowerShell Remoting.

A delegação CredSSP (Credential Security Support Provider) necessária está habilitada nas configurações do cliente no computador local e nas configurações de serviço no computador remoto. Para executar os comandos neste exemplo, você deve ser membro do grupo Administradores do no computador local e no computador remoto.

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

O cmdlet Enable-WSManCredSSP permite a delegação CredSSP do computador local Server01 para o computador remoto Server02. O parâmetro Role especifica Client para definir a configuração do cliente CredSSP no computador local.

New-PSSession cria um objeto PSSession para Server02 e armazena o objeto na variável $s.

O cmdlet Invoke-Command usa a variável $s para se conectar ao computador remoto, Server02. O parâmetro ScriptBlock é executado Enable-WSManCredSSP no computador remoto. O parâmetro Role especifica Server para definir a configuração do servidor CredSSP no computador remoto.

A variável $parameters contém os valores de parâmetro para se conectar ao compartilhamento de rede. O cmdlet Invoke-Command executa um comando Get-Item na sessão em $s. Este comando obtém um script do compartilhamento de rede \\Net03\Scripts. O comando usa o parâmetro Authentication com um valor de CredSSP e o parâmetro Credential com um valor de Domain01\Admin01.

Exemplo 18: Iniciar scripts em muitos computadores remotos

Este exemplo executa um script em mais de cem computadores. Para minimizar o impacto no computador local, ele se conecta a cada computador, inicia o script e, em seguida, desconecta-se de cada computador. O script continua a ser executado nas sessões desconectadas.

$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

O comando usa Invoke-Command para executar o script. O valor do parâmetro ComputerName é um comando que obtém os nomes dos computadores remotos de um arquivo de texto. O parâmetro InDisconnectedSession desconecta as sessões assim que inicia o comando. O valor do parâmetro FilePath é o script que Invoke-Command executa em cada computador.

O valor de SessionOption é uma tabela de hash. O valor OutputBufferingMode é definido como Drop e o valor IdleTimeout é definido como 12 horas.

Para obter os resultados de comandos e scripts executados em sessões desconectadas, use o cmdlet Receive-PSSession.

Exemplo 19: Executar um comando em um computador remoto usando SSH

Este exemplo mostra como executar um comando em um computador remoto usando o Secure Shell (SSH). Se o SSH estiver configurado no computador remoto para solicitar senhas, você receberá um prompt de senha. Caso contrário, você terá que usar a autenticação de usuário baseada em chave SSH.

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

Exemplo 20: Executar um comando em um computador remoto usando SSH e especificar uma chave de autenticação do usuário

Este exemplo mostra como executar um comando em um computador remoto usando SSH e especificando um arquivo de chave para autenticação do usuário. Não lhe será solicitada uma palavra-passe, a menos que a autenticação de chave falhe e o computador remoto esteja configurado para permitir a autenticação básica de palavra-passe.

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

Exemplo 21: Executar um arquivo de script em vários computadores remotos usando SSH como um trabalho

Este exemplo mostra como executar um arquivo de script em vários computadores remotos usando SSH e o SSHConnection conjunto de parâmetros. O parâmetro SSHConnection usa uma matriz de tabelas de hash que contêm informações de conexão para cada computador. Este exemplo requer que os computadores remotos de destino tenham o SSH configurado para oferecer suporte à autenticação de usuário baseada em chave.

$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

Exemplo 22: Conectar-se a uma sessão SSH remota usando opções SSH

Este exemplo mostra como executar um arquivo de script em uma máquina remota baseada em Linux usando opções SSH. O parâmetro Options usa uma hashtable de valores que são passados como opções para o comando ssh subjacente a conexão estabelecida com o sistema remoto.

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

Parâmetros

-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

Entradas

ScriptBlock

Você pode canalizar um comando em um bloco de script para Invoke-Command. Use a variável automática $Input para representar os objetos de entrada no comando.

Saídas

System.Management.Automation.PSRemotingJob

Se você usar o parâmetro AsJob, esse cmdlet retornará um objeto de trabalho.

PSSession

Se você usar o parâmetro InDisconnectedSession, esse cmdlet retornará um objeto PSSession.

Object

Por padrão, esse cmdlet retorna a saída do comando invoked, que é o valor do parâmetro ScriptBlock.

Notas

O PowerShell inclui os seguintes aliases para Invoke-Command:

• Todas as plataformas:
  • icm

No Windows Vista e em versões posteriores do sistema operacional Windows, para usar o parâmetro ComputerName do Invoke-Command para executar um comando no computador local, você deve executar o PowerShell usando a opção Executar como administrador opção.

Quando você executa comandos em vários computadores, o PowerShell se conecta aos computadores na ordem em que aparecem na lista. No entanto, a saída do comando é exibida na ordem em que é recebida dos computadores remotos, o que pode ser diferente.

Os erros resultantes do comando que Invoke-Command executa são incluídos nos resultados do comando. Os erros que seriam erros de encerramento em um comando local são tratados como erros não terminativos em um comando remoto. Essa estratégia garante que os erros de encerramento em um computador não fechem o comando em todos os computadores em que ele é executado. Essa prática é usada mesmo quando um comando remoto é executado em um único computador.

Se o computador remoto não estiver em um domínio em que o computador local confia, talvez não consiga autenticar as credenciais do usuário. Para adicionar o computador remoto à lista de hosts confiáveis no WS-Management, use o seguinte comando no provedor de WSMAN, onde <Remote-Computer-Name> é o nome do computador remoto:

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

Quando você desconecta um PSSession usando o parâmetro InDisconnectedSession, o estado da sessão é Desconectado e a disponibilidade é Nenhum. O valor da propriedade State é relativo à sessão atual. Um valor de Desconectado significa que o PSSession não está conectado à sessão atual. No entanto, isso não significa que o PSSession esteja desconectado de todas as sessões. Ele pode estar conectado a uma sessão diferente. Para determinar se você pode se conectar ou se reconectar à sessão, use a propriedade Disponibilidade.

Um valor de de Disponibilidade de de Nenhum indica que você pode se conectar à sessão. Um valor de Ocupado indica que você não pode se conectar ao PSSession porque ele está conectado a outra sessão. Para obter mais informações sobre os valores da propriedade State de sessões, consulte RunspaceState. Para obter mais informações sobre os valores da propriedade Availability de sessões, consulte RunspaceAvailability.

Os parâmetros HostName e SSHConnection foram incluídos a partir do PowerShell 6.0. Eles foram adicionados para fornecer comunicação remota do PowerShell com base no Secure Shell (SSH). O PowerShell e o SSH são suportados em várias plataformas (Windows, Linux, macOS) e a comunicação remota do PowerShell funciona nessas plataformas onde o PowerShell e o SSH estão instalados e configurados. Isso é separado da comunicação remota anterior do Windows baseada no WinRM e muitos dos recursos e limitações específicos do WinRM não se aplicam. Por exemplo, cotas baseadas no WinRM, opções de sessão, configuração de ponto de extremidade personalizada e recursos de desconexão/reconexão não são suportados no momento. Para obter mais informações sobre como configurar a comunicação remota SSH do PowerShell, consulte PowerShell Remoting Over SSH.

O executável ssh obtém dados de configuração das seguintes fontes na seguinte ordem:

1. Opções de linha de comando
2. arquivo de configuração do usuário (~/.ssh/config)
3. Arquivo de configuração em todo o sistema (/etc/ssh/ssh_config)

Os seguintes parâmetros de cmdlet são mapeados em ssh parâmetros e opções:

Parâmetro do cmdlet	Parâmetro SSH	Opção de -o SSH equivalente
-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>

Todos os valores explicitamente passados por parâmetros têm precedência sobre os valores passados na Opções hashtable. Para obter mais informações sobre ssh_config arquivos, consulte ssh_config(5).

Ligações Relacionadas

• 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
• Provedor WSMan