Invoke-Command

Executa comandos em computadores locais e remotos.

Sintaxe

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>]

Descrição

O cmdlet Invoke-Command executa comandos em um computador local ou remoto e retorna toda a saída dos comandos, inclusive erros. Com 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, crie uma PSSession (uma conexão persistente) no computador remoto e então use o parâmetro Session de Invoke-Command para executar o comando na PSSession.

Você também pode usar Invoke-Command em um computador local para avaliar ou executar uma cadeia de caracteres em um bloco de scripts como um comando. O Windows PowerShell converte o bloco de scripts em um comando e executa o comando imediatamente no escopo atual, em vez de apenas ecoar a cadeia de caracteres na linha de comando.

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

Parâmetros

-AllowRedirection

Permite o redirecionamento desta conexão para um URI 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 Windows PowerShell não redireciona conexões, mas você pode usar o parâmetro AllowRedirection para permitir que a conexão seja redirecionada.

Também é possível limitar o número de vezes que a conexão é redirecionada configurando a propriedade MaximumConnectionRedirectionCount da variável de preferência $PSSessionOption ou a propriedade MaximumConnectionRedirectionCount do valor do parâmetro SessionOption. O valor padrão é 5. Para obter mais informações, consulte a descrição do parâmetro SessionOption e o tópico da Ajuda referente ao cmdlet New-PSSessionOption.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ApplicationName <string>

Especifica o segmento do nome do 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 padrão é o valor da variável de preferência $PSSessionApplicationName no computador local. Se essa variável de preferência não for 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 uma escuta que atenda à solicitação de conexão. O valor do parâmetro deve corresponder ao valor da propriedade URLPrefix de uma escuta no computador remoto.

Necessário?	false
Posição?	named
Valor padrão	WSMAN
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-ArgumentList <Object[]>

Fornece os valores de variáveis locais no comando. As variáveis do comando são substituídas por esses valores antes de o comando ser executado no computador remoto. Digite os valores em uma lista separada por vírgula. Os valores são associados às variáveis na ordem em que elas são listadas. O alias para ArgumentList é "Args".

Os valores em ArgumentList podem ser valores reais, como "1024", ou podem ser referências a variáveis locais, como "$max".

Para usar variáveis locais em um comando, use o seguinte formato de comando:

{param($<nome1>[, $<nome2>]...) <comando-com-variáveis-locais>} -ArgumentList <valor | $variável-local>

A palavra-chave "param" lista as variáveis locais que são usadas no comando. O parâmetro ArgumentList fornece os valores das variáveis, na ordem em que são listadas.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-AsJob

Executa o comando como trabalho em segundo plano em um computador remoto. Use esse parâmetro para executar comandos que demoram a ser concluídos.

Quando você usa 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 cmdlets Job. Para obter os resultados do trabalho, use Receive-Job.

O parâmetro AsJob é semelhante a usar Invoke-Command para executar um comando Start-Job remotamente. Contudo, com AsJob, o trabalho é criado no computador local, mesmo que seja executado em um computador remoto, e os resultados do trabalho remoto são automaticamente retornados ao computador local.

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

Necessário?	false
Posição?	named
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Authentication <AuthenticationMechanism>

Especifica o mecanismo usado para autenticar as credenciais do usuário. Os valores válidos são Default, Basic, Credssp, Digest, Kerberos, Negotiate e NegotiateWithImplicitCredential. O valor padrão é Default.

A autenticação CredSSP está disponível apenas no Windows Vista, no Windows Server 2008 e em versões mais recentes do Windows.

Para obter informações sobre os valores desse parâmetro, consulte a descrição da enumeração System.Management.Automation.Runspaces.AuthenticationMechanism no MSDN.

