Invoke-Command

Módulo:

Microsoft.PowerShell.Core

Ejecuta comandos en equipos locales y remotos.

Syntax

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

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

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

Invoke-Command
      [[-ComputerName] <string[]>]
      [-ScriptBlock] <scriptblock>
      [-Credential <pscredential>]
      [-Port <int>]
      [-UseSSL]
      [-ConfigurationName <string>]
      [-ApplicationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-InDisconnectedSession]
      [-SessionName <string[]>]
      [-HideComputerName]
      [-JobName <string>]
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [-CertificateThumbprint <string>]
      [<CommonParameters>]

Invoke-Command
      [[-ComputerName] <string[]>]
      [-FilePath] <string>
      [-Credential <pscredential>]
      [-Port <int>]
      [-UseSSL]
      [-ConfigurationName <string>]
      [-ApplicationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-InDisconnectedSession]
      [-SessionName <string[]>]
      [-HideComputerName]
      [-JobName <string>]
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [[-ConnectionUri] <uri[]>]
      [-ScriptBlock] <scriptblock>
      [-Credential <pscredential>]
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-InDisconnectedSession]
      [-HideComputerName]
      [-JobName <string>]
      [-AllowRedirection]
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [-CertificateThumbprint <string>]
      [<CommonParameters>]

Invoke-Command
      [[-ConnectionUri] <uri[]>]
      [-FilePath] <string>
      [-Credential <pscredential>]
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-InDisconnectedSession]
      [-HideComputerName]
      [-JobName <string>]
      [-AllowRedirection]
      [-SessionOption <PSSessionOption>]
      [-Authentication <AuthenticationMechanism>]
      [-EnableNetworkAccess]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-VMId] <guid[]>
      [-ScriptBlock] <scriptblock>
      -Credential <pscredential>
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-ScriptBlock] <scriptblock>
      -Credential <pscredential>
      -VMName <string[]>
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-VMId] <guid[]>
      [-FilePath] <string>
      -Credential <pscredential>
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-FilePath] <string>
      -Credential <pscredential>
      -VMName <string[]>
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-ScriptBlock] <scriptblock>
      -HostName <string[]>
      [-Port <int>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <string>]
      [-UserName <string>]
      [-KeyFilePath <string>]
      [-Subsystem <string>]
      [-ConnectingTimeout <int>]
      [-SSHTransport]
      [-Options <hashtable>]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-ScriptBlock] <scriptblock>
      -ContainerId <string[]>
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <string>]
      [-RunAsAdministrator]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-FilePath] <string>
      -ContainerId <string[]>
      [-ConfigurationName <string>]
      [-ThrottleLimit <int>]
      [-AsJob]
      [-HideComputerName]
      [-JobName <string>]
      [-RunAsAdministrator]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      [-ScriptBlock] <scriptblock>
      -SSHConnection <hashtable[]>
      [-AsJob]
      [-HideComputerName]
      [-JobName <string>]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      -FilePath <string>
      -HostName <string[]>
      [-AsJob]
      [-HideComputerName]
      [-UserName <string>]
      [-KeyFilePath <string>]
      [-Subsystem <string>]
      [-ConnectingTimeout <int>]
      [-SSHTransport]
      [-Options <hashtable>]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Invoke-Command
      -FilePath <string>
      -SSHConnection <hashtable[]>
      [-AsJob]
      [-HideComputerName]
      [-RemoteDebug]
      [-InputObject <psobject>]
      [-ArgumentList <Object[]>]
      [<CommonParameters>]

Description

El Invoke-Command cmdlet ejecuta comandos en un equipo local o remoto y devuelve todos los resultados de los comandos, incluidos los errores. Con un solo Invoke-Command comando, puede ejecutar comandos en varios equipos.

Para ejecutar un único comando en un equipo remoto, use el parámetro ComputerName . Para ejecutar una serie de comandos relacionados que comparten datos, use el New-PSSession cmdlet para crear una PSSession (una conexión persistente) en el equipo remoto y, a continuación, use el parámetro Session de Invoke-Command para ejecutar el comando en PSSession. Para ejecutar un comando en una sesión desconectada, use el parámetro InDisconnectedSession . Para ejecutar un comando en un trabajo en segundo plano, use el parámetro AsJob .

También puede usar Invoke-Command en un equipo local para ejecutar un bloque de script como un comando. PowerShell ejecuta el bloque de script inmediatamente en un ámbito secundario del ámbito actual.

Antes de usar Invoke-Command para ejecutar comandos en un equipo remoto, lea about_Remote.

A partir de PowerShell 6.0, puede usar Secure Shell (SSH) para establecer una conexión a comandos e invocar comandos en equipos remotos. SSH debe instalarse en el equipo local y el equipo remoto debe configurarse con un punto de conexión SSH de PowerShell. La ventaja de una sesión remota de PowerShell basada en SSH es que funciona en varias plataformas (Windows, Linux, macOS). Para la sesión basada en SSH, use los parámetros HostName o SSH Conectar ion para especificar el equipo remoto y la información de conexión pertinente. Para obtener más información sobre cómo configurar la comunicación remota ssh de PowerShell, consulte Comunicación remota de PowerShell a través de SSH.

Algunos ejemplos de código usan la expansión para reducir la longitud de la línea. Para obtener más información, consulte about_Splatting.

Ejemplos

Ejemplo 1: Ejecución de un script en un servidor

En este ejemplo se ejecuta el Test.ps1 script en el equipo Server01.

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

El parámetro FilePath especifica un script que se encuentra en el equipo local. El script se ejecuta en el equipo remoto y los resultados se devuelven al equipo local.

Ejemplo 2: Ejecutar un comando en un servidor remoto

En este ejemplo se ejecuta un Get-Culture comando en el equipo remoto Server01.

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

El parámetro ComputerName especifica el nombre del equipo remoto. El parámetro Credential se usa para ejecutar el comando en el contexto de seguridad de Domain01\User01, un usuario que tiene permiso para ejecutar comandos. El parámetro ScriptBlock especifica el comando que se va a ejecutar en el equipo remoto.

En respuesta, PowerShell solicita la contraseña y un método de autenticación para la cuenta User01. Después ejecuta el comando en el equipo Server01 y devuelve el resultado.

Ejemplo 3: Ejecutar un comando en una conexión persistente

En este ejemplo se ejecuta el mismo Get-Culture comando en una sesión, mediante una conexión persistente, en el equipo remoto denominado Server02.

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

