Compartir a través de

Connect-PSSession

  • Referencia
Módulo:
Microsoft.PowerShell.Core

Vuelve a establecer la conexión con las sesiones desconectadas.

Syntax

Connect-PSSession
       -Name <String[]>
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       [-Session] <PSSession[]>
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       -ComputerName <String[]>
       [-ApplicationName <String>]
       [-ConfigurationName <String>]
       -InstanceId <Guid[]>
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-Port <Int32>]
       [-UseSSL]
       [-SessionOption <PSSessionOption>]
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       -ComputerName <String[]>
       [-ApplicationName <String>]
       [-ConfigurationName <String>]
       [-Name <String[]>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-Port <Int32>]
       [-UseSSL]
       [-SessionOption <PSSessionOption>]
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       [-ConfigurationName <String>]
       [-ConnectionUri] <Uri[]>
       [-AllowRedirection]
       -InstanceId <Guid[]>
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-SessionOption <PSSessionOption>]
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       [-ConfigurationName <String>]
       [-ConnectionUri] <Uri[]>
       [-AllowRedirection]
       [-Name <String[]>]
       [-Credential <PSCredential>]
       [-Authentication <AuthenticationMechanism>]
       [-CertificateThumbprint <String>]
       [-SessionOption <PSSessionOption>]
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       -InstanceId <Guid[]>
       [-ThrottleLimit <Int32>]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]
Connect-PSSession
       [-ThrottleLimit <Int32>]
       [-Id] <Int32[]>
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Description

El cmdlet Connect-PSSession se vuelve a conectar a sesiones de Windows PowerShell administradas por el usuario (PSSessions) que se desconectaron. Funciona en sesiones que se desconectan intencionadamente, como mediante el cmdlet Disconnect-PSSession o el parámetro InDisconnectedSession del cmdlet Invoke-Command, y los que se desconectaron involuntariamente, como por una interrupción temporal de la red.

Connect-PSSession puede conectarse a cualquier sesión desconectada iniciada por el mismo usuario. Entre ellas se incluyen las iniciadas por o desconectadas de otras sesiones en otros equipos.

Sin embargo, Connect-PSSession no puede conectarse a sesiones interrumpidas o cerradas, o sesiones interactivas iniciadas mediante el cmdlet Enter-PSSession. Tampoco se puede conectar sesiones a sesiones iniciadas por otros usuarios, a menos que pueda proporcionar las credenciales del usuario que creó la sesión.

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

Este cmdlet se introdujo en Windows PowerShell 3.0.

Ejemplos

Ejemplo 1: Volver a conectarse a una sesión

PS C:\> Connect-PSSession -ComputerName Server01 -Name ITTask
Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 4 ITTask          Server01        Opened        ITTasks                  Available

Este comando vuelve a conectarse a la sesión ITTask en el equipo Server01.

El resultado muestra que el comando se ejecutó correctamente. El estado de la sesión es Abierto y la disponibilidad está disponible, lo que indica que puede ejecutar comandos en la sesión.

Ejemplo 2: Efecto de la desconexión y reconexión

PS C:\> Get-PSSession

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 Backups         Localhost       Opened        Microsoft.PowerShell     Available


PS C:\> Get-PSSession | Disconnect-PSSession

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 Backups         Localhost       Disconnected  Microsoft.PowerShell          None


PS C:\> Get-PSSession | Connect-PSSession

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 Backups         Localhost       Opened        Microsoft.PowerShell     Available

En este ejemplo se muestra el efecto de desconectarse de una sesión y volver a conectarse.

El primer comando usa el cmdlet Get-PSSession. Sin el parámetro ComputerName, el comando obtiene solo las sesiones que se crearon en la sesión actual.

El resultado muestra que el comando obtiene la sesión Backups en el equipo local. El estado de la sesión se abre y la disponibilidad está disponible.

El segundo comando usa el cmdlet Get-PSSession para obtener los objetos PSSession que se crearon en la sesión actual y el cmdlet Disconnect-PSSession para desconectar las sesiones. El resultado muestra que la sesión Backups se desconectó. El estado de la sesión es Desconectado y la disponibilidad es None.

