Invoke-Command

Invoke-Command [-ScriptBlock] <scriptblock> [[-ComputerName] <string[]>] [-ApplicationName <string>] [-AsJob] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-HideComputerName] [-JobName <string>] [-Port <int>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [-UseSSL] [-ArgumentList <Object[]>] [-InputObject <psobject>] [<CommonParameters>]

Invoke-Command [-FilePath] <string> [[-ComputerName] <string[]>] [-ApplicationName <string>] [-AsJob] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-ConfigurationName <string>] [-Credential <PSCredential>] [-HideComputerName] [-JobName <string>] [-Port <int>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [-UseSSL] [-ArgumentList <Object[]>] [-InputObject <psobject>] [<CommonParameters>]

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

Invoke-Command [-FilePath] <string> [[-ConnectionURI] <Uri[]>] [-AllowRedirection] [-AsJob] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-ConfigurationName <string>] [-Credential <PSCredential>] [-HideComputerName] [-JobName <string>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [-ArgumentList <Object[]>] [-InputObject <psobject>] [<CommonParameters>]

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

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

Invoke-Command [-ScriptBlock] <scriptblock> [[-ConnectionURI] <Uri[]>] [-AllowRedirection] [-AsJob] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-HideComputerName] [-JobName <string>] [-SessionOption <PSSessionOption>] [-ThrottleLimit <int>] [-ArgumentList <Object[]>] [-InputObject <psobject>] [<CommonParameters>]

C:\PS>invoke-command -filepath c:\scripts\test.ps1 -computerName Server01

Disks: C:, D:, E:
Status: Warning, Normal, Normal

Descrição
-----------
Esse comando executa o script Test.ps1 no computador Server01. 

O comando usa o parâmetro FilePath para especificar um script que é encontrado no computador local. O script é executado no computador remoto e os resultados são retornados ao computador local.

C:\PS>invoke-command -computername server01 -credential domain01\user01 -scriptblock {get-culture}

Descrição
-----------
Esse comando executa um comando Get-Culture no computador remoto Server01. 

Usa o parâmetro ComputerName para especificar o nome do computador e o parâmetro Credential para executar o comando no contexto de segurança de "Domain01\User01", um usuário com permissão para executar comandos. Usa o parâmetro ScriptBlock para especificar o comando a ser executado no computador remoto.

Em resposta, o Windows PowerShell exibe uma caixa de diálogo que solicita a senha e um método de autenticação para a conta User01. Ele, em seguida, executa o comando no computador Server01 e retorna o resultado.

C:\PS>$s = new-pssession -computername server02 -credential domain01\user01

C:\PS> invoke-command -session $s -scriptblock {get-culture}

Descrição
-----------
Esse exemplo executa o mesmo comando "Get-Culture" em uma sessão (uma conexão persistente) no computador remoto Server02. Normalmente, você só cria uma sessão quando está executando uma série de comandos no computador remoto.

O primeiro comando usa o cmdlet New-PSSession para criar uma sessão no computador remoto Server02. Em seguida, ele salva a sessão na variável $s.

O segundo comando usa o cmdlet Invoke-Command para executar o comando Get-Culture no Server02. Ele usa o parâmetro Session para especificar a sessão salva na variável $s. 

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

C:\PS>invoke-command -computername Server02 -scriptblock {$p = get-process powershell}

C:\PS> invoke-command -computername Server02 -scriptblock {$p.virtualmemorysize}
C:\PS>

C:\PS> $s = new-pssession -computername Server02
C:\PS> invoke-command -session $s -scriptblock {$p = get-process powershell}
C:\PS> invoke-command -session $s -scriptblock {$p.virtualmemorysize}
17930240

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

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

O primeiro comando obtém êxito. Mas o segundo comando falha porque, quando você usa o parâmetro ComputerName, o Windows PowerShell cria uma conexão apenas para executar o comando. Em seguida, fecha a conexão quando o comando for concluído. A variável $p foi criada em uma conexão, mas ela não existe na conexão criada para o segundo comando.