El New-PSSession cmdlet crea una sesión en el equipo remoto Server02 y la guarda en la $s variable . Normalmente, solo se crea una sesión cuando se ejecuta una serie de comandos en el equipo remoto.

El Invoke-Command cmdlet ejecuta el Get-Culture comando en Server02. El parámetro Session especifica la sesión guardada en la $s variable .

En respuesta, PowerShell ejecuta el comando en la sesión en el equipo Server02.

Ejemplo 4: Usar una sesión para ejecutar una serie de comandos que comparten datos

En este ejemplo se comparan los efectos del uso de los parámetros ComputerName y Session de Invoke-Command. Muestra cómo usar una sesión para ejecutar una serie de comandos que comparten los mismos datos.

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

Los dos primeros comandos usan el parámetro ComputerName de Invoke-Command para ejecutar comandos en el equipo remoto Server02. El primer comando usa el Get-Process cmdlet para obtener el proceso de PowerShell en el equipo remoto y guardarlo en la $p variable . El segundo comando obtiene el valor de la propiedad VirtualMemorySize del proceso de PowerShell.

Cuando se usa el parámetro ComputerName , PowerShell crea una nueva sesión para ejecutar el comando. La sesión se cierra cuando se completa el comando. La $p variable se creó en una conexión, pero no existe en la conexión creada para el segundo comando.

El problema se resuelve mediante la creación de una sesión persistente en el equipo remoto y, a continuación, la ejecución de ambos comandos en la misma sesión.

El New-PSSession cmdlet crea una sesión persistente en el equipo Server02 y guarda la sesión en la $s variable . Las Invoke-Command líneas siguientes usan el parámetro Session para ejecutar ambos comandos en la misma sesión. Dado que ambos comandos se ejecutan en la misma sesión, el $p valor permanece activo.

Ejemplo 5: Invocar un comando con un bloque de script almacenado en una variable

En este ejemplo se muestra cómo ejecutar un comando que se almacena como un bloque de script en una variable. Cuando el bloque de script se guarda en una variable, puede especificar la variable como el valor del parámetro ScriptBlock .

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

La $command variable almacena el Get-WinEvent comando con formato de bloque de script. Invoke-Command ejecuta el comando almacenado en en $command los equipos remotos S1 y S2.

Ejemplo 6: Ejecución de un único comando en varios equipos

En este ejemplo se muestra cómo usar Invoke-Command para ejecutar un único comando en varios equipos.

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

El parámetro ComputerName especifica una lista separada por comas de nombres de equipo. La lista de equipos incluye el valor localhost, que representa el equipo local. El parámetro ConfigurationName especifica una configuración de sesión alternativa. El parámetro ScriptBlock se ejecuta Get-WinEvent para obtener los registros de eventos de PowerShellCore/Operational de cada equipo.

Ejemplo 7: Obtener la versión del programa host en varios equipos

En este ejemplo se obtiene la versión del programa host de PowerShell que se ejecuta en 200 equipos remotos.

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

Dado que solo se ejecuta un comando, no es necesario crear conexiones persistentes a cada uno de los equipos. En su lugar, el comando usa el parámetro ComputerName para indicar los equipos. Para especificar los equipos, usa el Get-Content cmdlet para obtener el contenido del archivo Machine.txt, un archivo de nombres de equipo.

El Invoke-Command cmdlet ejecuta un Get-Host comando en los equipos remotos. Usa la notación de puntos para obtener la propiedad Version del host de PowerShell.

Estos comandos se ejecutan de uno en uno. Cuando se completan los comandos, la salida de los comandos de todos los equipos se guarda en la $version variable . Los resultados incluyen el nombre del equipo en el que se originaron los datos.

Ejemplo 8: Ejecución de un trabajo en segundo plano en varios equipos remotos

En este ejemplo se ejecuta un comando en dos equipos remotos. El Invoke-Command comando usa el parámetro AsJob para que el comando se ejecute como un trabajo en segundo plano. Los comandos se ejecutan en los equipos remotos, pero el trabajo existe en el equipo local. Los resultados se transmiten al equipo 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

El New-PSSession cmdlet crea sesiones en los equipos remotos Server01 y Server02. El Invoke-Command cmdlet ejecuta un trabajo en segundo plano en cada una de las sesiones. El comando usa el parámetro AsJob para ejecutar el comando como un trabajo en segundo plano. Este comando devuelve un objeto de trabajo que contiene dos objetos de trabajo secundarios, uno para cada trabajo que se ejecuta en los dos equipos remotos.

El Get-Job comando guarda el objeto de trabajo en la $j variable . A $j continuación, la variable se canaliza al Format-List cmdlet para mostrar todas las propiedades del objeto de trabajo en una lista. El último comando obtiene los resultados de los trabajos. Canaliza el objeto de trabajo en $j al Receive-Job cmdlet y almacena los resultados en la $results variable.

Ejemplo 9: Incluir variables locales en una ejecución de comandos en un equipo remoto

En este ejemplo se muestra cómo incluir los valores de las variables locales en un comando ejecutado en un equipo remoto. El comando usa el Using modificador de ámbito para identificar una variable local en un comando remoto. De forma predeterminada, se supone que todas las variables están definidas en la sesión remota. El Using modificador de ámbito se introdujo en PowerShell 3.0. Para obtener más información sobre el Using modificador de ámbito, consulte about_Remote_Variables y about_Scopes.

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

La $Log variable almacena el nombre del registro de eventos, PowerShellCore/Operational. El Invoke-Command cmdlet se ejecuta Get-WinEvent en Server01 para obtener los diez eventos más recientes del registro de eventos. El valor del parámetro LogName es la $Log variable prefijo por el Using modificador de ámbito para indicar que se creó en la sesión local, no en la sesión remota.

Ejemplo 10: Ocultar el nombre del equipo

En este ejemplo se muestra el efecto de usar el parámetro HideComputerName de Invoke-Command. HideComputerName no cambia el objeto que devuelve este cmdlet. Solo cambia la pantalla. Todavía puede usar los cmdlets Format para mostrar la propiedad PsComputerName de cualquiera de los objetos afectados.

Invoke-Command -ComputerName S1, S2 -ScriptBlock { Get-Process PowerShell }

PSComputerName    Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id   ProcessName
--------------    -------  ------    -----      ----- -----   ------     --   -----------
S1                575      15        45100      40988   200     4.68     1392 PowerShell
S2                777      14        35100      30988   150     3.68     67   PowerShell

