Compartilhar via

Connect-PSSession

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

Reconecta-se a sessões desconectadas.

Sintaxe

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

O cmdlet Connect-PSSession se reconecta às sessões gerenciadas pelo usuário do Windows 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.

Exemplos

Exemplo 1: reconectar a uma sessão

PS C:\> 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 é Aberto e o de Disponibilidade de está Disponível, o que indica que você pode executar comandos na sessão.

Exemplo 2: efeito de desconectar e reconectar

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

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 é Aberto e o de Disponibilidade do está Disponível.

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

O terceiro comando usa o cmdlet Get-PSSession para obter o objetos de PSSession que foram 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 é Aberto e o de Disponibilidade do está Disponível.

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.

Exemplo 3: série de comandos em um cenário 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 série de comandos mostra como o cmdlet Connect-PSSession pode ser usado em um cenário corporativo. 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.

Parâmetros

-AllowRedirection

Indica que esse cmdlet permite o redirecionamento dessa conexão para um URI alternativo.

Quando você usa o parâmetro ConnectionURI, o destino remoto pode retornar uma instrução para redirecionar para um URI diferente. Por padrão, o Windows PowerShell não redireciona conexões, mas você pode usar esse parâmetro para permitir que ele redirecione a conexão.

Você também pode limitar o número de vezes que a conexão é redirecionada alterando o valor da opção MaximumConnectionRedirectionCount sessão. Use o parâmetro MaximumRedirection do cmdlet New-PSSessionOption ou defina a propriedade MaximumConnectionRedirectionCount da variável de preferência $PSSessionOption. O valor padrão é 5.

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

-ApplicationName

Especifica o nome de um aplicativo. Esse cmdlet se conecta apenas às sessões que usam o aplicativo especificado.

Insira o segmento de nome do aplicativo do URI de conexão. Por exemplo, no seguinte URI de conexão, o nome do aplicativo é WSMan: https://localhost:5985/WSMAN. O nome do aplicativo de uma sessão é armazenado na propriedade Runspace.ConnectionInfo.AppName da sessão.

O valor desse parâmetro é usado para selecionar e filtrar sessões. Ele não altera o aplicativo que a sessão usa.

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

-Authentication

Especifica o mecanismo usado para autenticar as credenciais do usuário no comando para se reconectar à sessão desconectada. Os valores aceitáveis para este parâmetro são:

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

O valor padrão é Default.

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

Cuidado: a autenticação credSSP (Provedor de Suporte à Segurança de Credencial), na qual as credenciais do usuário são passadas para um computador remoto a ser autenticado, foi projetada para comandos que exigem autenticação em mais de um recurso, como acessar um compartilhamento de rede remoto. Esse mecanismo aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, as credenciais passadas para ele poderão ser usadas para controlar a sessão de rede.

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

-CertificateThumbprint

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

Os certificados são usados na autenticação baseada em certificado do cliente. Eles podem ser mapeados apenas para contas de usuário locais. Eles não funcionam com contas de domínio.

Para obter uma impressão digital do certificado, use um comando Get-Item ou Get-ChildItem no Certificado do Windows PowerShell: unidade.

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

-ComputerName

Especifica os computadores nos quais as sessões desconectadas são armazenadas. As sessões são armazenadas no computador que está no lado do servidor ou no final de uma conexão. O padrão é o computador local.

Digite o nome NetBIOS, um endereço IP ou um nome de domínio totalmente qualificado de um computador. Caracteres curinga não são permitidos. Para especificar o computador local, digite o nome do computador, localhost ou um ponto (.)

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

-ConfigurationName

Conecta-se somente a sessões que usam a configuração de sessão especificada.

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

O valor desse parâmetro é usado para selecionar e filtrar sessões. Ele não altera a configuração de sessão usada pela sessão.

Para obter mais informações sobre configurações de sessão, consulte about_Session_Configurations.

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

-Confirm

Solicita a confirmação antes de executar o cmdlet.

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

-ConnectionUri

Especifica os URIs dos pontos de extremidade de conexão para as sessões desconectadas.

O URI deve ser totalmente qualificado. O formato dessa cadeia de caracteres é o seguinte:

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

O valor padrão é o seguinte:

https://localhost:5985/WSMAN

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

Os valores válidos para o segmento Transport do URI são HTTP e HTTPS. Se você especificar um URI de conexão com um segmento de Transporte, mas não especificar uma porta, a sessão será criada com portas padrões: 80 para HTTP e 443 para HTTPS. Para usar as portas padrão para comunicação remota do Windows PowerShell, especifique a porta 5985 para HTTP ou 5986 para HTTPS.