El tercer comando usa el cmdlet Get-PSSession para obtener los objetos PSSession que se crearon en la sesión actual y el cmdlet Connect-PSSession para volver a conectar las sesiones. El resultado muestra que la sesión Backups se volvió a conectar. El estado de la sesión se abre y la disponibilidad está disponible.

Si usa el cmdlet Connect-PSSession en una sesión que no está desconectada, el comando no afecta a la sesión y no genera ningún error.

Ejemplo 3: Serie de comandos en un escenario empresarial

The administrator starts by creating a sessions on a remote computer and running a script in the session.The first command uses the **New-PSSession** cmdlet to create the ITTask session on the Server01 remote computer. The command uses the *ConfigurationName* parameter to specify the ITTasks session configuration. The command saves the sessions in the $s variable.
PS C:\> $s = New-PSSession -ComputerName Server01 -Name ITTask -ConfigurationName ITTasks

 The second command **Invoke-Command** cmdlet to start a background job in the session in the $s variable. It uses the *FilePath* parameter to run the script in the background job.
PS C:\> Invoke-Command -Session $s {Start-Job -FilePath \\Server30\Scripts\Backup-SQLDatabase.ps1}
Id     Name            State         HasMoreData     Location             Command
--     ----            -----         -----------     --------             -------
2      Job2            Running       True            Server01             \\Server30\Scripts\Backup...

The third command uses the Disconnect-PSSession cmdlet to disconnect from the session in the $s variable. The command uses the *OutputBufferingMode* parameter with a value of Drop to prevent the script from being blocked by having to deliver output to the session. It uses the *IdleTimeoutSec* parameter to extend the session time-out to 15 hours.When the command is completed, the administrator locks her computer and goes home for the evening.
PS C:\> Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15
Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 ITTask          Server01        Disconnected  ITTasks               None

Later that evening, the administrator starts her home computer, logs on to the corporate network, and starts Windows PowerShell. The fourth command uses the Get-PSSession cmdlet to get the sessions on the Server01 computer. The command finds the ITTask session.The fifth command uses the **Connect-PSSession** cmdlet to connect to the ITTask session. The command saves the session in the $s variable.
PS C:\> Get-PSSession -ComputerName Server01 -Name ITTask

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 ITTask          Server01        Disconnected  ITTasks               None


PS C:\> $s = Connect-PSSession -ComputerName Server01 -Name ITTask


Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 ITTask          Server01        Opened        ITTasks               Available

The sixth command uses the **Invoke-Command** cmdlet to run a Get-Job command in the session in the $s variable. The output shows that the job finished successfully.The seventh command uses the **Invoke-Command** cmdlet to run a Receive-Job command in the session in the $s variable in the session. The command saves the results in the $BackupSpecs variable.The eighth command uses the **Invoke-Command** cmdlet to runs another script in the session. The command uses the value of the $BackupSpecs variable in the session as input to the script.


PS C:\> Invoke-Command -Session $s {Get-Job}

Id     Name            State         HasMoreData     Location             Command
--     ----            -----         -----------     --------             -------
2      Job2            Completed     True            Server01             \\Server30\Scripts\Backup...

PS C:\> Invoke-Command -Session $s {$BackupSpecs = Receive-Job -JobName Job2}

PS C:\> Invoke-Command -Session $s {\\Server30\Scripts\New-SQLDatabase.ps1 -InitData $BackupSpecs.Initialization}

The ninth command disconnects from the session in the $s variable.The administrator closes Windows PowerShell and closes the computer. She can reconnect to the session on the next day and check the script status from her work computer.
PS C:\> Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15
Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 ITTask          Server01        Disconnected  ITTasks               None

Esta serie de comandos muestra cómo el cmdlet Connect-PSSession podría utilizarse en un escenario empresarial. En este caso, un administrador del sistema inicia un trabajo de larga duración en una sesión en un equipo remoto. Después de iniciar el trabajo, el administrador se desconecta de la sesión y regresa a casa. Más tarde esa noche, el administrador inicia sesión en su equipo doméstico y comprueba que el trabajo se ejecutó hasta que se complete.

Parámetros

-AllowRedirection

Indica que este cmdlet permite el redireccionamiento de esta conexión a un URI alternativo.

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