O problema é resolvido com a criação de uma sessão (uma conexão persistente) no computador remoto e a execução de ambos os comandos relacionados na mesma sessão.

O terceiro comando usa o cmdlet New-PSSession para criar uma sessão no computador Server02. Em seguida, ele salva a sessão na variável $s. O quarto e o quinto comandos repetem a série de comandos usada no primeiro conjunto, mas, neste caso, o comando Invoke-Command usa o parâmetro Session para executar ambos os comandos na mesma sessão. 

Neste caso, como ambos os comandos são executados na mesma sessão, os comandos têm sucesso e o valor $p permanece ativo na sessão $s para uso posterior.

C:\PS>$command = { get-eventlog -log "windows powershell" | where {$_.message -like "*certificate*"} }

C:\PS> invoke-command -computername S1, S2 -scriptblock $command

Descrição
-----------
Esse exemplo mostra como inserir um comando que é salvo em uma variável local. 

Quando o comando inteiro é salvo em uma variável local, você pode especificar a variável como o valor do parâmetro ScriptBlock. Você não precisa usar a palavra-chave "param" ou a variável ArgumentList para enviar o valor da variável local.

O primeiro comando salva um comando Get-Eventlog na variável $command. O comando é formatado como um bloco de scripts.

O segundo comando usa o cmdlet Invoke-Command para executar o comando em $command nos computadores remotos S1 e S2.

C:\PS>invoke-command -computername server01, server02, TST-0143, localhost -configurationname MySession.PowerShell -scriptblock {get-eventlog "windows powershell"}

Descrição
-----------
Esse exemplo demonstra como usar o cmdlet Invoke-Command para executar um único comando em vários computadores. 

O comando usa o parâmetro ComputerName para especificar os computadores. Os nomes de computadores são apresentados em uma lista separada por vírgula. A lista de computadores inclui o valor "localhost", que representa o computador local.

O comando usa o parâmetro ConfigurationName para especificar uma configuração de sessão alternativa para o Windows PowerShell e o parâmetro ScriptBlock para especificar o comando.

Nesse exemplo, o comando no bloco de scripts obtém os eventos do log de evento do Windows PowerShell em cada computador remoto.

C:\PS>$version = invoke-command -computername (get-content machines.txt) -scriptblock {(get-host).version}

Descrição
-----------
Esse comando obtém a versão do host do Windows PowerShell em execução em 200 computadores remotos. 

Como somente um comando é executado, não é necessário criar conexões persistentes (sessões) para cada um dos computadores. Em vez disso, o comando usa o parâmetro ComputerName para indicar os computadores.

O comando utiliza o cmdlet Invoke-Command para executar um comando Get-Host. Ele usa notação de ponto para obter a propriedade Version do host do Windows PowerShell.

Para especificar os computadores, ele usa o cmdlet Get-Content para obter o conteúdo do arquivo Machine.txt, um arquivo de nomes de computadores.

