Connect-PSSession
Reconecta-se a sessões 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
Esse cmdlet só está disponível na plataforma Windows.
O Connect-PSSession cmdlet se reconecta às sessões do PowerShell gerenciadas pelo usuário (PSSessions) que foram desconectadas. Ele funciona em sessões desconectadas intencionalmente, como usando o Disconnect-PSSession cmdlet ou o parâmetro InDisconnectedSession do Invoke-Command cmdlet e aquelas que foram desconectadas 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 é possível se conectar a sessões interrompidas ou fechadas ou sessões interativas iniciadas usando o Enter-PSSession cmdlet . Além disso, não é possível 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 de Sessões desconectadas, consulte about_Remote_Disconnected_Sessions.
Este cmdlet foi introduzido no Windows PowerShell 3.0.
Exemplos
Exemplo 1: Reconectar-se a uma sessão
Connect-PSSession -ComputerName Server01 -Name ITTask
Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
4 ITTask Server01 Opened ITTasks AvailableEsse comando se reconecta à ITTask sessão no computador Server01.
A saída mostra que o comando teve êxito. O Estado da sessão é Opened e a Disponibilidade é Available, o que indica que você pode executar comandos na sessão.
Exemplo 2: efeito de desconexão e reconexã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 AvailableEste exemplo mostra o efeito de se desconectar e, em seguida, reconectar a uma sessão.
O primeiro comando usa o Get-PSSession cmdlet . 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 Backups sessão no computador local. O Estado da sessão é Opened e a Disponibilidade é Available.
O segundo comando usa o Get-PSSession cmdlet para obter os objetos PSSession que foram criados na sessão atual e o Disconnect-PSSession cmdlet para desconectar as sessões. A saída mostra que a Backups sessão foi desconectada. O Estado da sessão é Disconnected e a Disponibilidade é None.
O terceiro comando usa o Get-PSSession cmdlet para obter os objetos PSSession que foram criados na sessão atual e o Connect-PSSession cmdlet para reconectar as sessões. A saída mostra que a Backups sessão foi reconectada. O Estado da sessão é Opened e a Disponibilidade é Available.
Se você usar o Connect-PSSession cmdlet 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
Esta série de comandos mostra como o Connect-PSSession cmdlet pode ser usado em um cenário empresarial. Nesse caso, uma administradora do sistema inicia um trabalho de longa execução em uma sessão em um computador remoto. Após iniciar o trabalho, a administradora 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é ser concluído.
O administrador começa criando sessões em um computador remoto e executando um script na sessão. O primeiro comando usa o New-PSSession cmdlet para criar a ITTask sessão no computador remoto Server01. O comando usa o parâmetro ConfigurationName para especificar a configuração da ITTasks sessão. O comando salva as sessões na $s variável.
O segundo cmdlet de comando Invoke-Command para iniciar um trabalho em segundo plano na sessão na $s variável. Ele usa o parâmetro FilePath para executar o script no trabalho em segundo plano.
O terceiro comando usa o Disconnect-PSSession cmdlet para se desconectar da sessão na $s variável. 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 inicial, faz logon na rede corporativa e inicia o PowerShell. O quarto comando usa o Get-PSSession cmdlet para obter as sessões no computador Server01. O comando localiza a ITTask sessão. O quinto comando usa o Connect-PSSession cmdlet para se conectar à ITTask sessão. O comando salva a sessão na variável $s.
O sexto comando usa o Invoke-Command cmdlet para executar um Get-Job comando na sessão na $s variável . A saída mostra que o trabalho foi concluído com êxito. O sétimo comando usa o Invoke-Command cmdlet para executar um Receive-Job comando na sessão na $s variável na sessão. O comando salva os resultados na $BackupSpecs variável. O oitavo comando usa o Invoke-Command cmdlet para executar outro script na sessão. O comando usa o valor da $BackupSpecs variável 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 NoneO nono comando se desconecta da sessão na $s variável . O administrador fecha o PowerShell e fecha o computador. Ela pode se reconectar à sessão no dia seguinte e verificar o status do script do seu computador de trabalho.
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 PowerShell não redireciona conexões, mas você pode usar esse parâmetro para permitir que ele redirecione a conexão.
É possível também limitar o número de vezes que a conexão é redirecionada alterando o valor da opção de sessão MaximumConnectionRedirectionCount. Use o parâmetro MaximumRedirection do New-PSSessionOption cmdlet ou defina a propriedade MaximumConnectionRedirectionCount da variável de preferência $PSSessionOption . O valor padrão é 5.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ApplicationName
Especifica o nome de um aplicativo. Esse cmdlet se conecta apenas a sessões que usam o aplicativo especificado.
Insira o segmento de nome de aplicativo do URI de conexão. Por exemplo, no seguinte URI de conexão, o nome do aplicativo é WSMan: http://localhost:5985/WSMAN. O nome de 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 utilizado pela sessão.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | 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 esse parâmetro são:
DefaultBasicCredsspDigestKerberosNegotiateNegotiateWithImplicitCredential
O valor padrão é Default.
Para obter mais informações sobre os valores desse parâmetro, confira Enumeração AuthenticationMechanism.
Cuidado
A autenticação CredSSP (Credencial Security Support Provider), na qual as credenciais do usuário são passadas a um computador remoto para autenticação, foi projetada para comandos que exijam autenticação em mais de um recurso, como acessar um compartilhamento de rede remota. Esse mecanismo aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, as credenciais que são passadas a ele podem ser usadas para controlar a sessão de rede.
| 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 o certificado de chave pública digital (X509) de uma conta de usuário com permissão para se conectar à sessão desconectada. Insira a impressão digital do certificado.
Os certificados são utilizados na autenticação baseada em certificado do cliente. Eles só podem ser mapeados 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 Get-Item comando ou Get-ChildItem na unidade do PowerShell Cert: .
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ComputerName
Especifica os computadores nos quais as sessões desconectadas estão armazenadas. As sessões são armazenadas no computador que está no lado do servidor ou recebendo o fim 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, localhostou um ponto (.)
| Type: | String[] |
| Aliases: | Cn |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | 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 do 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á anexado: http://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 utilizada pela sessão.
Para obter mais informações sobre configurações de sessão, consulte about_Session_Configurations.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Confirm
Solicita sua confirmação antes de executar o cmdlet.
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | 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:
http://localhost:5985/WSMAN
Se você não especificar um URI de conexão, poderá usar os parâmetros UseSSL e Port 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 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 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 PowerShell impedirá o redirecionamento, a menos que você use o parâmetro AllowRedirection no comando .
| Type: | Uri[] |
| Aliases: | URI, CU |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | 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 gerado pelo Get-Credential cmdlet . Se você digitar um nome de usuário, será solicitado que você insira a senha.
As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.
Observação
Para obter mais informações sobre a proteção de dados SecureString , consulte Quão seguro é SecureString?.
| Type: | PSCredential |
| Position: | Named |
| Default value: | Current user |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Id
Especifica as IDs das sessões desconectadas. O parâmetro Id funciona somente quando a sessão desconectada foi conectada anteriormente à sessão atual.
Este parâmetro é válido, mas não é eficaz, quando a sessão está armazenada no computador local, mas não estava conectada à sessão atual.
| Type: | Int32[] |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-InstanceId
Especifica as IDs de instância das sessões desconectadas.
A ID da instância é um GUID que identifica exclusivamente uma PSSession em um computador local ou remoto.
A ID da instância é armazenada na propriedade InstanceID do PSSession.
| Type: | Guid[] |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Name
Especifica os nomes amigáveis das sessões desconectadas.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Port
Especifica a porta de rede no computador remoto que é usada para se reconectar à sessão. Para se conectar a um computador remoto, este deve estar escutando na porta usada pela conexão. 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 de WinRM no computador remoto para escutar na porta. Para configurar o ouvinte, digite os dois comandos a seguir no prompt do 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 que está definida no comando se aplica a todos os computadores ou sessões em que o comando é executado. Uma configuração de porta alternativa pode impedir que o comando seja executado em todos os computadores.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Session
Especifica as sessões desconectadas. Insira uma variável que contenha os objetos PSSession ou um comando que cria ou obtém os objetos PSSession , como um Get-PSSession comando.
| Type: | PSSession[] |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-SessionOption
Especifica opções avançadas para a sessão. Insira um objeto SessionOption , como um que você cria usando o New-PSSessionOption cmdlet 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 $PSSessionOption preferência, 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 $PSSessionOption variável de preferência 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.
| Type: | PSSessionOption |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ThrottleLimit
Especifica o número máximo de conexões simultâneas que podem ser estabelecidas para executar o comando.
Se você omitir esse parâmetro ou inserir um valor de 0, o valor padrão, 32, será usado.
O limite de aceleração aplica-se somente ao comando atual e não à sessão ou ao computador.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseSSL
Indica que esse cmdlet usa o protocolo SSL (Secure Sockets Layer) para se conectar à sessão desconectada. Por padrão, SSL não é usado.
WS-Management criptografa todo o conteúdo do 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á.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-WhatIf
Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Entradas
Você pode canalizar uma sessão (PSSession) para este cmdlet.
Saídas
Esse cmdlet retorna um objeto que representa a sessão à qual ele se reconectou.
Observações
O PowerShell inclui os seguintes aliases para Connect-PSSession:
Windows:
cnsn
Esse cmdlet só está disponível em plataformas Windows.
Connect-PSSessionreconecta-se somente a sessões desconectadas, ou seja, sessões que têm um valor desconectado para a propriedade State . Somente as sessões conectadas ou terminam em computadores que executam Windows PowerShell 3.0 ou versões posteriores podem ser desconectadas e reconectadas.Se você usar
Connect-PSSessionem 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 acessos mal-intencionados.
O valor da propriedade State de uma PSSession é relativo à sessão atual. Portanto, um valor desconectado significa que a PSSession não está conectada à sessão atual. No entanto, isso não significa que a PSSession esteja desconectada de todas as sessões. Ela pode ser conectada a uma sessão diferente. Para determinar se é possível conectar-se ou reconectar-se à sessão, utilize a propriedade Availability.
Um valor Availability de None indica que é possível conectar-se à sessão. Um valor de Ocupado indica que você não pode se conectar à PSSession porque ela está conectada a outra sessão.
Para obter mais informações sobre os valores da propriedade State das sessões, consulte Enumeração RunspaceState.
Para obter mais informações sobre os valores da propriedade Disponibilidade das sessões, consulte Enumeração RunspaceAvailability.
Não é possível alterar o valor de tempo limite ocioso de uma PSSession quando você se conecta à PSSession. O parâmetro SessionOption de
Connect-PSSessionusa um objeto SessionOption que tem um valor IdleTimeout . No entanto, o valor IdleTimeout do objeto SessionOption e o valor IdleTimeout da$PSSessionOptionvariável são ignorados ao se conectar a uma PSSession.Você pode definir e alterar o tempo limite ocioso de uma PSSession ao criar a PSSession, usando os
New-PSSessioncmdlets ouInvoke-Commande quando você se desconectar do PSSession.A propriedade IdleTimeout de uma PSSession é essencial para sessões desconectadas, pois determina por quanto tempo uma sessão desconectada é mantida no computador remoto. Sessões desconectadas são consideradas ociosas desde o momento em que são desconectadas, ainda que comandos estejam em execução na sessão desconectada.