Compartilhar via

Invoke-Command

  • Referência
Módulo:
Microsoft.PowerShell.Core

Executa comandos em computadores locais e remotos.

Sintaxe

Invoke-Command
      [-ScriptBlock] <ScriptBlock>
      [-NoNewScope]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]
Invoke-Command
      [[-Session] <PSSession[]>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-ScriptBlock] <ScriptBlock>
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]
Invoke-Command
      [[-Session] <PSSession[]>]
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <String>]
      [-FilePath] <String>
      [-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]
      [-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]
      [-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]
      [-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]
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]
Invoke-Command
      -Credential <PSCredential>
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-ScriptBlock] <ScriptBlock>
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-VMGuid] <Guid[]>
      [<CommonParameters>]
Invoke-Command
      -Credential <PSCredential>
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-ScriptBlock] <ScriptBlock>
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -VMName <String[]>
      [<CommonParameters>]
Invoke-Command
      -Credential <PSCredential>
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      [-VMGuid] <Guid[]>
      [<CommonParameters>]
Invoke-Command
      -Credential <PSCredential>
      [-ThrottleLimit <Int32>]
      [-AsJob]
      [-HideComputerName]
      [-FilePath] <String>
      [-InputObject <PSObject>]
      [-ArgumentList <Object[]>]
      -VMName <String[]>
      [<CommonParameters>]

Description

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

Para executar um único comando em um computador remoto, use o parâmetro ComputerName. Para executar uma série de comandos relacionados que compartilham dados, use o cmdlet para criar um de PSSession (uma conexão persistente) no computador remoto e use o parâmetro de Sessão de para executar o comando noPSSession . 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 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.

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

Exemplos

Exemplo 1: executar um script em um servidor

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

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

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

Exemplo 2: executar um comando em um servidor remoto

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

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

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

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

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

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

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

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

O cmdlet Invoke-Command executa o comando Get-Culture no Server02. O parâmetro sessão especifica a sessão salva na 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 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.

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

17930240

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

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

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

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

Exemplo 5: insira um comando armazenado em uma variável local

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

$command = { Get-EventLog -LogName "Windows PowerShell" |
  Where-Object {$_.Message -like "*certificate*"} }
Invoke-Command -ComputerName S1, S2 -ScriptBlock $command

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

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

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

$parameters = @{
  ComputerName = "Server01", "Server02", "TST-0143", "localhost"
  ConfigurationName = 'MySession.PowerShell'
  ScriptBlock = { Get-EventLog "Windows PowerShell" }
}
Invoke-Command @parameters

O parâmetro ComputerName especifica uma lista separada por vírgulas de nomes de computador. 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-EventLog para obter os logs de eventos do Windows PowerShell 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 cmdlet Get-Content para obter o conteúdo do arquivo Machine.txt, um arquivo de nomes de computador.

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

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

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

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

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

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

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

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

$results = $j | Receive-Job

O cmdlet New-PSSession cria sessões nos computadores remotos Server01 e Server02. O cmdlet Invoke-Command executa um trabalho em segundo plano em cada uma das sessões. O comando usa o parâmetro AsJob para executar o comando como um trabalho em segundo plano. 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 comando Get-Job salva o objeto de trabalho na variável $j. A variável $j é canalizada para o cmdlet Format-List para exibir todas as propriedades do objeto de trabalho em uma lista. O último comando obtém os resultados dos trabalhos. Ele canaliza o objeto de trabalho em $j para o cmdlet Receive-Job e armazena os resultados na variável $results.

Exemplo 9: Incluir variáveis locais em uma execução de comando em um computador remoto

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

$Log = "Windows PowerShell"
Invoke-Command -ComputerName Server01 -ScriptBlock { Get-EventLog -LogName $Using:Log -Newest 10 }

A variável $Log armazena o nome do log de eventos, Windows PowerShell. O cmdlet Invoke-Command é executado Get-EventLog no Server01 para obter os dez eventos mais recentes do log de eventos. O valor do parâmetro LogName é a variável $Log, que é prefixada pelo modificador de escopo Using 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 que esse cmdlet retorna. Ele altera 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 -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

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

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

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

