Invoke-Command

Referência

Módulo:: Microsoft.PowerShell.Core

Executa comandos em computadores locais e remotos.

Syntax

Invoke-Command
      [-StrictMode <Version>]
      [-ScriptBlock] <ScriptBlock>
      [-NoNewScope]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [[-Session] <PSSession[]>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-FilePath] <String>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [[-Session] <PSSession[]>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [[-ComputerName] <String[]>]
      [-Credential <PSCredential>]
      [-Port <Int32>]
      [-UseSSL]
      [-ConfigurationName <String>]
      [-ApplicationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-InDisconnectedSession]
      [-SessionName <String[]>]
      [-HideComputerName]
      [-JobName <String>]
      [-FilePath] <String>
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [[-ComputerName] <String[]>]
      [-Credential <PSCredential>]
      [-Port <Int32>]
      [-UseSSL]
      [-ConfigurationName <String>]
      [-ApplicationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-InDisconnectedSession]
      [-SessionName <String[]>]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-CertificateThumbprint <String>]
      [<CommonParameters>]

Invoke-Command
      [-Credential <PSCredential>]
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [[-ConnectionUri] <Uri[]>]
      [-AsJob]
      [-InDisconnectedSession]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      [-AllowRedirection]
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-CertificateThumbprint <String>]
      [<CommonParameters>]

Invoke-Command
      [-Credential <PSCredential>]
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [[-ConnectionUri] <Uri[]>]
      [-AsJob]
      [-InDisconnectedSession]
      [-HideComputerName]
      [-JobName <String>]
      [-FilePath] <String>
      [-AllowRedirection]
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      -Credential <PSCredential>
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-ScriptBlock] <ScriptBlock>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-VMId] <Guid[]>
      [<CommonParameters>]

Invoke-Command
      -Credential <PSCredential>
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-ScriptBlock] <ScriptBlock>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -VMName <String[]>
      [<CommonParameters>]

Invoke-Command
      -Credential <PSCredential>
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-VMId] <Guid[]>
      [<CommonParameters>]

Invoke-Command
      -Credential <PSCredential>
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -VMName <String[]>
      [<CommonParameters>]