Invoke-Command -ComputerName S1, S2 -HideComputerName -ScriptBlock {
    Get-Process PowerShell
}

Handles  NPM(K)    PM(K)      WS(K) VM(M)   CPU(s)     Id   ProcessName
-------  ------    -----      ----- -----   ------     --   -----------
575      15        45100      40988   200     4.68     1392 PowerShell
777      14        35100      30988   150     3.68     67   PowerShell

Los dos primeros comandos usan Invoke-Command para ejecutar un Get-Process comando para el proceso de PowerShell. La salida del primer comando incluye la propiedad PsComputerName , que contiene el nombre del equipo en el que se ejecutó el comando. La salida del segundo comando, que usa HideComputerName, no incluye la columna PsComputerName .

Ejemplo 11: Uso de la palabra clave Param en un bloque de script

La Param palabra clave y el parámetro ArgumentList se usan para pasar valores de variable a parámetros con nombre en un bloque de script. En este ejemplo se muestran los nombres de archivo que comienzan por la letra a y tienen la .pdf extensión .

Para obtener más información sobre la Param palabra clave , 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 el parámetro ScriptBlock que define dos variables y $param1$param2. Get-ChildItem usa los parámetros con nombre, Name e Include con los nombres de variable. ArgumentList pasa los valores a las variables.

Ejemplo 12: Uso de la variable automática $args en un bloque de script

La $args variable automática y el parámetro ArgumentList se usan para pasar valores de matriz a posiciones de parámetro en un bloque de script. En este ejemplo se muestra el contenido del directorio de un servidor de .txt archivos. El Get-ChildItemparámetro Path es la posición 0 y el parámetro Filter es la posición 1.

Para obtener más información sobre la $args variable, consulte about_Automatic_Variables

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

Directory: C:\Test

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

Invoke-Command usa un parámetro ScriptBlock y Get-ChildItem especifica los valores de matriz $args[0] y $args[1] . ArgumentList pasa los valores de $args matriz a las posiciones de Get-ChildItem parámetro para Path y Filter.

Ejemplo 13: Ejecutar un script en todos los equipos enumerados en un archivo de texto

En este ejemplo se usa el Invoke-Command cmdlet para ejecutar el Sample.ps1 script en todos los equipos enumerados en el Servers.txt archivo. El comando usa el parámetro FilePath para especificar el archivo de script. Este comando le permite ejecutar el script en los equipos remotos, incluso si el archivo de script no es accesible para los equipos remotos.

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

Al enviar el comando, el contenido del Sample.ps1 archivo se copia en un bloque de script y el bloque de script se ejecuta en cada uno de los equipos remotos. Este procedimiento es equivalente al uso del parámetro ScriptBlock para enviar el contenido del script.

Ejemplo 14: Ejecución de un comando en un equipo remoto mediante un URI

En este ejemplo se muestra cómo ejecutar un comando en un equipo remoto identificado por un identificador uniforme de recursos (URI). En este ejemplo concreto se ejecuta un Set-Mailbox comando en un servidor remoto de 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

La primera línea usa el Get-Credential cmdlet para almacenar las credenciales de Windows Live ID en la $LiveCred variable . PowerShell solicita al usuario que escriba las credenciales de Windows Live ID.

La $parameters variable es una tabla hash que contiene los parámetros que se van a pasar al Invoke-Command cmdlet . El Invoke-Command cmdlet ejecuta un Set-Mailbox comando mediante la configuración de sesión de Microsoft.Exchange . El parámetro Conectar ionURI especifica la dirección URL del punto de conexión del servidor exchange. El parámetro Credential especifica las credenciales almacenadas en la $LiveCred variable . El parámetro AuthenticationMechanism especifica el uso de la autenticación básica. El parámetro ScriptBlock especifica un bloque de script que contiene el comando .

Ejemplo 15: Usar una opción de sesión

En este ejemplo se muestra cómo crear y usar un parámetro SessionOption .

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

El New-PSSessionOption cmdlet crea un objeto de opción de sesión que hace que el extremo remoto no compruebe la entidad de certificación, el nombre canónico y las listas de revocación al evaluar la conexión HTTPS entrante. El objeto SessionOption se guarda en la $so variable .

Nota:

Deshabilitar estas comprobaciones es conveniente para solucionar problemas, pero obviamente no es seguro.

El Invoke-Command cmdlet ejecuta un Get-HotFix comando de forma remota. El parámetro SessionOption recibe la $so variable .

Ejemplo 16: Administración del redireccionamiento de URI en un comando remoto

En este ejemplo se muestra cómo usar los parámetros AllowRedirection y SessionOption para administrar el redireccionamiento de URI en un 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

El New-PSSessionOption cmdlet crea un objeto PSSessionOption que se guarda en la $max variable . El comando usa el parámetro MaximumRedirection para establecer la propiedad Maximum Conectar ionRedirectionCount del objeto PSSessionOption en 1.

El Invoke-Command cmdlet ejecuta un Get-Mailbox comando en un servidor remoto de Microsoft Exchange Server. El parámetro AllowRedirection proporciona permiso explícito para redirigir la conexión a un punto de conexión alternativo. El parámetro SessionOption usa el objeto de sesión almacenado en la $max variable .

Como resultado, si el equipo remoto especificado por Conectar ionURI devuelve un mensaje de redirección, PowerShell redirige la conexión, pero si el nuevo destino devuelve otro mensaje de redirección, se supera el valor de recuento de redireccionamiento de 1 y Invoke-Command devuelve un error de no terminación.

Ejemplo 17: Acceso a un recurso compartido de red en una sesión remota

En este ejemplo se muestra cómo acceder a un recurso compartido de red desde una sesión remota. Se usan tres equipos para mostrar el ejemplo. Server01 es el equipo local, Server02 es el equipo remoto y Net03 contiene el recurso compartido de red. Server01 se conecta a Server02 y, a continuación, Server02 realiza un segundo salto a Net03 para acceder al recurso compartido de red. Para obtener más información sobre cómo la comunicación remota de PowerShell admite saltos entre equipos, consulte Realización del segundo salto en comunicación remota de PowerShell.

La delegación necesaria del proveedor de soporte técnico de seguridad de credenciales (CredSSP) está habilitada en la configuración del cliente en el equipo local y en la configuración del servicio en el equipo remoto. Para ejecutar los comandos de este ejemplo, debe ser miembro del grupo Administración istrators en el equipo local y en el equipo remoto.

