Connect-PSSession

Connect-PSSession
    -Name <String[]>
    [-ThrottleLimit <Int32>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Connect-PSSession
    [-Session] <PSSession[]>
    [-ThrottleLimit <Int32>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Connect-PSSession
    -ComputerName <String[]>
    -InstanceId <Guid[]>
    [-ApplicationName <String>]
    [-ConfigurationName <String>]
    [-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
    [-ConnectionUri] <Uri[]>
    -InstanceId <Guid[]>
    [-ConfigurationName <String>]
    [-AllowRedirection]
    [-Credential <PSCredential>]
    [-Authentication <AuthenticationMechanism>]
    [-CertificateThumbprint <String>]
    [-SessionOption <PSSessionOption>]
    [-ThrottleLimit <Int32>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Connect-PSSession
    [-ConnectionUri] <Uri[]>
    [-ConfigurationName <String>]
    [-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
    [-Id] <Int32[]>
    [-ThrottleLimit <Int32>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Este cmdlet só está disponível na plataforma Windows.

O cmdlet Connect-PSSession se reconecta às sessões gerenciadas pelo usuário do PowerShell (PSSessions) que foram desconectadas. Ele funciona em sessões desconectadas intencionalmente, como usando o cmdlet Disconnect-PSSession ou o parâmetro InDisconnectedSession do cmdlet Invoke-Command e aqueles que foram desconectados involuntariamente, como por uma interrupção temporária da rede.

Connect-PSSession pode se conectar a qualquer sessão desconectada iniciada pelo mesmo usuário. Isso inclui aqueles que foram iniciados ou desconectados de outras sessões em outros computadores.

No entanto, Connect-PSSession não pode se conectar a sessões interrompidas ou fechadas ou sessões interativas iniciadas usando o cmdlet Enter-PSSession. Além disso, você não pode conectar sessões a sessões iniciadas por outros usuários, a menos que você possa fornecer as credenciais do usuário que criou a sessão.

Para obter mais informações sobre o recurso Sessões Desconectadas, consulte about_Remote_Disconnected_Sessions.

Esse cmdlet foi introduzido no Windows PowerShell 3.0.

Connect-PSSession -ComputerName Server01 -Name ITTask

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

Esse comando se reconecta à sessão ITTask no computador Server01.

A saída mostra que o comando foi bem-sucedido. O de Estado da sessão é Opened e o de Disponibilidade é Available, o que indica que você pode executar comandos na sessão.

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

Este exemplo mostra o efeito de desconectar e reconectar-se a uma sessão.

O primeiro comando usa o cmdlet Get-PSSession. Sem o parâmetro ComputerName, o comando obtém apenas as sessões que foram criadas na sessão atual.

A saída mostra que o comando obtém a sessão Backups no computador local. O de Estado da sessão é Opened e o de Disponibilidade é Available.

O segundo comando usa o cmdlet Get-PSSession para obter o objetos PSSession criados na sessão atual e o cmdlet Disconnect-PSSession para desconectar as sessões. A saída mostra que a sessão de Backups foi desconectada. O de Estado da sessão é Disconnected e o de Disponibilidade é None.

O terceiro comando usa o cmdlet Get-PSSession para obter os objetos PSSession criados na sessão atual e o cmdlet Connect-PSSession para reconectar as sessões. A saída mostra que a sessão Backups foi reconectada. O de Estado da sessão é Opened e o de Disponibilidade é Available.

Se você usar o cmdlet Connect-PSSession em uma sessão que não está desconectada, o comando não afetará a sessão e não gerará erros.

Esta série de comandos mostra como o cmdlet Connect-PSSession pode ser usado em um cenário empresarial. Nesse caso, um administrador do sistema inicia um trabalho de execução prolongada em uma sessão em um computador remoto. Depois de iniciar o trabalho, o administrador se desconecta da sessão e vai para casa. Mais tarde naquela noite, o administrador faz logon em seu computador doméstico e verifica se o trabalho foi executado até que ele seja concluído.

O administrador começa criando uma sessão em um computador remoto e executando um script na sessão. O primeiro comando usa o cmdlet New-PSSession para criar a sessão ITTask no computador remoto Server01. O comando usa o parâmetro ConfigurationName para especificar a configuração da sessão ITTasks. O comando salva as sessões na variável $s.

O segundo comando Invoke-Command cmdlet para iniciar um trabalho em segundo plano na sessão na variável $s. Ele usa o parâmetro FilePath para executar o script no trabalho em segundo plano.

O terceiro comando usa o cmdlet Disconnect-PSSession para se desconectar da sessão na variável $s. O comando usa o parâmetro OutputBufferingMode com um valor de Drop para impedir que o script seja bloqueado por ter que entregar a saída para a sessão. Ele usa o parâmetro IdleTimeoutSec para estender o tempo limite da sessão para 15 horas. Quando o comando é concluído, o administrador bloqueia seu computador e vai para casa durante a noite.

Mais tarde naquela noite, o administrador inicia seu computador doméstico, faz logon na rede corporativa e inicia o PowerShell. O quarto comando usa o cmdlet Get-PSSession para obter as sessões no computador Server01. O comando localiza a sessão ITTask. O quinto comando usa o cmdlet Connect-PSSession para se conectar à sessão de ITTask. O comando salva a sessão na variável $s.

O sexto comando usa o cmdlet Invoke-Command para executar um comando Get-Job na sessão na variável $s. A saída mostra que o trabalho foi concluído com êxito. O sétimo comando usa o cmdlet Invoke-Command para executar um comando Receive-Job na sessão na variável $s na sessão. O comando salva os resultados na variável $BackupSpecs. O oitavo comando usa o cmdlet Invoke-Command para executar outro script na sessão. O comando usa o valor da variável $BackupSpecs na sessão como entrada para o 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

O nono comando se desconecta da sessão na variável $s. O administrador fecha o PowerShell e fecha o computador. Ela pode se reconectar à sessão no dia seguinte e verificar o status do script em seu computador de trabalho.

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.

Você pode redirecionar uma sessão (PSSession) para este cmdlet.

Esse cmdlet retorna um objeto que representa a sessão à qual ele se reconectou.

O PowerShell inclui os seguintes aliases para Connect-PSSession:

• Windows:

  • cnsn

• Este cmdlet está disponível apenas em plataformas Windows.

• Connect-PSSession se reconecta apenas às sessões desconectadas, ou seja, sessões que têm um valor desconectado para a propriedade state. Somente as sessões que estão conectadas ou terminam em computadores que executam o Windows PowerShell 3.0 ou versões posteriores podem ser desconectadas e reconectadas.

• Se você usar Connect-PSSession em uma sessão que não está desconectada, o comando não afetará a sessão e não gerará erros.

• Sessões de loopback desconectadas com tokens interativos, que são criados usando o parâmetro EnableNetworkAccess , só podem ser reconectadas do computador no qual a sessão foi criada. Essa restrição protege o computador contra acesso mal-intencionado.

• O valor da propriedade State de uma PSSession é relativo à sessão atual. Portanto, um valor de Desconectado significa que o PSSession não está conectado à sessão atual. No entanto, isso não significa que o de PSSession esteja desconectado de todas as sessões. Ela pode ser conectada a uma sessão diferente. Para determinar se você pode se conectar ou se reconectar à sessão, use a propriedade Disponibilidade.

  Um valor Disponibilidade de Nenhuma indica que você pode se conectar à sessão. Um valor de Ocupado indica que você não pode se conectar ao PSSession porque ele está conectado a outra sessão.

  Para obter mais informações sobre os valores da propriedade State de sessões, consulte de Enumeração RunspaceState.

  Para obter mais informações sobre os valores da propriedade Availability de sessões, consulte RunspaceAvailability Enumeration.

• Não é possível alterar o valor de tempo limite ocioso de uma de PSSession ao se conectar aoPSSession . O parâmetro SessionOption de Connect-PSSession usa um objeto SessionOption que tem um valor IdleTimeout. No entanto, o IdleTimeout valor do objeto SessionOption e o valor IdleTimeout da variável $PSSessionOption são ignorados ao se conectar a um PSSession.

  Você pode definir e alterar o tempo limite ocioso de uma PSSession ao criar a PSSession usando os cmdlets New-PSSession ou Invoke-Command, e quando você se desconectar da PSSession.

  A propriedade IdleTimeout de um PSSession é essencial para sessões desconectadas, pois determina por quanto tempo uma sessão desconectada é mantida no computador remoto. As sessões desconectadas são consideradas ociosas a partir do momento em que estão desconectadas, mesmo que os comandos estejam em execução na sessão desconectada.