Para obter mais informações sobre a palavra-chave Param, consulte about_Language_Keywords.

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

aa.pdf
ab.pdf
ac.pdf
az.pdf

Invoke-Command usa o parâmetro ScriptBlock que define duas variáveis, $param1 e $param2. Get-ChildItem usa os parâmetros nomeados, 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 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 do diretório de arquivos .txt de um servidor. O parâmetro Path é a posição 0 e o parâmetro de Filtro de é a posição 1.

Para obter mais informações sobre a variável $args, consulte about_Automatic_Variables

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

Directory: C:\Test

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           6/12/2019    15:15            128 alog.txt
-a---           7/27/2019    15:16            256 blog.txt
-a---           9/28/2019    17:10             64 zlog.txt

usa um parâmetro ScriptBlock e especifica os valores de matriz e . O ArgumentList passa os valores da matriz para as posições de 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 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 que o arquivo de script não esteja acessível aos computadores remotos.

Invoke-Command -ComputerName (Get-Content Servers.txt) -FilePath C:\Scripts\Sample.ps1 -ArgumentList Process, Service

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

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

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

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

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

A variável $parameters é uma tabela de hash que contém os parâmetros a serem passados para o cmdlet Invoke-Command. O cmdlet executa um comando usando a configuração de sessão Microsoft.Exchange . O parâmetro ConnectionURI especifica a URL do ponto de extremidade do servidor Exchange. O parâmetro de credenciais especifica as credenciais armazenadas na 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
Invoke-Command -ComputerName server01 -UseSSL -ScriptBlock { Get-HotFix } -SessionOption $so -Credential server01\user01

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

Nota

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

O cmdlet Invoke-Command executa um comando Get-HotFix remotamente. O parâmetro SessionOption recebe a 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 cmdlet cria um objeto PSSessionOption que é salvo na variável . O comando usa o parâmetro MaximumRedirection para definir a propriedade MaximumConnectionRedirectionCount do objeto PSSessionOption como 1.

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

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

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

Este exemplo mostra como acessar um compartilhamento de rede 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. O Server01 conecta-se ao Server02 e, em seguida, o Server02 faz um segundo salto para o Net03 para acessar o compartilhamento de rede. Para obter mais informações sobre como a Comunicação Remota do PowerShell dá suporte a saltos entre computadores, consulte Fazer o segundo salto no PowerShell Remoting.

A delegação do CredSSP (Provedor de Suporte à Segurança de Credencial) necessária está habilitada nas configurações do cliente no computador local e nas configurações de serviço no computador remoto. Para executar os comandos neste exemplo, você deve ser um 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 = @{
  Session = $s
  ScriptBlock = { Get-Item \\Net03\Scripts\LogFiles.ps1 }
  Authentication = "CredSSP"
  Credential = "Domain01\Admin01"
}
Invoke-Command @parameters

O cmdlet Enable-WSManCredSSP 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 objeto na variável $s.

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

A variável $parameters contém os valores de parâmetro para se conectar ao compartilhamento de rede. O cmdlet Invoke-Command executa um comando Get-Item na sessão em $s. Esse comando obtém um script do compartilhamento de rede \\Net03\Scripts. O comando usa o parâmetro de Autenticação 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 se desconecta de cada computador. O script continua sendo 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=43200000}
}
Invoke-Command @parameters

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

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

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

Parâmetros

-AllowRedirection

Permite o redirecionamento dessa 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 MaximumConnectionRedirectionCount sessão. Use o parâmetro MaximumRedirection do cmdlet New-PSSessionOption ou defina a propriedade MaximumConnectionRedirectionCount da variável de preferência $PSSessionOption. O valor padrão é 5.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ApplicationName

Especifica o segmento de 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 valor padrão é o valor da variável de preferência $PSSessionApplicationName no computador local. Se essa variável de preferência não estiver definida, o valor padrão será WSMAN. Esse valor é apropriado 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.

Tipo:String
Cargo:Named
Valor padrão:$PSSessionApplicationName if set on the local computer, otherwise WSMAN
Obrigatório:False
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-ArgumentList