Esses comandos são executados de modo síncrono (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 no qual os dados têm origem.

C:\PS>$s = new-pssession -computername Server01, Server02

C:\PS> invoke-command -session $s -scriptblock {get-eventlog system} -AsJob

Id   Name    State      HasMoreData   Location           Command
---  ----    -----      -----         -----------        --------             -------
1    Job1    Running    True          Server01,Server02  get-eventlog system


C:\PS> $j = Get-Job

C:\PS> $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  :

C:\PS> $results = $j | Receive-Job

Descrição
-----------
Esses comandos executam um trabalho em segundo plano em dois computadores remotos. Como o comando Invoke-Command usa o parâmetro AsJob, os comandos são executados nos computadores remotos, mas, na verdade, o trabalho reside no computador local e os resultados são transmitidos para o computador local.

O primeiro comando usa o cmdlet New-PSSession para criar sessões nos computadores remotos Server01 e Server02.

O segundo comando usa o cmdlet Invoke-Command para executar 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 filhos, um para cada trabalho executado nos dois computadores remotos.

O terceiro comando usa um comando Get-Job para salvar o objeto de trabalho na variável $j. 

O quarto comando usa um operador de pipeline (|) para enviar o valor da variável $j ao cmdlet Format-List, que exibe todas as propriedades do objeto de trabalho em uma lista.

O quinto comando obtém os resultados dos trabalhos. Ele canaliza o objeto do trabalho em $j para o cmdlet Receive-Job e armazena os resultados na variável $results.

C:\PS>$MWFO-LOg = Microsoft-Windows-Forwarding/Operational

C:\PS> invoke-command -computername server01 -scriptblock {param($log, $num) get-eventlog -logname $log -newest $num} -ArgumentList $MWFO-log, 10

Descrição
-----------
Esse exemplo mostra como incluir os valores de variáveis locais em um comando executado em um computador remoto.

O primeiro comando salva o nome do log de eventos Microsoft-Windows-Forwarding/Operational na variável $MWFO-Log.

O segundo comando usa o cmdlet Invoke-Command para executar um comando Get-EventLog no computador remoto Server01 para obter os 10 eventos mais recentes do log de eventos Microsoft-Windows-Forwarding/Operational no Server01.

Esse comando usa a palavra-chave "param" para criar duas variáveis, $log e $num, que são usadas como espaços reservados no comando Get-EventLog. Esses espaços reservados têm nomes arbitrários que não precisam corresponder aos nomes das variáveis locais que fornecem seus valores.

Os valores do parâmetro ArgumentList demonstram as duas diferentes maneiras de especificar valores na lista de argumentos. O valor do espaço reservado $log é a variável $MFWO-Log, definida no primeiro comando. O valor da variável $num é 10.

Antes de o comando ser enviado para o computador remoto, as variáveis são substituídas pelos valores especificados.

C:\PS>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


C:\PS> invoke-command -computername S1, S2 -scriptblock {get-process powershell} -HideComputerName

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

Descrição
-----------
Esse exemplo mostra o efeito de usar o parâmetro HideComputerName de Invoke-Command. 

Os primeiros dois comandos usam o cmdlet 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 o parâmetro HideComputerName, não inclui a coluna PsComputerName.

O uso do parâmetro HideComputerName não altera o objeto. Você ainda pode usar os cmdlets Format para exibir a propriedade PsComputerName de qualquer objeto afetado.

C:\PS>invoke-command -comp (get-content servers.txt) -filepath c:\scripts\sample.ps1 -argumentlist Process, Service

Descrição
-----------
Esse 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. Esse comando permite que você execute o script nos computadores remotos, mesmo se o arquivo de script não estiver acessível aos computadores remotos.

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

C:\PS>$LiveCred = Get-Credential

C:\PS> Invoke-Command -ConfigurationName Microsoft.Exchange `
         -ConnectionUri https://ps.exchangelabs.com/powershell `
         -Credential $LiveCred  -Authentication Basic `
         -scriptblock {Invoke-Command {Set-Mailbox dan -DisplayName "Dan Park"}

Descrição
-----------
Esse exemplo mostra como executar um comando em um computador remoto que é identificado por um URI (endereço na Internet). Este exemplo em particular executa um comando Set-Mailbox em um servidor Exchange remoto. O caractere de crase (`) no comando é o caractere de continuação do Windows PowerShell.

O primeiro comando usa o cmdlet Get-Credential para armazenar credenciais Windows Live ID na variável $LiveCred. Quando a caixa de diálogo de credenciais for exibida, digite as credenciais Windows Live ID.
O segundo comando usa o cmdlet Invoke-Command para executar um comando Set-Mailbox. O comando usa o parâmetro ConfigurationName para especificar que o comando deve ser executado em uma sessão que use a configuração de sessão do Microsoft.Exchange. O parâmetro ConnectionURI especifica a URL do ponto de extremidade do servidor Exchange. 