Enable-WSManCredSSP -Role Client -DelegateComputer Server02
$s = New-PSSession Server02
Invoke-Command -Session $s -ScriptBlock { Enable-WSManCredSSP -Role Server -Force }
$parameters = @{
  ComputerName   = 'Server02'
  ScriptBlock    = { Get-Item \\Net03\Scripts\LogFiles.ps1 }
  Authentication = 'CredSSP'
  Credential     = 'Domain01\Admin01'
}
Invoke-Command @parameters

El Enable-WSManCredSSP cmdlet habilita la delegación credSSP desde el equipo local Server01 al equipo remoto Server02. El parámetro Role especifica Client para configurar el valor de cliente CredSSP en el equipo local.

New-PSSession crea un objeto PSSession para Server02 y almacena el objeto en la $s variable .

El Invoke-Command cmdlet usa la $s variable para conectarse al equipo remoto, Server02. El parámetro ScriptBlock se ejecuta Enable-WSManCredSSP en el equipo remoto. El parámetro Role especifica Server para configurar el valor del servidor CredSSP en el equipo remoto.

La $parameters variable contiene los valores de parámetro para conectarse al recurso compartido de red. El Invoke-Command cmdlet ejecuta un Get-Item comando en la sesión de $s. Este comando obtiene un script del \\Net03\Scripts recurso compartido de red. El comando usa el parámetro Authentication con un valor de CredSSP y el parámetro Credential con un valor de Domain01\Administración 01.

Ejemplo 18: Inicio de scripts en muchos equipos remotos

En este ejemplo se ejecuta un script en más de cien equipos. Para minimizar el impacto en el equipo local, se conecta a cada equipo, inicia el script y luego se desconecta. El script se sigue ejecutando en las sesiones desconectadas.

$parameters = @{
  ComputerName          = (Get-Content -Path C:\Test\Servers.txt)
  InDisconnectedSession = $true
  FilePath              = '\\Scripts\Public\ConfigInventory.ps1'
  SessionOption         = @{
      OutputBufferingMode = 'Drop'
      IdleTimeout         = [timespan]::FromHours(12)
  }
}
Invoke-Command @parameters

El comando usa Invoke-Command para ejecutar el script. El valor del parámetro ComputerName es un Get-Content comando que obtiene los nombres de los equipos remotos de un archivo de texto. El parámetro InDisconnectedSession desconecta las sesiones en cuanto inicia el comando. El valor del parámetro FilePath es el script que Invoke-Command se ejecuta en cada equipo.

El valor de SessionOption es una tabla hash. El valor OutputBufferingMode se establece en Drop y el valor IdleTimeout se establece en 12 horas.

Para obtener los resultados de comandos y scripts que se ejecutan en sesiones desconectadas, use el Receive-PSSession cmdlet .

Ejemplo 19: Ejecución de un comando en un equipo remoto mediante SSH

En este ejemplo se muestra cómo ejecutar un comando en un equipo remoto mediante Secure Shell (SSH). Si SSH está configurado en el equipo remoto para solicitar contraseñas, recibirá un mensaje de contraseña. De lo contrario, tendrá que usar la autenticación de usuario basada en claves SSH.

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

Ejemplo 20: Ejecutar un comando en un equipo remoto mediante SSH y especificar una clave de autenticación de usuario

En este ejemplo se muestra cómo ejecutar un comando en un equipo remoto mediante SSH y especificar un archivo de clave para la autenticación de usuario. No se le pedirá una contraseña a menos que se produzca un error en la autenticación de claves y el equipo remoto esté configurado para permitir la autenticación de contraseña básica.

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

Ejemplo 21: Ejecución de un archivo de script en varios equipos remotos mediante SSH como trabajo

En este ejemplo se muestra cómo ejecutar un archivo de script en varios equipos remotos mediante SSH y el conjunto de parámetros SSH Conectar ion. El parámetro SSH Conectar ion toma una matriz de tablas hash que contienen información de conexión para cada equipo. En este ejemplo se requiere que los equipos remotos de destino tengan SSH configurado para admitir la autenticación de usuario basada en claves.

$sshConnections = @(
    @{
        HostName    = "WinServer1"
        UserName    = "Domain\UserA"
        KeyFilePath = "C:\Users\UserA\id_rsa"
    }
    @{
        HostName    = "UserB@LinuxServer5"
        KeyFilePath = "/Users/UserB/id_rsa"
    }
)
$results = Invoke-Command -FilePath c:\Scripts\GetInfo.ps1 -SSHConnection $sshConnections

Ejemplo 22: Conectar a una sesión de SSH remota mediante las opciones de SSH

En este ejemplo se muestra cómo ejecutar un archivo de script en una máquina remota basada en Linux mediante opciones ssh. El parámetro Options toma una tabla hash de valores que se pasan como opciones al comando subyacente ssh el establecido la conexión al sistema remoto.

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

Parámetros

-AllowRedirection

Permite redirigir esta conexión a un identificador uniforme de recursos alternativo (URI).

Cuando se usa el parámetro Conectar ionURI, el destino remoto puede devolver una instrucción para redirigir a otro URI. De forma predeterminada, PowerShell no redirige las conexiones, pero puede usar este parámetro para permitir que redirija la conexión.

También puede limitar el número de veces que se redirige la conexión cambiando el valor de la opción de sesión Maximum Conectar ionRedirectionCount. Use el parámetro MaximumRedirection del New-PSSessionOption cmdlet o establezca la propiedad Maximum Conectar ionRedirectionCount de la $PSSessionOption variable de preferencia. El valor predeterminado es 5.

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

-ApplicationName

Escriba el segmento del nombre de aplicación del URI de conexión. Use este parámetro para especificar el nombre de la aplicación cuando no use el parámetro Conectar ionURI en el comando .

El valor predeterminado es el valor de la $PSSessionApplicationName variable de preferencia en el equipo local. Si no se define esta variable de preferencia, el valor predeterminado es WSMAN. Este valor resulta apropiado en la mayoría de los casos. Para obtener más información, consulte about_Preference_Variables.

El servicio WinRM usa el nombre de aplicación para seleccionar un agente de escucha que atienda la solicitud de conexión. El valor de este parámetro debe coincidir con el valor de la propiedad URLPrefix de un agente de escucha en el equipo remoto.

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