Fornece os valores das variáveis locais no comando. As variáveis no comando são substituídas por esses valores antes que o comando seja executado no computador remoto. Insira os valores em uma lista separada por vírgulas. Os valores são associados a variáveis na ordem em que estão listados. O alias para ArgumentList é Args.

Os valores no parâmetro 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($<name1>[, $<name2>]...) <command-with-local-variables>} -ArgumentList <value> -ou- <local-variable>

A palavra-chave lista as variáveis locais usadas no comando. ArgumentList fornece os valores das variáveis, na ordem em que elas estão listadas.

Tipo:Object[]
Aliases:Args
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 exibe o prompt de comando. Você pode 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 o cmdlet Receive-Job.

O parâmetro AsJob se assemelha ao uso do cmdlet Invoke-Command para executar um cmdlet Start-Job 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 para o computador local.

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

Tipo:SwitchParameter
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Authentication

Especifica o mecanismo usado para autenticar as credenciais do usuário. A autenticação credSSP está disponível apenas 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:

  • Inadimplência
  • Básico
  • Credssp
  • Digerir
  • Kerberos
  • Negociar
  • NegotiateWithImplicitCredential

O valor padrão é Default.

Para obter mais informações sobre os valores desse parâmetro, consulte de Enumeração AuthenticationMechanism .

Cuidado

A autenticação credSSP (Provedor de Suporte à Segurança de Credencial), na qual as credenciais do usuário são passadas para um computador remoto a ser autenticado, 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. Para obter mais informações, consulte provedor de suporte de segurança de credencial.

Tipo:AuthenticationMechanism
Valores aceitos:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Cargo:Named
Valor padrão:Default
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-CertificateThumbprint

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

Os certificados são usados 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 do certificado, use um comando Get-Item ou Get-ChildItem no Cert do PowerShell: unidade.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ComputerName

Especifica os computadores nos quais 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 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 credencial. O computador deve ser configurado para o transporte HTTPS ou o endereço IP do computador remoto deve ser incluído na lista de winrm do computador local TrustedHosts. Para obter instruções para adicionar um nome de computador à lista de TrustedHosts, consulte How to Add a Computer to the Trusted Host List.

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

Tipo:String[]
Aliases:Cn
Cargo:0
Valor padrão:Local computer
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ConfigurationName

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

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

A configuração de sessão de 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 valor da variável de preferência $PSSessionConfigurationName 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.

Tipo:String
Cargo:Named
Valor padrão:$PSSessionConfigurationName if set on the local computer, otherwise Microsoft.PowerShell
Obrigatório:False
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga: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:

https://localhost:5985/WSMAN

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

Os valores válidos para o segmento Transport 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ões: 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 redirecionar a conexão para um URI diferente, o PowerShell impedirá o redirecionamento, a menos que você use o parâmetro AllowRedirection no comando.

Tipo:Uri[]
Aliases:URI, CU
Cargo:0
Valor padrão:https://localhost:5985/WSMAN
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Credential

Especifica uma conta de usuário que tem 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 um objeto PSCredential , como um gerado pelo cmdlet . Se você digitar um nome de usuário, esse cmdlet solicitará uma senha.

Tipo:PSCredential
Cargo:Named
Valor padrão:Current user
Obrigatório:False
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-EnableNetworkAccess

Indica que esse cmdlet adiciona um token de segurança interativo a 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 para o computador local.

Uma sessão de loopback é uma 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 autenticar em computadores remotos.

O parâmetro EnableNetworkAccess só é eficaz em sessões de loopback. Se você usar EnableNetworkAccess ao criar uma sessão em um computador remoto, o comando terá êxito, mas o parâmetro será ignorado.

Você pode permitir o acesso remoto em uma sessão de loopback usando o credSSP valor do parâmetro de Autenticação , que delega as credenciais de sessão para outros computadores.

Para proteger o computador contra acesso mal-intencionado, as sessões de loopback desconectadas que têm tokens interativos, que são 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 de outros computadores. Para obter mais informações, consulte Disconnect-PSSession.

Esse parâmetro foi introduzido no PowerShell 3.0.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-FilePath

Especifica um script local que este cmdlet executa em um ou mais computadores remotos. Insira o caminho e o nome do arquivo do script ou redirecione 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 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.