O parâmetro credential especifica as credenciais do Windows Live armazenadas na variável $LiveCred. O parâmetro AuthenticationMechanism especifica o uso de autenticação básica. O parâmetro ScriptBlock especifica um bloco de scripts que contém o comando.

C:\PS>$max = New-PSSessionOption -MaximumRedirection 1

C:\PS> Invoke-Command -ConnectionUri https://ps.exchangelabs.com/powershell `
         -scriptblock {Invoke-Command {Get-Mailbox dan} `
         -AllowRedirection -SessionOption $max

Descrição
-----------
Esse comando mostra como usar os parâmetros AllowRedirection e SessionOption para gerenciar o redirecionamento de URI em um comando remoto.

O primeiro comando usa o cmdlet New-PSSessionOption para criar um objeto PSSessionOpption que ele salva na variável $max. O comando usa o parâmetro MaximumRedirection para definir a propriedade MaximumConnectionRedirectionCount do objeto PSSessionOption como 1. 

O segundo comando usa o cmdlet Invoke-Command para executar um comando Get-Mailbox em um servidor remoto que esteja executando o Microsoft Exchange Server. O comando usa o parâmetro AllowRedirection para fornecer permissão explícita a fim de redirecionar a conexão a um ponto de extremidade alternativo. Ele também usa o parâmetro SessionOption para especificar o objeto de sessão na variável $max.

Consequentemente, se o computador remoto especificado pelo parâmetro ConnectionURI retornar uma mensagem de redirecionamento, o Windows PowerShell redirecionará a conexão, mas se o novo destino retornar outra mensagem de redirecionamento, o valor 1 de contagem de redirecionamento será excedido, e Invoke-Command retornará um erro não fatal.

C:\PS>$so = New-PSSessionOption -SkipCACheck

PS C:\> invoke-command $s { get-hotfix } -SessionOption $so -credential server01\user01

Descrição
-----------
Esse exemplo mostra como criar e usar um parâmetro SessionOption. 

O primeiro comando usa o cmdlet New-PSSessionOption para criar uma opção de sessão. Ele salva o objeto SessionOption resultante no parâmetro $so.

O segundo comando usa o cmdlet Invoke-Command para executar um comando Get-Hotfix remotamente. O valor do parâmetro SessionOption é o objeto SessionOption na variável $so.

C:\PS>enable-wsmanCredSSP -delegate server02

C:\PS> connect-wsman Server02

C:\PS> set-item wsman:\server02*\service\auth\credSSP -value $true

C:\PS> $s = new-pssession server02

C:\PS> invoke-command -session $s -script {get-item \\Net03\Scripts\LogFiles.ps1} -authentication credssp -credential domain01\admin01

Descrição
-----------
Este exemplo mostra como acessar um compartilhamento de rede de dentro de uma sessão remota. 

O comando requer que a delegação CredSSP seja habilitada nas configurações de cliente no computador local e nas configurações de serviço no computador remoto. Para executar os comando deste exemplo, você deve ser membro do grupo Administradores no computador local e no computador remoto.

O primeiro comando usa o cmdlet Enable-WSManCredSSP para habilitar a delegação CredSSP do computador local Server01 no computador remoto Server02. Isso define a configuração de cliente CredSSP no computador local.

O segundo comando usa o cmdlet Connect-WSman para estabelecer conexão com o computador Server02. Essa ação adiciona um nó para o computador Server02 na unidade WSMan: no computador local, permitindo que você exiba e altere as configurações WS-Management no computador Server02.

O terceiro comando usa o cmdlet Set-Item para alterar o valor do item CredSSP no nó Service do computador Server02 para True. Essa ação habilita CredSSP nas configurações de serviço no computador remoto.

O quarto comando usa o cmdlet New-PSSession para criar uma PSSession no computador Server02. Ele salva a PSSession na variável $s.

O quinto comando usa o cmdlet Invoke-Command para executar um comando Get-Item na sessão em $s que obtém um script do compartilhamento de rede Net03\Scripts. O comando usa o parâmetro Credential e usa o parâmetro Authentication com um valor CredSSP.