-ArgumentList

Proporciona los valores de los parámetros para el scriptblock. Los parámetros del bloque de script se pasan por posición del valor de matriz proporcionado a ArgumentList. Esto se conoce como expansión de matriz. Para obtener más información sobre el comportamiento de ArgumentList, vea about_Splatting.

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

-AsJob

Indica que este cmdlet ejecuta el comando como un trabajo en segundo plano en un equipo remoto. Use este parámetro para ejecutar comandos que tardan mucho tiempo en finalizar.

Cuando se usa el parámetro AsJob , el comando devuelve un objeto que representa el trabajo y, a continuación, muestra el símbolo del sistema. Puede seguir trabajando en la sesión mientras finaliza el trabajo. Para administrar el trabajo, use los *-Job cmdlets. Para obtener los resultados del trabajo, use el Receive-Job cmdlet .

El parámetro AsJob es similar al uso del Invoke-Command cmdlet para ejecutar un Start-Job cmdlet de forma remota. Sin embargo, con AsJob, el trabajo se crea en el equipo local, aunque el trabajo se ejecute en un equipo remoto. Los resultados del trabajo remoto se devuelven automáticamente al equipo local.

Para obtener más información sobre los trabajos en segundo plano de PowerShell, consulte about_Jobs y about_Remote_Jobs.

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

-Authentication

Especifica el mecanismo que se usa para autenticar las credenciales del usuario. La autenticación CredSSP solo está disponible en Windows Vista, Windows Server 2008 y versiones posteriores del sistema operativo Windows.

Los valores aceptables para este parámetro son los siguientes:

• Valor predeterminado
• Basic
• Credssp
• Digest
• Kerberos
• Negotiate
• NegotiateWithImplicitCredential

El valor predeterminado es Default.

Para obtener más información sobre los valores de este parámetro, vea AuthenticationMechanism (enumeración).

Precaución

La autenticación del proveedor de soporte técnico de seguridad de credenciales (CredSSP), en la que las credenciales del usuario se pasan a un equipo remoto para autenticarse, está diseñada para comandos que requieren autenticación en más de un recurso, como el acceso a un recurso compartido de red remoto. Este mecanismo el riesgo de seguridad de la operación remota. Si el equipo remoto se ve comprometido, las credenciales que se pasen a él se pueden utilizar para controlar la sesión de red. Para obtener más información, consulte Proveedor de compatibilidad con seguridad de credenciales.

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

-CertificateThumbprint

Especifica el certificado de clave pública digital (X509) de una cuenta de usuario que tiene permiso para conectarse a la sesión desconectada. Escriba la huella digital del certificado.

Los certificados se usan para la autenticación basada en certificados de cliente. Solo se pueden asignar a cuentas de usuario locales y no funcionan con cuentas de dominio.

Para obtener una huella digital de certificado, use un Get-Item comando o Get-ChildItem en la unidad Cert: de PowerShell.

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

-ComputerName

Especifica los equipos en los que se ejecuta el comando. La opción predeterminada es el equipo local.

Cuando se usa el parámetro ComputerName , PowerShell crea una conexión temporal que solo se usa para ejecutar el comando especificado y, a continuación, se cierra. Si necesita una conexión persistente, use el parámetro Session .

Escriba el nombre NETBIOS, la dirección IP o el nombre de dominio completo de uno o varios equipos en una lista separada por comas. Para especificar el equipo local, escriba el nombre del equipo, localhost o un punto (.).

Para usar una dirección IP en el valor de ComputerName, el comando debe incluir el parámetro Credential . El equipo debe configurarse para el transporte HTTPS o la dirección IP del equipo remoto debe incluirse en la lista de Host de confianza de WinRM del equipo local. Para obtener instrucciones para agregar un nombre de equipo a la lista TrustedHosts , vea How to Add a Computer to the Trusted Host List.

En Windows Vista y versiones posteriores del sistema operativo Windows, para incluir el equipo local en el valor de ComputerName, debe ejecutar PowerShell mediante la opción Ejecutar como administrador .

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

-ConfigurationName

Especifica la configuración de sesión que se usa para la nueva PSSession.

Escriba un nombre de configuración o el URI de un recurso completo para configurar una sesión. Si especifica solo el nombre de configuración, se antepone el siguiente URI de esquema: http://schemas.microsoft.com/PowerShell.

Cuando se usa con SSH, este parámetro especifica el subsistema que se va a usar en el destino tal como se define en sshd_config. El valor predeterminado de SSH es el powershell subsistema.

La configuración de sesión para una sesión se encuentra en el equipo remoto. Si la configuración de sesión especificada no existe en el equipo remoto, se produce un error en el comando.

El valor predeterminado es el valor de la $PSSessionConfigurationName variable de preferencia en el equipo local. Si no se establece esta variable de preferencia, el valor predeterminado es Microsoft.PowerShell. Para obtener más información, consulte about_Preference_Variables.

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

-ConnectingTimeout

Especifica la cantidad de tiempo en milisegundos permitidos para que se complete la conexión SSH inicial. Si la conexión no se completa en el tiempo especificado, se devuelve un error.

Este parámetro se introdujo en PowerShell 7.2

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

-ConnectionUri

Especifica un identificador uniforme de recursos (URI) que define el extremo de la conexión de la sesión. El identificador URI debe ser completo.

El formato de esta cadena es:

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

El valor predeterminado es el siguiente:

http://localhost:5985/WSMAN

Si no especifica un URI de conexión, puede usar los parámetros UseSSL y Port para especificar los valores de URI de conexión.

Los valores válidos para el segmento Transporte del URI son HTTP y HTTPS. Si especifica un URI de conexión con un segmento de transporte, pero no especifica un puerto, la sesión se crea con los puertos de estándares: 80 para HTTP y 443 para HTTPS. Para usar los puertos predeterminados para la comunicación remota de PowerShell, especifique el puerto 5985 para HTTP o 5986 para HTTPS.

Si el equipo de destino redirige la conexión a un URI diferente, PowerShell impide el redireccionamiento a menos que use el parámetro AllowRedirection en el comando.

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

-ContainerId

Especifica una matriz de identificadores de contenedor.

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

-Credential

Especifica una cuenta de usuario con permiso para realizar esta acción. El valor predeterminado es el usuario actual.

Escriba un nombre de usuario, como User01 o Domain01\User01, o escriba un objeto PSCredential generado por el Get-Credential cmdlet . Si escribe un nombre de usuario, se le pedirá que escriba la contraseña.