Tipo:String
Aliases:PSPath
Cargo:1
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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.

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

Tipo:SwitchParameter
Aliases:HCN
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-InDisconnectedSession

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

Quando você usa o parâmetro InDisconnectedSession, cria uma sessão persistente em cada computador remoto, inicia o comando especificado pelo parâmetro ScriptBlock ou FilePath e desconecta da sessão. Os comandos continuam sendo 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 todos os resultados sejam retornados, InDisconnectedSession garante que todos os resultados do comando sejam retornados para a sessão reconectada, em vez de serem divididos entre as sessões.

Você não pode usar InDisconnectedSession com o parâmetro de Sessão 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 cmdlets Connect-PSSession ou Receive-PSSession. Para obter os resultados dos comandos executados na sessão, use o cmdlet Receive-PSSession. Para executar comandos que geram saída em uma sessão desconectada, defina o valor da opção de sessão OutputBufferingMode para 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 você se conectar 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 variável de preferência $PSSessionOption. 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.

Tipo:SwitchParameter
Aliases:Disconnected
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-InputObject

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

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

Tipo:PSObject
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-JobName

Especifica um nome amigável para o trabalho em segundo plano. Por padrão, os trabalhos são nomeados Job<n>, em que <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.

Tipo:String
Cargo:Named
Valor padrão:Job<n>
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 apenas 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.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Port

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

Antes de usar uma porta alternativa, configure o ouvinte do WinRM no computador remoto para escutar nessa 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 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 que o comando seja executado em todos os computadores.

Tipo:Int32
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ScriptBlock

Especifica os comandos a serem executados. Coloque os comandos em chaves { } para criar um bloco de script. Esse parâmetro é necessário.

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

Tipo:ScriptBlock
Aliases:Command
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Session

Especifica uma matriz de sessões em que esse cmdlet executa o comando. Insira uma variável que contenha objetos de PSSession ou um comando que cria ou obtém os objetos PSSession , como um comando ou .

Quando você cria um PSSession, o 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 obter mais informações, consulte about_PSSessions.

Tipo:PSSession[]
Cargo:0
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-SessionName

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

Esse parâmetro foi introduzido no PowerShell 3.0.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-SessionOption

Especifica opções avançadas para a sessão. Insira um objeto SessionOption, como um que você cria usando o cmdlet New-PSSessionOption 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.

Os valores padrão para as opções são determinados pelo valor da variável de preferência $PSSessionOption, 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 valores padrão para sessões definidas na variável de preferência $PSSessionOption 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 incluem os valores padrão, consulte New-PSSessionOption. Para obter informações sobre a variável de preferência $PSSessionOption, consulte about_Preference_Variables. Para obter mais informações sobre configurações de sessão, consulte about_Session_Configurations.

Tipo:PSSessionOption
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ThrottleLimit

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 de 0, o valor padrão, 32, será usado.

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

Tipo:Int32
Cargo:Named
Valor padrão:32
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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.

WS-Management criptografa todo o conteúdo do PowerShell transmitido pela rede. O parâmetro UseSSL é uma proteção adicional que envia os dados em 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á.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-VMId

Especifica uma matriz de IDs de máquinas virtuais.

Tipo:Guid[]
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-VMName

Especifica uma matriz de nomes de máquinas virtuais.

Tipo:String[]
Cargo:Named
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

Entradas

ScriptBlock

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

Saídas

System.Management.Automation.PSRemotingJob, System.Management.Automation.Runspaces.PSSession, or the output of the invoked command

Esse cmdlet retornará um objeto de trabalho, se você usar o parâmetro AsJob. Se você especificar o parâmetro InDisconnectedSession, retornará um objeto PSSession. Caso contrário, ele retorna a saída do comando invocado, que é o valor do parâmetro ScriptBlock.

Observações

No Windows Vista e 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.

Erros resultantes do comando que Invoke-Command execuções são incluídos nos resultados do comando. Erros que estariam encerrando erros em um comando local são tratados como erros de não terminação em um comando remoto. Essa estratégia garante que os erros de encerramento em um computador não fechem o comando em todos os computadores nos quais ele é executado. Essa prática é usada mesmo quando um comando remoto é executado em um único computador.

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

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

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

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