De igual modo, se puede limitar el número de veces que la conexión se redirecciona; para ello, hay que cambiar el valor de la opción de sesión MaximumConnectionRedirectionCount. Utilice el parámetro MaximumRedirection del cmdlet New-PSSessionOption o establezca la propiedad MaximumConnectionRedirectionCount de la variable de preferencia $PSSessionOption . El valor predeterminado es 5.

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

-ApplicationName

Especifica el nombre de una aplicación. Este cmdlet solo se conecta a las sesiones que usan la aplicación especificada.

Escriba el segmento de nombre de aplicación del URI de conexión. Por ejemplo, en el siguiente URI de conexión, el nombre de la aplicación es WSMan: https://localhost:5985/WSMAN. El nombre de aplicación de una sesión se almacena en la propiedad Runspace.ConnectionInfo.AppName de la sesión.

El valor de este parámetro sirve para seleccionar y filtrar las sesiones. No cambia la aplicación que la sesión utiliza.

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

-Authentication

Especifica el mecanismo que se usa para autenticar las credenciales de usuario en el comando para volver a conectarse a la sesión desconectada. Los valores permitidos para este parámetro son los siguientes:

  • Default
  • Básico
  • 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 Enumeration en MSDN Library.

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.

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:None
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. No funcionan con cuentas de dominio.

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

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

-ComputerName

Especifica los equipos donde se almacenan las sesiones desconectadas. Las sesiones se almacenan en el equipo que se encuentra en el lado servidor o reciben el final de una conexión. La opción predeterminada es el equipo local.

Escriba el nombre NetBIOS, una dirección IP o un nombre de dominio completo de un equipo. No se admite el uso de caracteres comodín. Para especificar el equipo local, escriba el nombre del equipo, localhost o un punto (.)

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

-ConfigurationName

Se conecta únicamente a las sesiones que usan la configuración de sesión especificada.

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: https://schemas.microsoft.com/powershell. El nombre de configuración de una sesión se almacena en la propiedad ConfigurationName de la sesión.

El valor de este parámetro sirve para seleccionar y filtrar las sesiones. No cambia la configuración de sesión que la sesión utiliza.

Para obtener más información sobre las configuraciones de sesión, consulte about_Session_Configurations.

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

-Confirm

Le solicita su confirmación antes de ejecutar el cmdlet.

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

-ConnectionUri

Especifica los URI de los puntos de conexión de las sesiones desconectadas.

El identificador URI debe ser completo. El formato de esta cadena es:

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

El valor predeterminado es el siguiente:

https://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 Transport del URI son HTTP y HTTPS. Si especifica un URI de conexión con un segmento transporte, pero no especifica un puerto, la sesión se crea con puertos estándar: 80 para HTTP y 443 para HTTPS. Para usar los puertos predeterminados para la comunicación remota de Windows PowerShell, especifique el puerto 5985 para HTTP o 5986 para HTTPS.

Si el equipo de destino redirige la conexión a otro URI, Windows PowerShell impide que la redirección se produzca, a menos que se use el parámetro AllowRedirection en el comando.

Type:Uri[]
Aliases:URI, CU
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Credential

Especifica una cuenta de usuario que tiene permiso para conectarse a la sesión desconectada. El valor predeterminado es el usuario actual.

Escriba un nombre de usuario, como Usuario01 o Dominio01\Usuario01. O bien, escriba un objeto PSCredential , como uno generado por el cmdlet Get-Credential. Si escribe un nombre de usuario, este cmdlet le pedirá una contraseña.

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

-Id

Especifica los identificadores de las sesiones desconectadas. El parámetro Id solo funciona cuando la sesión desconectada se conectó anteriormente a la sesión actual.

Este parámetro es válido, pero no tiene efecto alguno, si la sesión se almacena en el equipo local, pero no estaba conectada a la sesión actual.

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

-InstanceId

Especifica los identificadores de instancia de las sesiones desconectadas.

El identificador de instancia es un GUID que identifica de forma única una PSSession en un equipo local o remoto.

El identificador de instancia se almacena en la propiedad InstanceID de psSession.

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

-Name

Especifica los nombres descriptivos de las sesiones desconectadas.