Las credenciales se almacenan en un objeto PSCredential y la contraseña se almacena como SecureString.

Nota:

Para obtener más información sobre la protección de datos SecureString , consulte ¿Cómo es secure is SecureString?.

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

-EnableNetworkAccess

Indica que este cmdlet agrega un token de seguridad interactivo a las sesiones de bucle invertido. El token interactivo permite ejecutar comandos en la sesión de bucle invertido que obtienen datos de otros equipos. Por ejemplo, se puede ejecutar un comando en la sesión que copie los archivos XML de un equipo remoto al equipo local.

Una sesión de bucle invertido es una PSSession que se origina y termina en el mismo equipo. Para crear una sesión de bucle invertido, omita el parámetro ComputerName o establezca su valor en dot (.), localhost o el nombre del equipo local.

De forma predeterminada, las sesiones de bucle invertido se crean mediante un token de red, lo que podría no proporcionar permiso suficiente para autenticarse en equipos remotos.

El parámetro EnableNetworkAccess solo es efectivo en sesiones de bucle invertido. Si usa EnableNetworkAccess al crear una sesión en un equipo remoto, el comando se realiza correctamente, pero el parámetro se omite.

Puede permitir el acceso remoto en una sesión de bucle invertido mediante el valor CredSSP del parámetro Authentication , que delega las credenciales de sesión en otros equipos.

Para proteger el equipo contra el acceso malintencionado, las sesiones de bucle invertido desconectadas que tienen tokens interactivos, que son los creados mediante EnableNetworkAccess, solo se pueden volver a conectar desde el equipo en el que se creó la sesión. Las sesiones desconectadas que usan la autenticación CredSSP se pueden volver a conectar desde otros equipos. Para obtener más información, vea Disconnect-PSSession.

Este parámetro se introdujo en PowerShell 3.0.

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

-FilePath

Especifica un script local que este cmdlet se ejecuta en uno o varios equipos remotos. Escriba la ruta de acceso y el nombre de archivo del script, o canalice una ruta de acceso de script a Invoke-Command. El script debe existir en el equipo local o en un directorio al que pueda acceder el equipo local. Use ArgumentList para especificar los valores de los parámetros en el script.

Cuando se usa este parámetro, PowerShell convierte el contenido del archivo de script especificado en un bloque de script, transmite el bloque de script al equipo remoto y lo ejecuta en el equipo remoto.

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

-HideComputerName

Indica que este cmdlet omite el nombre de equipo de cada objeto de la presentación de salida. De forma predeterminada, el nombre de equipo que generó el objeto aparece en la pantalla.

Este parámetro afecta únicamente a los resultados mostrados. No cambia el objeto.

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

-HostName

Especifica una matriz de nombres de equipo para una conexión basada en Secure Shell (SSH). Esto es similar al parámetro ComputerName , excepto que la conexión al equipo remoto se realiza mediante SSH en lugar de Windows WinRM.

Este parámetro se introdujo en PowerShell 6.0.

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

-InDisconnectedSession

Indica que este cmdlet ejecuta un comando o script en una sesión desconectada.

Cuando se usa el parámetro InDisconnectedSession , Invoke-Command se crea una sesión persistente en cada equipo remoto, se inicia el comando especificado por el parámetro ScriptBlock o FilePath y, a continuación, se desconecta de la sesión. Los comandos continúan ejecutándose en las sesiones desconectadas. InDisconnectedSession permite ejecutar comandos sin mantener una conexión a las sesiones remotas. Además, dado que la sesión está desconectada antes de que se devuelvan los resultados, InDisconnectedSession garantiza que todos los resultados del comando se devuelvan a la sesión reconectada, en lugar de dividirse entre sesiones.

No se puede usar InDisconnectedSession con el parámetro Session o el parámetro AsJob.

Los comandos que usan InDisconnectedSession devuelven un objeto PSSession que representa la sesión desconectada. No devuelven la salida del comando. Para conectarse a la sesión desconectada, use los Connect-PSSession cmdlets o Receive-PSSession . Para obtener los resultados de los comandos que se ejecutaron en la sesión, use el Receive-PSSession cmdlet . Para ejecutar comandos que generan la salida en una sesión desconectada, establezca el valor de la opción de sesión OutputBufferingMode en Quitar. Si piensa conectarse a la sesión desconectada, establezca el tiempo de espera de inactividad en la sesión para que proporcione tiempo suficiente para conectarse antes de eliminar la sesión.

Puede establecer el modo de almacenamiento en búfer de salida y el tiempo de espera de inactividad en el parámetro SessionOption o en la variable de $PSSessionOption preferencia. Para obtener más información sobre las opciones de sesión, consulte New-PSSessionOption y about_Preference_Variables.

Para obtener más información sobre la característica Sesiones desconectadas, consulte about_Remote_Disconnected_Sessions.

Este parámetro se introdujo en PowerShell 3.0.

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

-InputObject

Especifica entradas del comando. Especifique una variable que contenga los objetos, o escriba un comando o una expresión que obtenga los objetos.

Al usar el parámetro InputObject , use la $Input variable automática en el valor del parámetro ScriptBlock para representar los objetos de entrada.

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

-JobName

Especifica un nombre descriptivo para el trabajo en segundo plano. De forma predeterminada, los trabajos se denominan Job<n>, donde <n> es un número ordinal.

Si usa el parámetro JobName en un comando, el comando se ejecuta como un trabajo y Invoke-Command devuelve un objeto de trabajo, aunque no incluya AsJob en el comando.

Para obtener más información sobre los trabajos en segundo plano de PowerShell, consulte about_Jobs.

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

-KeyFilePath

Especifica una ruta de acceso de archivo de clave usada por Secure Shell (SSH) para autenticar a un usuario en un equipo remoto.

SSH permite realizar la autenticación de usuario a través de claves públicas y privadas como alternativa a la autenticación de contraseña básica. Si el equipo remoto está configurado para la autenticación de claves, este parámetro se puede usar para proporcionar la clave que identifica al usuario.

Este parámetro se introdujo en PowerShell 6.0.

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

-NoNewScope

Indica que este cmdlet ejecuta el comando especificado en el ámbito actual. De forma predeterminada, Invoke-Command ejecuta comandos en su propio ámbito.

Este parámetro solo es válido en los comandos que se ejecutan en la sesión actual, es decir, los comandos que omiten los parámetros ComputerName y Session .