Se o computador de destino redirecionar a conexão para um URI diferente, o Windows PowerShell impedirá o redirecionamento, a menos que você use o parâmetro AllowRedirection no comando.

Tipo:Uri[]
Aliases:URI, CU
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-Credential

Especifica uma conta de usuário que tem permissão para se conectar à sessão desconectada. O padrão é o usuário atual.

Digite um nome de usuário, como User01 ou Domain01\User01. Ou insira um objeto PSCredential , como um gerado pelo cmdlet Get-Credential. Se você digitar um nome de usuário, esse cmdlet solicitará uma senha.

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

-Id

Especifica as IDs das sessões desconectadas. A ID parâmetro funciona somente quando a sessão desconectada foi conectada anteriormente à sessão atual.

Esse parâmetro é válido, mas não eficaz, quando a sessão é armazenada no computador local, mas não foi conectada à sessão atual.

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

-InstanceId

Especifica as IDs de instância das sessões desconectadas.

A ID da instância é um GUID que identifica exclusivamente um de PSSession em um computador local ou remoto.

A ID da instância é armazenada na propriedade InstanceID do PSSession.

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

-Name

Especifica os nomes amigáveis das sessões desconectadas.

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

-Port

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

Antes de usar uma porta alternativa, você deve configurar o ouvinte do WinRM no computador remoto para escutar nessa porta. Para configurar o ouvinte, digite os dois comandos a seguir no prompt do Windows PowerShell:

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

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

Não use o parâmetro Port, a menos que seja necessário. A porta definida no comando se aplica a todos os computadores ou sessões nas quais o comando é executado. Uma configuração de porta alternativa pode impedir que o comando seja executado em todos os computadores.

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

-Session

Especifica as sessões desconectadas. Insira uma variável que contém os objetos PSSession ou um comando que cria ou obtém os objetos PSSession, como um comando Get-PSSession.

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

-SessionOption

Especifica opções avançadas para a sessão. Insira um objeto SessionOption, como um que você cria usando o cmdlet New-PSSessionOption ou uma tabela de hash na qual as chaves são nomes de opção de sessão e os valores são valores de opção de sessão.

Os valores padrão para as opções são determinados pelo valor da variável de preferência $PSSessionOption, se ela estiver definida. Caso contrário, os valores padrão são estabelecidos por opções definidas na configuração da sessão.

Os valores de opção de sessão têm precedência sobre valores padrão para sessões definidas na variável de preferência $PSSessionOption e na configuração da sessão. No entanto, eles não têm precedência sobre valores máximos, cotas ou limites definidos na configuração da sessão.

Para obter uma descrição das opções de sessão que incluem os valores padrão, consulte New-PSSessionOption. Para obter informações sobre a variável de preferência $PSSessionOption, consulte about_Preference_Variables. Para obter mais informações sobre configurações de sessão, consulte about_Session_Configurations.

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

-ThrottleLimit

Especifica o número máximo de conexões simultâneas que podem ser estabelecidas para executar esse comando. Se você omitir esse parâmetro ou inserir um valor de 0, o valor padrão, 32, será usado.

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

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

-UseSSL

Indica que esse cmdlet usa o protocolo SSL (Secure Sockets Layer) para se conectar à sessão desconectada. Por padrão, o SSL não é usado.

WS-Management criptografa todo o conteúdo do Windows PowerShell transmitido pela rede. O parâmetro UseSSL é uma proteção adicional que envia os dados em uma conexão HTTPS em vez de uma conexão HTTP.

Se você usar esse parâmetro, mas o SSL não estiver disponível na porta usada para o comando, o comando falhará.

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

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

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

Entradas

PSSession

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

Saídas

PSSession

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

Observações

  • 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. Ele pode estar conectado a uma sessão diferente. Para determinar se você pode se conectar ou se reconectar à sessão, use a propriedade de Disponibilidade .

    Um valor de disponibilidade de de Nenhum 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 na biblioteca MSDN.

    Para obter mais informações sobre os valores da propriedade de disponibilidade de de sessões, consulte de Enumeração RunspaceAvailability na biblioteca MSDN.

  • 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 idleTimeout valor da variável $PSSessionOption são ignorados ao se conectar a umde PSSession .

    Você pode definir e alterar o tempo limite ocioso de uma de PSSession ao criar oPSSession usando os cmdlets new-PSSession ou Invoke-Command e quando você se desconectar do 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.