Invoke-Command
      [-Port <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      -HostName <String[]>
      [-UserName <String>]
      [-KeyFilePath <String>]
      [-Subsystem <String>]
      [-ConnectingTimeout <Int32>]
      [-SSHTransport]
      [-Options <Hashtable>]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      [-RunAsAdministrator]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -ContainerId <String[]>
      [<CommonParameters>]

Invoke-Command
      [-ConfigurationName <String>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-FilePath] <String>
      [-RunAsAdministrator]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -ContainerId <String[]>
      [<CommonParameters>]

Invoke-Command
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      -SSHConnection <Hashtable[]>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      -HostName <String[]>
      [-UserName <String>]
      [-KeyFilePath <String>]
      [-Subsystem <String>]
      [-ConnectingTimeout <Int32>]
      [-SSHTransport]
      [-Options <Hashtable>]
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      -SSHConnection <Hashtable[]>
      [-RemoteDebug]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Description

O Invoke-Command cmdlet executa comandos em um computador local ou remoto e retorna toda a saída dos comandos, incluindo erros. Usando um único Invoke-Command comando, 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 New-PSSession cmdlet para criar uma PSSession (uma conexão persistente) no computador remoto e use o parâmetro Session de Invoke-Command 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 os parâmetros HostName ou 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 Test.ps1 script 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 ao computador local.

Exemplo 2: Executar um comando em um servidor remoto

Este exemplo executa um Get-Culture comando 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 Get-Culture comando 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 New-PSSession cmdlet cria uma sessão no computador remoto Server02 e a salva na $s variável. Normalmente, você cria uma sessão somente quando executa uma série de comandos no computador remoto.

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

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 dos parâmetros ComputerName e Session do Invoke-Command. Ele mostra como utilizar 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 Get-Process cmdlet para obter o processo do PowerShell no computador remoto e salvá-lo na $p variável. 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 é fechada quando o comando é concluído. A $p variável 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 os dois comandos na mesma sessão.

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

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

Este exemplo mostra como executar um comando 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 $command variável armazena o Get-WinEvent comando formatado como um bloco de script. O Invoke-Command executa o comando armazenado nos $command 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, você não precisa 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 Get-Content cmdlet para obter o conteúdo do arquivo Machine.txt, um arquivo de nomes de computador.

O Invoke-Command cmdlet executa um Get-Host comando nos computadores remotos. Ele usa notação de ponto para obter a propriedade Version 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 $version variável. A saída inclui o nome do computador de origem de dados.

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

Este exemplo executa um comando em dois computadores remotos. O Invoke-Command comando 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 New-PSSession cmdlet cria sessões nos computadores remotos Server01 e Server02. O Invoke-Command cmdlet 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. Esse 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 Get-Job comando salva o objeto de trabalho na $j variável. A $j variável é então canalizada para o Format-List cmdlet 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 para $j o Receive-Job cmdlet e armazena os resultados na $results variável.

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

Este exemplo mostra como incluir os valores das variáveis locais em um comando executado em um computador remoto. O comando usa o Using modificador de escopo para identificar uma variável local em um comando remoto. Por padrão, todas as variáveis devem ser 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 Using escopo, consulte about_Remote_Variables e about_Scopes.

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

A $Log variável armazena o nome do log de eventos, PowerShellCore/Operational. O Invoke-Command cmdlet é executado Get-WinEvent no Server01 para obter os dez eventos mais recentes do log de eventos. O valor do parâmetro LogName é a variável prefixada $LogUsing pelo modificador de escopo para indicar que ele foi criado 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. Ele muda apenas a exibição. 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 são usados Invoke-Command para executar um Get-Process comando 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 Param palavra-chave 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 .pdf extensão.

Para obter mais informações sobre a Param palavra-chave, 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, Name e Include 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 $args variável automática e o parâmetro ArgumentList são usados para passar valores de matriz para posições de parâmetro em um bloco de script. Este exemplo exibe o conteúdo dos arquivos do diretório de .txt um servidor. O Get-ChildItemparâmetro Path é a posição 0 e o parâmetro Filter é a posição 1.

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

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

Este exemplo usa o Invoke-Command cmdlet para executar o Sample.ps1 script em todos os computadores listados no Servers.txt arquivo. O comando usa o parâmetro FilePath para especificar o arquivo de script. Esse 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 Sample.ps1 conteúdo do arquivo é copiado em um bloco de script e o bloco de script é executado em cada um dos computadores remotos. Esse procedimento é equivalente ao uso do 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 específico executa um Set-Mailbox comando em um servidor Exchange remoto.

$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 para armazenar credenciais do Get-Credential$LiveCred Windows Live ID na variável. O PowerShell solicita que o usuário insira credenciais do Windows Live ID.

A $parameters variável é uma tabela de hash que contém os parâmetros a serem passados para o Invoke-Command cmdlet. O Invoke-Command cmdlet executa um Set-Mailbox 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 $LiveCred variável. 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 New-PSSessionOption cmdlet 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 $so variável.

Observação

Desabilitar essas verificações é conveniente para solução de problemas, mas obviamente não é seguro.

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

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

O Invoke-Command cmdlet executa um Get-Mailbox comando 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 $max variável.

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 encerramento.

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

Este exemplo mostra como acessar um compartilhamento de rede 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 o PowerShell Remoting oferece suporte a saltos entre computadores, consulte Criando o segundo salto no PowerShell Remoting.

A delegação necessária do CredSSP (Credential Security Support Provider) 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 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 Enable-WSManCredSSP cmdlet habilita 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 $s objeto na variável.

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

A $parameters variável contém os valores de parâmetro para se conectar ao compartilhamento de rede. O Invoke-Command cmdlet executa um Get-Item comando na sessão em $s. Esse comando obtém um script do \\Net03\Scripts compartilhamento de rede. 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 de cada computador. O script continuará 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 é usado Invoke-Command para executar o script. O valor do parâmetro ComputerName é um Get-Content 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 executado Invoke-Command 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 Receive-PSSession cmdlet.

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 de 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 será solicitada uma senha, a menos que a autenticação de chave falhe e o computador remoto esteja configurado para permitir a autenticação básica de senha.

$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 conjunto de parâmetros SSHConnection . 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 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 tabela de hash de valores que são passados como opções para o comando subjacente ssh que estabeleceu a conexão 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

Permite o redirecionamento da conexão para um URI (Uniform Resource Identifier) alternativo.

Quando você usa o parâmetro ConnectionURI , o destino remoto pode retornar uma instrução para redirecionar para um URI diferente. Por padrão, o PowerShell não redireciona conexões, mas você pode usar esse parâmetro para permitir que ele redirecione a conexão.

Você também pode limitar o número de vezes que a conexão é redirecionada alterando o valor da opção de sessão MaximumConnectionRedirectionCount . Use o parâmetro MaximumRedirection do New-PSSessionOption cmdlet ou defina a propriedade MaximumConnectionRedirectionCount da $PSSessionOption variável de preferência. O valor padrão é 5.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ApplicationName

Especifica o segmento de nome de aplicativo do URI de conexão. Use esse parâmetro para especificar o nome do aplicativo quando você não estiver usando o parâmetro ConnectionURI no comando.

O valor padrão é o $PSSessionApplicationName valor da variável de preferência no computador local. Se essa variável de preferência não estiver definida, o valor padrão será WSMAN. Esse valor é adequado para a maioria dos usos. Para obter mais informações, consulte about_Preference_Variables.

O serviço WinRM usa o nome do aplicativo para selecionar um ouvinte para atender à solicitação de conexão. O valor desse parâmetro deve corresponder ao valor da propriedade URLPrefix de um ouvinte no computador remoto.

Type:	String
Position:	Named
Default value:	$PSSessionApplicationName if set on the local computer, otherwise WSMAN
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-ArgumentList

Fornece os valores dos parâmetros para o scriptblock. Os parâmetros no bloco de script são passados por posição do valor da matriz fornecido a ArgumentList. Isso é conhecido como array splatting. Para obter mais informações sobre o comportamento de ArgumentList, consulte about_Splatting.

Type:	Object[]
Aliases:	Args
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-AsJob

Indica que esse cmdlet executa o comando como um trabalho em segundo plano em um computador remoto. Use esse parâmetro para executar comandos que levam muito tempo para serem concluídos.

Quando você usa o parâmetro AsJob , o comando retorna um objeto que representa o trabalho e, em seguida, exibe o prompt de comando. É possível continuar a trabalhar na sessão enquanto o trabalho é concluído. Para gerenciar o trabalho, use os *-Job cmdlets. Para obter os resultados do trabalho, use o Receive-Job cmdlet.

O parâmetro AsJob é semelhante ao uso do Invoke-Command cmdlet para executar um Start-Job cmdlet remotamente. No entanto, com AsJob, o trabalho é criado no computador local, mesmo que o trabalho seja executado em um computador remoto. Os resultados do trabalho remoto são retornados automaticamente ao computador local.

Para obter mais informações sobre trabalhos em segundo plano do PowerShell, consulte about_Jobs e about_Remote_Jobs.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Authentication

Especifica o mecanismo usado para autenticar as credenciais do usuário. A autenticação CredSSP está disponível somente no Windows Vista, Windows Server 2008 e versões posteriores do sistema operacional Windows.

Os valores aceitáveis para esse parâmetro são os seguintes:

Padrão
Basic
Credssp
Digest
Kerberos
Negotiate
NegotiateWithImplicitCredential

O valor padrão é Default.

Para obter mais informações sobre os valores desse parâmetro, consulte AuthenticationMechanism Enumeration.

Cuidado

A autenticação CredSSP (Credential Security Support Provider), na qual as credenciais do usuário são passadas para um computador remoto para serem autenticadas, foi projetada para comandos que exigem autenticação em mais de um recurso, como acessar um compartilhamento de rede remoto. Esse mecanismo aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, as credenciais que são passadas a ele podem ser usadas para controlar a sessão de rede. Para obter mais informações, consulte Provedor de suporte de segurança de credenciais.

Type:	AuthenticationMechanism
Accepted values:	Basic, Default, Credssp, Digest, Kerberos, Negotiate, NegotiateWithImplicitCredential
Position:	Named
Default value:	Default
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-CertificateThumbprint

Especifica o certificado de chave pública digital (X509) de uma conta de usuário com permissão para se conectar à sessão desconectada. Insira a impressão digital do certificado.

Os certificados são utilizados na autenticação baseada em certificado do cliente. Eles podem ser mapeados apenas para contas de usuário locais e não funcionam com contas de domínio.

Para obter uma impressão digital de certificado, use um Get-Item comando ou Get-ChildItem na unidade PowerShell Cert:.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ComputerName

Especifica os computadores em que o comando é executado. O padrão é o computador local.

Quando você usa o parâmetro ComputerName, o PowerShell cria uma conexão temporária que é usada apenas para executar o comando especificado e, em seguida, é fechada. Se você precisar de uma conexão persistente, use o parâmetro Session .

Digite o nome da NETBIOS, o endereço IP ou o nome de domínio totalmente qualificado de um ou mais computadores em uma lista separada por vírgulas. Para especificar o computador local, digite o nome do computador, localhost ou um ponto (.).

Para usar um endereço IP no valor de ComputerName, o comando deve incluir o parâmetro Credential . O computador deve ser configurado para o transporte HTTPS ou o endereço IP do computador remoto deve ser incluído na lista WinRM TrustedHosts do computador local. Para obter instruções sobre como adicionar um nome de computador à lista TrustedHosts , consulte Como adicionar um computador à lista de hosts confiáveis.

No Windows Vista e em versões posteriores do sistema operacional Windows, para incluir o computador local no valor de NomeDoComputador, você deve executar o PowerShell usando a opção Executar como administrador .

Type:	String[]
Aliases:	Cn
Position:	0
Default value:	Local computer
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ConfigurationName

Especifica a configuração de sessão usada para o novo PSSession.

Insira um nome de configuração ou o URI do recurso totalmente qualificado para uma configuração de sessão. Se você especificar apenas o nome da configuração, o seguinte URI do esquema será suspenso: http://schemas.microsoft.com/PowerShell.

Quando usado com SSH, esse parâmetro especifica o subsistema a ser usado no destino, conforme definido em sshd_config. O valor padrão para SSH é o powershell subsistema.

A configuração da sessão para uma sessão está localizada no computador remoto. Se a configuração de sessão especificada não existir no computador remoto, o comando falhará.

O valor padrão é o $PSSessionConfigurationName valor da variável de preferência no computador local. Se essa variável de preferência não estiver definida, o padrão será Microsoft.PowerShell. Para obter mais informações, consulte about_Preference_Variables.

Type:	String
Position:	Named
Default value:	$PSSessionConfigurationName if set on the local computer, otherwise Microsoft.PowerShell
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-ConnectingTimeout

Especifica a quantidade de tempo, em milissegundos, permitida para que a conexão SSH inicial seja concluída. Se a conexão não for concluída dentro do tempo especificado, um erro será retornado.

Esse parâmetro foi introduzido no PowerShell 7.2

Type:	Int32
Position:	Named
Default value:	Unlimited
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ConnectionUri

Especifica um URI (Uniform Resource Identifier) que define o ponto de extremidade de conexão da sessão. O URI deve ser totalmente qualificado.

O formato dessa cadeia de caracteres é o seguinte:

<Transport>://<ComputerName>:<Port>/<ApplicationName>

O valor padrão é o seguinte:

http://localhost:5985/WSMAN

Se você não especificar um URI de conexão, poderá usar os parâmetros UseSSL e Port para especificar os valores de URI de conexão.

Os valores válidos para o segmento Transporte do URI são HTTP e HTTPS. Se você especificar um URI de conexão com um segmento de Transporte, mas não especificar uma porta, a sessão será criada com as portas padrão: 80 para HTTP e 443 para HTTPS. Para usar as portas padrão para comunicação remota do PowerShell, especifique a porta 5985 para HTTP ou 5986 para HTTPS.

Se o computador de destino redireciona a conexão para um URI diferente, o PowerShell impede o redirecionamento, a menos que você use o parâmetro AllowRedirection no comando.

Type:	Uri[]
Aliases:	URI, CU
Position:	0
Default value:	http://localhost:5985/WSMAN
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ContainerId

Especifica uma matriz de IDs de contêiner.

Type:	String[]
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-Credential

Especifica uma conta de usuário que tem permissão para executar esta ação. O padrão é o usuário atual.

Digite um nome de usuário, como User01 ou Domain01\User01, ou insira um objeto PSCredential gerado pelo Get-Credential cmdlet. Se você digitar um nome de usuário, será solicitado que você insira a senha.

As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.

Observação

Para obter mais informações sobre a proteção de dados do SecureString , consulte Quão seguro é o SecureString?.

Type:	PSCredential
Position:	Named
Default value:	Current user
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-EnableNetworkAccess

Indica que esse cmdlet adiciona um token de segurança interativo às sessões de loopback. O token interativo permite executar comandos na sessão de loopback que obtêm dados de outros computadores. Por exemplo, você pode executar um comando na sessão que copia arquivos XML de um computador remoto no computador local.

Uma sessão de loopback é um PSSession que se origina e termina no mesmo computador. Para criar uma sessão de loopback, omita o parâmetro ComputerName ou defina seu valor como dot (.), localhost ou o nome do computador local.

Por padrão, as sessões de loopback são criadas usando um token de rede, que pode não fornecer permissão suficiente para autenticação em computadores remotos.

O parâmetro EnableNetworkAccess é efetivo somente em sessões de loopback. Se você usar EnableNetworkAccess ao criar uma sessão em um computador remoto, o comando será bem-sucedido, mas o parâmetro será ignorado.

Você pode permitir o acesso remoto em uma sessão de loopback usando o valor CredSSP do parâmetro Authentication, que delega as credenciais da sessão a outros computadores.

Para proteger o computador contra acesso mal-intencionado, as sessões de loopback desconectadas que têm tokens interativos, que são aqueles criados usando EnableNetworkAccess, podem ser reconectadas somente do computador no qual a sessão foi criada. Sessões desconectadas que usam a autenticação CredSSP podem ser reconectadas por meio de outros computadores. Para obter mais informações, consulte Disconnect-PSSession.

Esse parâmetro foi introduzido no PowerShell 3.0.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-FilePath

Especifica um script local que esse cmdlet executa em um ou mais computadores remotos. Insira o caminho e o nome do arquivo do script ou canalize um caminho de script para Invoke-Command. O script deve existir no computador local ou em um diretório que o computador local possa acessar. Use ArgumentList para especificar os valores dos parâmetros no script.

Quando você usa esse parâmetro, o PowerShell converte o conteúdo do arquivo de script especificado em um bloco de script, transmite o bloco de script para o computador remoto e o executa no computador remoto.

Type:	String
Aliases:	PSPath
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-HideComputerName

Indica que esse cmdlet omite o nome do computador de cada objeto da exibição de saída. Por padrão, o nome do computador que gerou o objeto aparece na exibição.

Este parâmetro afeta somente a exibição de saída. Ele não altera o objeto.

Type:	SwitchParameter
Aliases:	HCN
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-HostName

Especifica uma matriz de nomes de computador para uma conexão baseada em SSH (Secure Shell). Isso é semelhante ao parâmetro ComputerName , exceto que a conexão com o computador remoto é feita usando SSH em vez do Windows WinRM.

Esse parâmetro foi introduzido no PowerShell 6.0.

Type:	String[]
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-InDisconnectedSession

Indica que esse cmdlet executa um comando ou script em uma sessão desconectada.

Quando você usa o parâmetro InDisconnectedSession , Invoke-Command cria uma sessão persistente em cada computador remoto, inicia o comando especificado pelo parâmetro ScriptBlock ou FilePath e se desconecta da sessão. Os comandos continuam a ser executados nas sessões desconectadas. InDisconnectedSession permite executar comandos sem manter uma conexão com as sessões remotas. E, como a sessão é desconectada antes que qualquer resultado seja retornado, InDisconnectedSession garante que todos os resultados do comando sejam retornados para a sessão reconectada, em vez de serem divididos entre sessões.

Não é possível usar InDisconnectedSession com o parâmetro Session ou o parâmetro AsJob.

Os comandos que usam InDisconnectedSession retornam um objeto PSSession que representa a sessão desconectada. Eles não retornam a saída do comando. Para se conectar à sessão desconectada, use os Connect-PSSession cmdlets ou Receive-PSSession . Para obter os resultados dos comandos executados na sessão, use o Receive-PSSession cmdlet. Para executar comandos que geram saída em uma sessão desconectada, defina o valor da opção de sessão OutputBufferingMode como Drop. Se você pretende se conectar à sessão desconectada, defina o tempo limite ocioso na sessão para que ele forneça tempo suficiente para que você se conecte antes de excluir a sessão.

Você pode definir o modo de buffer de saída e o tempo limite ocioso no parâmetro SessionOption ou na $PSSessionOption variável de preferência. Para obter mais informações sobre opções de sessão, consulte New-PSSessionOption e about_Preference_Variables.

Para obter mais informações sobre o recurso Sessões Desconectadas, consulte about_Remote_Disconnected_Sessions.

Esse parâmetro foi introduzido no PowerShell 3.0.

Type:	SwitchParameter
Aliases:	Disconnected
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InputObject

Especifica a entrada para o comando. Insira uma variável que contém os objetos ou digite um comando ou uma expressão que obtém os objetos.

Ao usar o parâmetro InputObject, use a $Input variável automática no valor do parâmetro ScriptBlock para representar os objetos de entrada.

Type:	PSObject
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	True
Accept wildcard characters:	False

-JobName

Especifica um nome amigável para o trabalho em segundo plano. Por padrão, os trabalhos são nomeados Job<n>, onde <n> é um número ordinal.

Se você usar o parâmetro JobName em um comando, o comando será executado como um trabalho e Invoke-Command retornará um objeto de trabalho, mesmo que você não inclua AsJob no comando.

Para obter mais informações sobre trabalhos em segundo plano do PowerShell, consulte about_Jobs.

Type:	String
Position:	Named
Default value:	Job<n>
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-KeyFilePath

Especifica um caminho de arquivo de chave usado pelo Secure Shell (SSH) para autenticar um usuário em um computador remoto.

O SSH permite que a autenticação do usuário seja realizada por meio de chaves privadas e públicas como uma alternativa à autenticação básica de senha. Se o computador remoto estiver configurado para autenticação de chave, esse parâmetro poderá ser usado para fornecer a chave que identifica o usuário.

Esse parâmetro foi introduzido no PowerShell 6.0.

Type:	String
Aliases:	IdentityFilePath
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-NoNewScope

Indica que esse cmdlet executa o comando especificado no escopo atual. Por padrão, Invoke-Command executa comandos em seu próprio escopo.

Esse parâmetro é válido somente em comandos executados na sessão atual, ou seja, comandos que omitem os parâmetros ComputerName e Session .

Esse parâmetro foi introduzido no PowerShell 3.0.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Options

Especifica uma tabela de hash de opções SSH usadas ao se conectar a uma sessão remota baseada em SSH. As opções possíveis são quaisquer valores suportados pela versão baseada em Unix do comando ssh .

Quaisquer valores explicitamente passados por parâmetros têm precedência sobre os valores passados na tabela de hash Opções . Por exemplo, o uso do parâmetro Port substitui qualquer Port par chave-valor passado na tabela de hash Options .

Esse parâmetro foi adicionado no PowerShell 7.3.

Type:	Hashtable
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Port

Especifica a porta de rede no computador remoto usada para esse comando. Para se conectar a um computador remoto, este deve estar escutando na porta usada pela conexão. As portas padrão são 5985 (porta WinRM para HTTP) e 5986 (porta WinRM para HTTPS).

Antes de usar uma porta alternativa, configure o ouvinte WinRM no computador remoto para escutar na porta. Para configurar o ouvinte, digite os dois comandos a seguir no prompt do PowerShell:

Remove-Item -Path WSMan:\Localhost\listener\listener* -Recurse

New-Item -Path WSMan:\Localhost\listener -Transport http -Address * -Port \<port-number\>

Não use o parâmetro Port, a menos que seja necessário. A porta que está definida no comando se aplica a todos os computadores ou sessões em que o comando é executado. Uma configuração de porta alternativa pode impedir que o comando seja executado em todos os computadores.

Type:	Int32
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-RemoteDebug

Usado para executar o comando invocado no modo de depuração na sessão remota do PowerShell.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-RunAsAdministrator

Indica que esse cmdlet invoca um comando como Administrador.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ScriptBlock

Especifica os comandos a serem executados. Coloque os comandos entre chaves ({ }) para criar um bloco de script. Ao usar Invoke-Command para executar um comando remotamente, todas as variáveis no comando são avaliadas no computador remoto.

Observação

Os parâmetros para o scriptblock só podem ser passados de ArgumentList por posição. Os parâmetros do switch não podem ser passados pela posição. Se você precisar de um parâmetro que se comporte como um tipo SwitchParameter , use um tipo booleano .

Type:	ScriptBlock
Aliases:	Command
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Session

Especifica uma matriz de sessões nas quais esse cmdlet executa o comando. Insira uma variável que contenha objetos PSSession ou um comando que crie ou obtenha os objetos PSSession , como um New-PSSession comando ou Get-PSSession .

Quando você cria um PSSession, o PowerShell estabelece uma conexão persistente com o computador remoto. Use um PSSession para executar uma série de comandos relacionados que compartilham dados. Para executar um único comando ou uma série de comandos não relacionados, use o parâmetro ComputerName . Para obter mais informações, consulte about_PSSessions.

Type:	PSSession[]
Position:	0
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SessionName

Especifica um nome amigável para uma sessão desconectada. Você pode usar o nome para se referir à sessão em comandos subsequentes, como um Get-PSSession comando. Esse parâmetro é válido somente com o parâmetro InDisconnectedSession .

Esse parâmetro foi introduzido no PowerShell 3.0.

Type:	String[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SessionOption

Especifica opções avançadas para a sessão. Insira um objeto SessionOption , como um que você cria usando o New-PSSessionOption cmdlet, ou uma tabela de hash na qual as chaves são nomes de opção de sessão e os valores são valores de opção de sessão.

Observação

Se você especificar uma hashtable para SessionOption, o PowerShell converterá a hashtable em um objeto System.Management.Autiomation.Remoting.PSSessionOption . Os valores para chaves especificadas na tabela de hash são convertidos para a propriedade correspondente do objeto. Isso se comporta de forma diferente de chamar New-PSSessionOption. Por exemplo, os valores System.TimeSpan para as propriedades de tempo limite, como IdleTimeout, convertem um valor inteiro em ticks em vez de milissegundos. Para obter mais informações sobre o objeto PSSessionOption e suas propriedades, consulte PSSessionOption

Os valores padrão para as opções são determinados pelo valor da variável de $PSSessionOption preferência, se ela estiver definida. Caso contrário, os valores padrão são estabelecidos por opções definidas na configuração da sessão.

Os valores de opção de sessão têm precedência sobre os $PSSessionOption valores padrão para sessões definidas na variável de preferência e na configuração da sessão. No entanto, eles não têm precedência sobre valores máximos, cotas ou limites definidos na configuração da sessão.

Para obter uma descrição das opções de sessão que inclui os valores padrão, consulte New-PSSessionOption. Para obter informações sobre a variável de $PSSessionOption preferência, consulte about_Preference_Variables. Para saber mais sobre configurações de sessão, confira about_Session_Configurations.

Type:	PSSessionOption
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SSHConnection

Esse parâmetro usa uma matriz de tabelas de hash em que cada tabela de hash contém um ou mais parâmetros de conexão necessários para estabelecer uma conexão SSH (Secure Shell). O parâmetro SSHConnection é útil para criar várias sessões em que cada sessão requer informações de conexão diferentes.

A hashtable tem os seguintes membros:

ComputerName (ou HostName)
Porta
UserName
KeyFilePath (ou IdentityFilePath)

ComputerName (ou HostName) é o único par chave-valor necessário.

Esse parâmetro foi introduzido no PowerShell 6.0.

Type:	Hashtable[]
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-SSHTransport

Indica que a conexão remota é estabelecida usando Secure Shell (SSH).

Por padrão, o PowerShell usa o Windows WinRM para se conectar a um computador remoto. Essa opção força o PowerShell a usar o parâmetro HostName para estabelecer uma conexão remota baseada em SSH.

Esse parâmetro foi introduzido no PowerShell 6.0.

Type:	SwitchParameter
Accepted values:	true
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Subsystem

Especifica o subsistema SSH usado para o novo PSSession.

Isso especifica o subsistema a ser usado no destino, conforme definido em sshd_config. O subsistema inicia uma versão específica do PowerShell com parâmetros predefinidos. Se o subsistema especificado não existir no computador remoto, o comando falhará.

Se esse parâmetro não for usado, o padrão será o powershell subsistema.

Type:	String
Position:	Named
Default value:	powershell
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ThrottleLimit

Especifica o número máximo de conexões simultâneas que podem ser estabelecidas para executar o comando. Se você omite esse parâmetro ou digita um valor 0, o valor padrão, 32, é usado.

O limite de aceleração aplica-se somente ao comando atual e não à sessão ou ao computador.

Type:	Int32
Position:	Named
Default value:	32
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UserName

Especifica o nome de usuário da conta usada para executar um comando no computador remoto. O método de autenticação do usuário depende de como o Secure Shell (SSH) está configurado no computador remoto.

Se o SSH estiver configurado para autenticação de senha básica, a senha do usuário será solicitada.

Se o SSH estiver configurado para autenticação de usuário baseada em chave, um caminho de arquivo de chave poderá ser fornecido por meio do parâmetro KeyFilePath e nenhum prompt de senha ocorrerá. Se o arquivo de chave de usuário do cliente estiver localizado em um local conhecido SSH, o parâmetro KeyFilePath não será necessário para autenticação baseada em chave e a autenticação do usuário ocorrerá automaticamente com base no nome de usuário. Para obter mais informações, consulte a documentação SSH da sua plataforma sobre autenticação de usuário baseada em chave.

Este não é um parâmetro obrigatório. Se o parâmetro UserName não for especificado, o nome de usuário conectado atual será usado para a conexão.

Esse parâmetro foi introduzido no PowerShell 6.0.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-UseSSL

Indica que esse cmdlet usa o protocolo SSL (Secure Sockets Layer) para estabelecer uma conexão com o computador remoto. Por padrão, o SSL não é usado.

O WS-Management criptografa todo o conteúdo do PowerShell transmitido pela rede. O parâmetro UseSSL é uma proteção adicional que envia os dados através de um HTTPS, em vez de HTTP.

Se você usar esse parâmetro, mas o SSL não estiver disponível na porta usada para o comando, o comando falhará.

Type:	SwitchParameter
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-VMId

Especifica uma matriz de IDs de máquinas virtuais.

Type:	Guid[]
Aliases:	VMGuid
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-VMName

Especifica uma matriz de nomes de máquinas virtuais.

Type:	String[]
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

Entradas

ScriptBlock

Você pode canalizar um comando em um bloco de script para Invoke-Command. Use a $Input variável automática 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 invocado, que é o valor do parâmetro ScriptBlock .

Observações

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 de Invoke-Command para executar um comando no computador local, você deve executar o PowerShell usando a opção Executar como administrador .

Quando você executa comandos em vários computadores, o PowerShell se conecta aos computadores na ordem em que eles 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 executado Invoke-Command são incluídos nos resultados do comando. Erros que poderiam ser erros de finalização em um comando local são tratados como erros de não finalização em um comando remoto. Essa estratégia garante que o encerramento de erros em um computador não feche o comando em todos os computadores em que ele é executado. Essa prática é utilizada mesmo quando um comando remoto é executado em um único computador.

Se o computador remoto não estiver em um domínio no qual o computador local confia, talvez o computador não consiga autenticar as credenciais do usuário. Para adicionar o computador remoto à lista de hosts confiáveis no WS-Management, use o WSMAN seguinte comando no provedor, 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 está desconectado de todas as sessões. Ela pode ser conectada a uma sessão diferente. Para determinar se você pode se conectar ou se reconectar à sessão, use a propriedade Availability .

Um valor de Disponibilidade 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 das sessões, consulte RunspaceState. Para obter mais informações sobre os valores da propriedade Availability das 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 têm suporte em várias plataformas (Windows, Linux, macOS) e a comunicação remota do PowerShell funciona nessas plataformas em que o PowerShell e o SSH são instalados e configurados. Isso é separado da comunicação remota anterior do Windows que é baseada no WinRM e muitos dos recursos e limitações específicos do WinRM não se aplicam. Por exemplo, cotas baseadas em 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 ssh executável obtém dados de configuração das seguintes fontes na seguinte ordem:

Opções de linha de comando
arquivo de configuração do usuário (~/.ssh/config)
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 de cmdlet	parâmetro ssh	opção equivalente ssh -o
`-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>`

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

Invoke-Command

Syntax

Description

Exemplos

Exemplo 1: Executar um script em um servidor

Exemplo 2: Executar um comando em um servidor remoto

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

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

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

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

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

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

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

Exemplo 10: Ocultar o nome do computador

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

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

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

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

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

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

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

Exemplo 18: Iniciar scripts em muitos computadores remotos

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

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

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

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

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

Saídas

Observações

Links Relacionados

Comentários

Recursos adicionais