Este parámetro se introdujo en PowerShell 3.0.

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

-Options

Especifica una tabla hash de las opciones ssh que se usan al conectarse a una sesión remota basada en SSH. Las opciones posibles son los valores admitidos por la versión basada en Unix del comando ssh .

Los valores pasados explícitamente por parámetros tienen prioridad sobre los valores pasados en la tabla hash Options . Por ejemplo, el uso del parámetro Port invalida cualquier Port par clave-valor pasado en la tabla hash Options.

Este parámetro se agregó en PowerShell 7.3.

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

-Port

Especifica el puerto de red en el equipo remoto que se usa para este comando. Para conectarse a un equipo remoto, este debe estar escuchando en el puerto que usa la conexión. Los puertos predeterminados son 5985 (puerto WinRM para HTTP) y 5986 (puerto WinRM para HTTPS).

Antes de usar un puerto alternativo, configure el agente de escucha de WinRM en el equipo remoto para escuchar en ese puerto. Para configurar el agente de escucha, escriba los dos comandos siguientes en el símbolo del sistema de PowerShell:

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

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

No use el parámetro Port a menos que sea necesario. El puerto que se establece en el comando se aplica a todos los equipos o sesiones en que dicho comando se ejecuta. Una configuración de puerto alternativo podría impedir que el comando se ejecutara en todos los equipos.

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

-RemoteDebug

Se usa para ejecutar el comando invocado en modo de depuración en la sesión remota de PowerShell.

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

-RunAsAdministrator

Indica que este cmdlet invoca un comando como Administración istrator.

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

-ScriptBlock

Especifica los comandos que se van a ejecutar. Incluya los comandos entre llaves ({ }) para crear un bloque de script. Cuando se usa Invoke-Command para ejecutar un comando de forma remota, las variables del comando se evalúan en el equipo remoto.

Nota:

Los parámetros del scriptblock solo se pueden pasar desde ArgumentList por posición. Los parámetros switch no se pueden pasar por posición. Si necesita un parámetro que se comporte como un tipo SwitchParameter , use un tipo booleano en su lugar.

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

-Session

Especifica una matriz de sesiones en las que este cmdlet ejecuta el comando . Escriba una variable que contenga objetos PSSession o un comando que cree o obtenga los objetos PSSession , como un New-PSSession comando o Get-PSSession .

Al crear una PSSession, PowerShell establece una conexión persistente al equipo remoto. Use una PSSession para ejecutar una serie de comandos relacionados que comparten datos. Para ejecutar un único comando o una serie de comandos no relacionados, use el parámetro ComputerName . Para obtener más información, consulte about_PSSessions.

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

-SessionName

Especifica un nombre descriptivo para una sesión desconectada. Puede usar el nombre para hacer referencia a la sesión en comandos posteriores, como un Get-PSSession comando. Este parámetro solo es válido con el parámetro InDisconnectedSession .

Este parámetro se introdujo en PowerShell 3.0.

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

-SessionOption

Especifica opciones avanzadas para la sesión. Escriba un objeto SessionOption , como uno que cree mediante el New-PSSessionOption cmdlet o una tabla hash en la que las claves son nombres de opción de sesión y los valores son valores de opción de sesión.

Nota:

Si especifica una tabla hash para SessionOption, PowerShell convierte la tabla hash en un objeto System.Management.Autiomation.Remoting.PSSessionOption . Los valores de las claves especificadas en la tabla hash se convierten en la propiedad coincidente del objeto . Esto se comporta de forma diferente a la llamada a New-PSSessionOption. Por ejemplo, los valores System.TimeSpan de las propiedades de tiempo de espera, como IdleTimeout, convierten un valor entero en tics en lugar de milisegundos. Para obtener más información sobre el objeto PSSessionOption y sus propiedades, consulte PSSessionOption.

Los valores predeterminados de las opciones se determinan mediante el valor de la $PSSessionOption variable de preferencia, si se establece. De lo contrario, los valores predeterminados se establecerán mediante las opciones establecidas en la configuración de sesión.

Los valores de opción de sesión tienen prioridad sobre los valores predeterminados de las sesiones establecidas en la $PSSessionOption variable de preferencia y en la configuración de la sesión. Sin embargo, no tienen prioridad sobre los valores máximos, cuotas o límites establecidos en la configuración de sesión.

Para obtener una descripción de las opciones de sesión que incluye los valores predeterminados, consulte New-PSSessionOption. Para obtener información sobre la $PSSessionOption variable de preferencia, consulte about_Preference_Variables. Para más información sobre las configuraciones de sesión, vea about_Session_Configurations.

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

-SSHConnection

Este parámetro toma una matriz de tablas hash donde cada tabla hash contiene uno o varios parámetros de conexión necesarios para establecer una conexión de Secure Shell (SSH). El parámetro SSH Conectar ion es útil para crear varias sesiones en las que cada sesión requiere información de conexión diferente.

La tabla hash tiene los siguientes miembros:

• NombreDeEquipo (o Nombre de host)
• Puerto
• UserName
• KeyFilePath (o IdentityFilePath)

ComputerName (o HostName) es el único par clave-valor necesario.

Este parámetro se introdujo en PowerShell 6.0.

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

-SSHTransport

Indica que la conexión remota se establece mediante Secure Shell (SSH).

De forma predeterminada, PowerShell usa Windows WinRM para conectarse a un equipo remoto. Este modificador obliga a PowerShell a usar el parámetro HostName para establecer una conexión remota basada en SSH.

Este parámetro se introdujo en PowerShell 6.0.

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

-Subsystem

Especifica el subsistema SSH usado para la nueva PSSession.

Especifica el subsistema que se va a usar en el destino tal como se define en sshd_config. El subsistema inicia una versión específica de PowerShell con parámetros predefinidos. Si el subsistema especificado no existe en el equipo remoto, se produce un error en el comando.

Si no se usa este parámetro, el valor predeterminado es el powershell subsistema.

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

-ThrottleLimit

Especifica el número máximo de operaciones simultáneas que se pueden establecer para ejecutar este comando. Si omite este parámetro o escribe un valor 0, se usa el valor predeterminado, 32.

El límite solo se aplica al comando actual, no a la sesión ni al equipo.

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

-UserName

Especifica el nombre de usuario de la cuenta usada para ejecutar un comando en el equipo remoto. El método de autenticación de usuario depende de cómo se configura Secure Shell (SSH) en el equipo remoto.