Type:String[]
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 volver a conectar con la sesión. Para conectarse a un equipo remoto, este debe estar escuchando en el puerto que usa la conexión. Los puertos predeterminados son 5985, que es el puerto WinRM para HTTP y 5986, que es el puerto winRM para HTTPS.

Antes de usar un puerto alternativo, debe configurar el agente de escucha de WinRM en el equipo remoto para poder escuchar en ese puerto. Para configurar el agente de escucha, escriba los dos comandos siguientes en el símbolo del sistema de Windows 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

-Session

Especifica las sesiones desconectadas. Escriba una variable que contenga los objetos PSSession o un comando que crea u obtiene los objetos PSSession , como un comando Get-PSSession.

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

-SessionOption

Especifica opciones avanzadas para la sesión. Escriba un objeto SessionOption , como uno que cree mediante el cmdlet New-PSSessionOption, 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.

Los valores predeterminados de las opciones se determinan con el valor de la variable de preferencia $PSSessionOption, 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 precedencia sobre los valores predeterminados de las sesiones definidos en la variable de preferencia $PSSessionOption y en la configuración de sesión. Sin embargo, no tienen precedencia sobre los valores máximos, las cuotas o los 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 variable de preferencia de $PSSessionOption , consulte about_Preference_Variables. Para obtener más información sobre las configuraciones de sesión, consulte about_Session_Configurations.

Type:PSSessionOption
Position:Named
Default value:None
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: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 conectarse a la sesión desconectada. De forma predeterminada, no se usa SSL.

WS-Management cifra todo el contenido de Windows PowerShell que se transmite por la red. El parámetro UseSSL es una protección adicional que envía los datos a través de una conexión HTTPS en lugar de una conexión 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:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WhatIf

Muestra lo que sucedería si se ejecutara el cmdlet. El cmdlet no se ejecuta.

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

Entradas

PSSession

Puede canalizar una sesión (PSSession) a este cmdlet.

Salidas

PSSession

Este cmdlet devuelve un objeto que representa la sesión a la que se volvió a conectar.

Notas

  • Connect-PSSession solo se vuelve a conectar a las sesiones que están desconectadas, es decir, sesiones que tienen un valor de Disconnected para la propiedad State . Solo las sesiones conectadas a los equipos que ejecutan Windows PowerShell 3.0 o versiones posteriores se pueden desconectar y volver a conectar.

  • Si usa Connect-PSSession en una sesión que no está desconectada, el comando no afecta a la sesión y no genera errores.

  • Las sesiones de bucle invertido desconectadas con tokens interactivos, que se crean mediante el parámetro EnableNetworkAccess , solo se pueden volver a conectar desde el equipo en el que se creó la sesión. Esta restricción protege el equipo contra accesos malintencionados.

  • El valor de la propiedad State de una PSSession es relativo a la sesión actual. Por lo tanto, un valor de Disconnected significa que PSSession no está conectado a la sesión actual. Sin embargo, no significa que la PSSession se desconecte de todas las sesiones. Podría estar conectada a una sesión diferente. Para saber si se puede conectar o volver a conectar a la sesión, use la propiedad Availability.

    Un valor de Availability establecido en None indica que se puede conectar 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 Enumeration en MSDN Library.

    Para obtener más información sobre los valores de la propiedad Availability de las sesiones, vea RunspaceAvailability Enumeration en MSDN Library.

  • No se puede cambiar el valor de tiempo de espera de inactividad de una PSSession cuando se conecta a la PSSession. El parámetro SessionOption de Connect-PSSession toma un objeto SessionOption que tiene un valor IdleTimeout. Sin embargo, el valor IdleTimeout del objeto SessionOption y el valor IdleTimeout de la variable $PSSessionOption se omiten al conectarse a una PSSession.

    Puede establecer y cambiar el tiempo de espera de inactividad de una PSSession al crear la PSSession, mediante los cmdlets New-PSSession o Invoke-Command , y cuando se desconecta de PSSession.

    La propiedad IdleTimeout de una PSSession es fundamental para las sesiones desconectadas, ya que determina cuánto tiempo se mantiene una sesión desconectada en el equipo remoto. Las sesiones desconectadas se consideran como inactivas desde el momento en que se desconectan, aun cuando haya comandos ejecutándose en la sesión desconectada.