Connect-PSSession

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

Este cmdlet solo está disponible en la plataforma Windows.

El Connect-PSSession cmdlet se vuelve a conectar a sesiones de PowerShell administradas por el usuario (PSSessions) que se desconectaron. Funciona en sesiones que se desconectan intencionadamente, como mediante el Disconnect-PSSession cmdlet o el parámetro InDisconnectedSession del Invoke-Command cmdlet, y aquellos 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 se puede conectar a sesiones interrumpidas o cerradas, ni a sesiones interactivas iniciadas mediante el Enter-PSSession cmdlet . 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 obtener más información sobre la característica 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

Connect-PSSession -ComputerName Server01 -Name ITTask

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

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

El resultado muestra que el comando se ejecutó correctamente. El estado de la sesión es Opened y la disponibilidad es Available, que indica que puede ejecutar comandos en la sesión.

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

Get-PSSession

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

Get-PSSession | Disconnect-PSSession

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

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 Get-PSSession cmdlet . Sin el parámetro ComputerName , el comando obtiene solo las sesiones que se crearon en la sesión actual.

La salida muestra que el comando obtiene la Backups sesión en el equipo local. El estado de la sesión es Opened y la disponibilidad es Available.

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

El tercer comando usa el Get-PSSession cmdlet para obtener los objetos PSSession que se crearon en la sesión actual y el Connect-PSSession cmdlet para volver a conectar las sesiones. La salida muestra que la Backups sesión se ha vuelto a conectar. El estado de la sesión es Opened y la disponibilidad es Available.

Si usa el Connect-PSSession cmdlet 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

Esta serie de comandos muestra cómo se puede usar el Connect-PSSession cmdlet 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, el administrador inicia sesión en su equipo doméstico y comprueba que el trabajo se ejecutó hasta que se complete.

El administrador comienza creando sesiones en un equipo remoto y ejecutando un script en la sesión. El primer comando usa el New-PSSession cmdlet para crear la ITTask sesión en el equipo remoto Server01. El comando usa el parámetro ConfigurationName para especificar la configuración de sesión ITTasks . El comando guarda las sesiones en la $s variable .

El segundo cmdlet de comando Invoke-Command para iniciar un trabajo en segundo plano en la sesión de la $s variable . Usa el parámetro FilePath para ejecutar el script en el trabajo en segundo plano.

El tercer comando usa el Disconnect-PSSession cmdlet para desconectar de la sesión en la $s variable . El comando usa el parámetro OutputBufferingMode con un valor de Drop para evitar que el script se bloquee al tener que entregar la salida a la sesión. Usa el parámetro IdleTimeoutSec para ampliar el tiempo de espera de la sesión a 15 horas. Cuando se completa el comando, el administrador bloquea su equipo y se va a casa por la noche.

Más tarde, el administrador inicia su equipo doméstico, inicia sesión en la red corporativa e inicia PowerShell. El cuarto comando usa el Get-PSSession cmdlet para obtener las sesiones en el equipo Server01. El comando busca la ITTask sesión. El quinto comando usa el Connect-PSSession cmdlet para conectarse a la ITTask sesión. El comando guarda la sesión en la variable $s.

El sexto comando usa el Invoke-Command cmdlet para ejecutar un Get-Job comando en la sesión de la $s variable . La salida muestra que el trabajo finalizó correctamente. El séptimo comando usa el Invoke-Command cmdlet para ejecutar un Receive-Job comando en la sesión de la $s variable de la sesión. El comando guarda los resultados en la $BackupSpecs variable . El octavo comando usa el Invoke-Command cmdlet para ejecutar otro script en la sesión. El comando usa el valor de la $BackupSpecs variable en la sesión como entrada para el script.

$s = New-PSSession -ComputerName Server01 -Name ITTask -ConfigurationName ITTasks
Invoke-Command -Session $s -ScriptBlock {Start-Job -FilePath \\Server30\Scripts\Backup-SQLDatabase.ps1}

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

Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15

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

Get-PSSession -ComputerName Server01 -Name ITTask

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

$s = Connect-PSSession -ComputerName Server01 -Name ITTask

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

Invoke-Command -Session $s -ScriptBlock {Get-Job}

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

Invoke-Command -Session $s -ScriptBlock {$BackupSpecs = Receive-Job -JobName Job2}
Invoke-Command -Session $s -ScriptBlock {\\Server30\Scripts\New-SQLDatabase.ps1 -InitData $BackupSpecs.Initialization}
Disconnect-PSSession -Session $s -OutputBufferingMode Drop -IdleTimeoutSec 60*60*15

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

El noveno comando se desconecta de la sesión en la $s variable . El administrador cierra PowerShell y cierra el equipo. Puede volver a conectarse a la sesión el día siguiente y comprobar el estado del script desde su equipo de trabajo.

Parámetros

-AllowRedirection

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

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 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 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: http://localhost:5985/WSMAN. El nombre de la aplicación de una sesión se almacena en Runspace.ConectarPropiedad ionInfo.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
  • 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.

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 Get-Item comando o Get-ChildItem en la unidad de PowerShell Cert: .

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 que recibe 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, localhosto 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: http://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 más información sobre las configuraciones de sesión, vea 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:

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 puertos estándar: 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 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: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 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: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 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 Get-PSSession comando.

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

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

-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 especifica un valor de 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 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 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

PowerShell incluye los siguientes alias para Connect-PSSession:

  • Windows:

    • cnsn
  • Este cmdlet solo está disponible en plataformas Windows.

  • Connect-PSSession se vuelve a conectar solo 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 equipos que ejecutan Windows PowerShell 3.0 o versiones posteriores solo 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 PSSession esté desconectado 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 Enumeration.

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

  • No se puede cambiar el valor de tiempo de espera de inactividad de una PSSession cuando se conecta a 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 $PSSessionOption variable 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 New-PSSession cmdlets 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.