Si SSH está configurado para la autenticación de contraseña básica, se le pedirá la contraseña de usuario.

Si SSH está configurado para la autenticación de usuario basada en claves, se puede proporcionar una ruta de acceso del archivo de claves a través del parámetro KeyFilePath y no se produce ningún mensaje de contraseña. Si el archivo de clave de usuario del cliente se encuentra en una ubicación conocida de SSH, el parámetro KeyFilePath no es necesario para la autenticación basada en claves y la autenticación del usuario se produce automáticamente en función del nombre de usuario. Para más información, consulte la documentación de SSH de la plataforma sobre la autenticación de usuario basada en claves.

No es un parámetro obligatorio. Si no se especifica el parámetro UserName , se usa el nombre de usuario que inició sesión actual para la conexión.

Este parámetro se introdujo en PowerShell 6.0.

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

-UseSSL

Indica que este cmdlet usa el protocolo Capa de sockets seguros (SSL) para establecer una conexión con el equipo remoto. De forma predeterminada, no se usa SSL.

WS-Management cifra todo el contenido de PowerShell transmitido a través de la red. El parámetro UseSSL es una protección adicional que envía los datos a través de HTTPS, en lugar de HTTP.

Si usa este parámetro, pero SSL no está disponible en el puerto que se usa para el comando, se produce un error en el comando.

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

-VMId

Especifica una matriz de identificadores de máquinas virtuales.

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

-VMName

Especifica una matriz de nombres de máquinas virtuales.

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

Entradas

ScriptBlock

Puede canalizar un comando en un bloque de script a Invoke-Command. Use la $Input variable automática para representar los objetos de entrada en el comando .

Salidas

System.Management.Automation.PSRemotingJob

Si usa el parámetro AsJob , este cmdlet devuelve un objeto de trabajo.

PSSession

Si usa el parámetro InDisconnectedSession , este cmdlet devuelve un objeto PSSession .

Object

De forma predeterminada, este cmdlet devuelve la salida del comando invocado, que es el valor del parámetro ScriptBlock .

Notas

PowerShell incluye los siguientes alias para Invoke-Command:

• Todas las plataformas:
  • icm

En Windows Vista y versiones posteriores del sistema operativo Windows, para usar el parámetro ComputerName de Invoke-Command para ejecutar un comando en el equipo local, debe ejecutar PowerShell mediante la opción Ejecutar como administrador .

Al ejecutar comandos en varios equipos, PowerShell se conecta a los equipos en el orden en que aparecen en la lista. Sin embargo, la salida del comando se muestra en el orden en que se recibe de los equipos remotos, lo que puede ser diferente.

Los errores resultantes del comando que Invoke-Command se ejecuta se incluyen en los resultados del comando. Los errores que podrían suponer la terminación de un comando local se tratan como errores de no terminación en un comando remoto. Esta estrategia garantiza que los errores de terminación de un equipo no cierren el comando en todos los equipos en los que se ejecuta. Esta práctica se utiliza incluso cuando se ejecuta un comando remoto en un único equipo.

Si el equipo remoto no está en un dominio en el que confía el equipo local, es posible que el equipo no pueda autenticar las credenciales del usuario. Para agregar el equipo remoto a la lista de hosts de confianza en WS-Management, use el siguiente comando en el WSMAN proveedor, donde <Remote-Computer-Name> es el nombre del equipo remoto:

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

Cuando se desconecta una PSSession mediante el parámetro InDisconnectedSession , el estado de sesión es Disconnected y la disponibilidad es None. El valor de la propiedad State es relativo a la sesión actual. Un valor de Disconnected significa que PSSession no está conectado a la sesión actual. Sin embargo, no significa que PSSession se desconecte de todas las sesiones. Podría estar conectada a una sesión diferente. Para determinar si puede conectarse o volver a conectarse a la sesión, use la propiedad Availability .

Un valor de Disponibilidad de None indica que puede conectarse a la sesión. Un valor de Busy indica que no se puede conectar a PSSession porque está conectado a otra sesión. Para obtener más información sobre los valores de la propiedad State de las sesiones, vea RunspaceState. Para obtener más información sobre los valores de la propiedad Availability de las sesiones, vea RunspaceAvailability.

Los parámetros HostName y SSH Conectar ion se incluyeron a partir de PowerShell 6.0. Se agregaron para proporcionar comunicación remota de PowerShell basada en Secure Shell (SSH). PowerShell y SSH son compatibles con varias plataformas (Windows, Linux, macOS) y la comunicación remota de PowerShell funcionan en estas plataformas en las que PowerShell y SSH están instalados y configurados. Esto es independiente de la comunicación remota anterior de Windows basada en WinRM y muchas de las características y limitaciones específicas de WinRM no se aplican. Por ejemplo, las cuotas basadas en WinRM, las opciones de sesión, la configuración del punto de conexión personalizado y las características de desconexión o reconexión no se admiten actualmente. Para obtener más información sobre cómo configurar la comunicación remota ssh de PowerShell, consulte Comunicación remota de PowerShell a través de SSH.

El ssh ejecutable obtiene los datos de configuración de los orígenes siguientes en el orden siguiente:

1. opciones de línea de comandos
2. Archivo de configuración del usuario (~/.ssh/config)
3. Archivo de configuración de todo el sistema (/etc/ssh/ssh_config)

Los siguientes parámetros de cmdlet se asignan a ssh parámetros y opciones:

Parámetro del cmdlet	parámetro ssh	opción ssh -o equivalente
-KeyFilePath	-i <KeyFilePath>	-o IdentityFile=<KeyFilePath>
-UserName	-l <UserName>	-o User=<UserName>
-Port	-p <Port>	-o Port=<Port>
-ComputerName -Subsystem	-s <ComputerName> <Subsystem>	-o Host=<ComputerName>

Los valores pasados explícitamente por parámetros tienen prioridad sobre los valores pasados en la tabla hash Options . Para obtener más información sobre ssh_config los archivos, vea ssh_config(5).

Vínculos relacionados

• about_PSSessions
• about_Remote
• about_Remote_Disconnected_Sessions
• about_Remote_Troubleshooting
• about_Remote_Variables
• about_Scopes
• Enter-PSSession
• Exit-PSSession
• Get-PSSession
• Invoke-Item
• New-PSSession
• Remove-PSSession
• Proveedor de WSMan