CUIDADO: a autenticação CredSSP (Credential Security Service 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 passadas para ele poderão ser usadas para controlar a sessão de rede.

Necessário?	false
Posição?	named
Valor padrão	Default
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-CertificateThumbprint <string>

Especifica o certificado de chave pública digital (X509) de uma conta de usuário com permissão para executar essa ação. Digite a impressão digital do certificado.

Os certificados são usados em autenticação baseada em certificado de cliente. Podem ser mapeados apenas para contas de usuários locais; não funcionam com contas de domínio.

Para obter uma impressão digital de certificado, use os comandos Get-Item ou Get-ChildItem na unidade Cert: do Windows PowerShell.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ComputerName <string[]>

Especifica os computadores nos quais o comando é executado. O padrão é o computador local.

Quando você usar o parâmetro ComputerName, o Windows PowerShell criará uma conexão temporária que será usada apenas para executar o comando especificado e depois será fechada. Se você precisar de uma conexão persistente, use o parâmetro Session.

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

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

Observação: no Windows Vista e em versões mais recentes do Windows, para incluir o computador local no valor do parâmetro ComputerName, é necessário abrir o Windows PowerShell com a opção "Executar como administrador".

Necessário?	false
Posição?	1
Valor padrão
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-ConfigurationName <string>

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

Digite um nome de configuração ou o URI de recurso totalmente qualificado para uma configuração de sessão. Se você especificar só o nome de configuração, o seguinte URI de esquema será pré-demarcado: https://schemas.microsoft.com/powershell.

A configuraçã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 padrão é o valor da variável de preferência $PSSessionConfigurationName no computador local. Se essa variável de preferência não for definida, o padrão será Microsoft.PowerShell. Para obter mais informações, consulte about_Preference_Variables.

Necessário?	false
Posição?	named
Valor padrão	https://Schemas.Microsoft.com/PowerShell/Microsoft.PowerShell
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-ConnectionURI <Uri[]>

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

O formato dessa cadeia de caracteres é:

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

O valor padrão é:

https://localhost:80/WSMAN

Os valores válidos para o segmento Transport do URI são HTTP e HTTPS. Se você não especificar um ConnectionURI, poderá usar os parâmetros UseSSL, ComputerName, Port e ApplicationName para especificar os valores de URI.

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

Necessário?	false
Posição?	1
Valor padrão	https://localhost:80/wsman
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-Credential <PSCredential>

Especifica uma conta de usuário com permissão para executar essa ação. O padrão é o usuário atual.

Digite um nome de usuário, como "User01" ou "Domain01\User01", ou insira uma variável que contenha um objeto PSCredential, como aquele gerado pelo cmdlet Get-Credential. Quando você digitar um nome de usuário, uma senha será solicitada.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-FilePath <string>

Executa o script local especificado em um ou mais computadores remotos. Insira o caminho e o nome de arquivo do script, ou canalize um caminho de script para Invoke-Command. O script deve residir no computador local ou em um diretório que o computador local possa acessar. Use o parâmetro ArgumentList para especificar os valores de parâmetros no script.

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

Necessário?	true
Posição?	2
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-HideComputerName

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.

Esse parâmetro afeta somente a exibição da saída. O objeto não é alterado.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-InputObject <psobject>

Especifica a entrada para o comando. Insira uma variável que contenha os objetos ou digite um comando ou expressão que obtenha os objetos.

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

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	true (ByValue)
Aceitar caracteres curinga?	false

-JobName <string>

Especifica um nome amigável para o trabalho em segundo plano. Por padrão, os trabalhos recebem o nome de "Job<n>", onde <n> é um numeral ordinal. Esse parâmetro é válido somente com o parâmetro AsJob.

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

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

Necessário?	false
Posição?	named
Valor padrão	Job<n>
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Port <int>

Especifica a porta de rede no computador remoto usada para esse comando. O padrão é a porta 80 (a porta HTTP).

Antes de usar uma porta alternativa, configure o ouvinte WinRM no computador remoto para ouvir nessa porta. Para configurar a escuta, digite estes dois comandos no prompt do Windows PowerShell:

remove-item -path wsman:\Localhost\listener\listener* -recurse

new-item -path wsman:\Localhost\listener -Transport http -Address * -port <número-da-porta>

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

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ScriptBlock <scriptblock>

Especifica os comandos a serem executados. Coloque os comandos entre chaves ( { } ) para criar um bloco de script. Esse parâmetro é obrigatório.

Por padrão, as variáveis do comando são avaliadas no computador remoto. Para incluir variáveis locais no comando, use o parâmetro ArgumentList.

Necessário?	true
Posição?	1
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Session <PSSession[]>

Executa o comando nas sessões do Windows PowerShell especificadas (PSSessions). Insira uma variável que contenha as PSSessions ou um comando que crie ou obtenha as PSSessions, como o comando New-PSSession ou Get-PSSession.

Quando você cria um PSSession, o Windows PowerShell estabelece uma conexão persistente com o computador remoto. Use uma 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 criar uma PSSession, use o cmdlet New-PSSession. Para obter mais informações, consulte about_PSSessions.

Necessário?	false
Posição?	1
Valor padrão
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-SessionOption <PSSessionOption>

Define opções avançadas para a sessão. Digite um objeto SessionOption que você cria usando o cmdlet New-PSSessionOption.

Os valores padrão para as opções são determinados pelo valor da variável de preferência $PSSessionOption, se esteja definida. Caso contrário, a sessão usará os padrões do sistema.

Para obter uma descrição das opções da sessão, inclusive os valores padrão, consulte o tópico da Ajuda referente ao cmdlet New-PSSessionOption. Para obter informações sobre a variável de preferência $PSSessionOption, consulte about_Preference_Variables.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ThrottleLimit <int>

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

O limite se aplica somente ao comando atual, não à sessão ou ao computador.

Necessário?	false
Posição?	named
Valor padrão	32
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-UseSSL

Usa o protocolo SSL para estabelecer uma conexão com o computador remoto. Por padrão, SSL não é usado.

WS-Management criptografa todo o conteúdo do Windows PowerShell transmitido pela rede. UseSSL é uma proteção adicional que envia os dados por 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, este falhará.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

<CommonParameters>

Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.

Entradas e saídas

O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.

Entradas	System.Management.Automation.ScriptBlock Você pode canalizar um comando em um bloco de scripts para Invoke-Command. Use a variável automática $input para representar os objetos de entrada no comando.
Saídas	System.Management.Automation.PSRemotingJob ou a saída do comando invocado Quando você usa o parâmetro AsJob, Invoke-Command retorna um objeto de trabalho. Caso contrário, retornará a saída do comando invocado (o valor do parâmetro ScriptBlock).

Observações

-- No Windows Vista e em versões mais recentes do Windows, para usar o parâmetro ComputerName de Invoke-Command para executar um comando no computador local, é necessário abrir o Windows PowerShell com a opção "Executar como administrador".

--Quando você executa comandos em vários computadores, o Windows PowerShell conecta os computadores na ordem em que eles aparecem na lista. Porém, a saída do comando é exibida na ordem recebida pelos computadores remotos, que pode ser diferente.

--Erros resultantes do comando que Invoke-Command executa são incluídos nos resultados do comando. Erros que podem ser fatais em um comando local são tratados como erros não fatais em um comando remoto. Essa estratégia assegura que erros fatais em um computador não encerram o comando em todos os computadores nos quais são executados. Essa prática é usada até 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 confie, o computador talvez não possa autenticar as credenciais do usuário. Para adicionar o computador remoto à lista de "hosts de confiança" no WS-Management, use o seguinte comando no provedor WSMAN, onde <Nome-do-computador-remoto> é o nome do computador remoto:

set-item -path wsman:\Localhost\Client\TrustedHosts -value <Nome-do-computador-remoto>.

Exemplo 1

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.

Exemplo 2

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.

Exemplo 3

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.

Exemplo 4

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.

Exemplo 5

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.

Exemplo 6

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.

Exemplo 7

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.

Exemplo 8

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.

Exemplo 9

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.

Exemplo 10

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.

Exemplo 11

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.

Exemplo 12

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.

Exemplo 13

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.

Exemplo 14

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.

Exemplo 15

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.

Consulte também

Conceitos

about_Remote
about_PSSessions
New-PSSession
Get-PSSession
Remove-PSSession
Enter-PSSession
Exit-PSSession
WSMan Provider