Disconnect-PSSession

Referência

Módulo:: Microsoft.PowerShell.Core

Desconecta-se de uma sessão.

Syntax

Disconnect-PSSession
          [-Session] <PSSession[]>
          [-IdleTimeoutSec <Int32>]
          [-OutputBufferingMode <OutputBufferingMode>]
          [-ThrottleLimit <Int32>]
          [-WhatIf]
          [-Confirm]
          [<CommonParameters>]

Disconnect-PSSession
          [-IdleTimeoutSec <Int32>]
          [-OutputBufferingMode <OutputBufferingMode>]
          [-ThrottleLimit <Int32>]
          -Name <String[]>
          [-WhatIf]
          [-Confirm]
          [<CommonParameters>]

Disconnect-PSSession
          [-IdleTimeoutSec <Int32>]
          [-OutputBufferingMode <OutputBufferingMode>]
          [-ThrottleLimit <Int32>]
          -InstanceId <Guid[]>
          [-WhatIf]
          [-Confirm]
          [<CommonParameters>]

Disconnect-PSSession
          [-IdleTimeoutSec <Int32>]
          [-OutputBufferingMode <OutputBufferingMode>]
          [-ThrottleLimit <Int32>]
          [-Id] <Int32[]>
          [-WhatIf]
          [-Confirm]
          [<CommonParameters>]

Description

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

O Disconnect-PSSession cmdlet desconecta uma sessão do PowerShell (PSSession), como uma iniciada usando o New-PSSession cmdlet, da sessão atual. Como resultado, o PSSession está em um estado desconectado. Você pode se conectar à PSSession desconectada da sessão atual ou de outra sessão no computador local ou em um computador diferente.

O Disconnect-PSSession cmdlet desconecta apenas PSSessions abertas que estão conectadas à sessão atual. Disconnect-PSSessionnão pode desconectar PSSessions quebrados ou fechados ou PSSessions interativos iniciados usando o Enter-PSSession cmdlet e não pode desconectar PSSessions que estão conectados a outras sessões.

Para se reconectar a uma PSSession desconectada, use os Connect-PSSession cmdlets ouReceive-PSSession.

Quando um PSSession é desconectado, os comandos no PSSession continuam a ser executados até serem concluídos, a menos que o tempo limite do PSSession ou os comandos no PSSession sejam bloqueados por um buffer de saída completo. Para alterar o tempo limite de inatividade, use o parâmetro IdleTimeoutSec . Para alterar o modo de buffer de saída, use o parâmetro OutputBufferingMode Você também pode usar o parâmetro InDisconnectedSession do Invoke-Command cmdlet para executar um comando em uma sessão desconectada.

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

Este cmdlet é introduzido no Windows PowerShell 3.0.

Exemplos

Exemplo 1 - Desconectar uma sessão pelo nome

Este comando desconecta a UpdateSessionPSSession no computador Server01 da sessão atual. O comando usa o parâmetro Name para identificar o PSSession.

PS> Disconnect-PSSession -Name UpdateSession
Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
1  UpdateSession   Server01        Disconnected  Microsoft.PowerShell          None

A saída mostra que a tentativa de desconexão foi bem-sucedida. O estado da sessão é Disconnected e a Disponibilidade é None, o que indica que a sessão não está ocupada e pode ser reconectada.

Exemplo 2 - Desconectar uma sessão de um computador específico

Este comando desconecta o ITTaskPSSession no computador Server12 da sessão atual. A ITTask sessão foi criada na sessão atual e se conecta ao computador Server12. O comando usa o Get-PSSession cmdlet para obter a sessão e o Disconnect-PSSession cmdlet para desconectá-la.

PS> Get-PSSession -ComputerName Server12 -Name ITTask |
  Disconnect-PSSession -OutputBufferingMode Drop -IdleTimeoutSec 86400
Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
1  ITTask          Server12        Disconnected  ITTasks               None

O Disconnect-PSSession comando usa o parâmetro OutputBufferingMode para definir o modo de saída como Drop. Essa configuração garante que o script em execução na sessão possa continuar a ser executado mesmo se o buffer de saída da sessão estiver cheio. Como o script grava sua saída em um relatório em um compartilhamento de arquivos, outra saída pode ser perdida sem consequências.

O comando também usa o parâmetro IdleTimeoutSec para estender o tempo limite ocioso da sessão para 24 horas. Essa configuração dá tempo para que esse administrador ou outros administradores se reconectem à sessão para verificar se o script foi executado e solucionar problemas, se necessário.

Exemplo 3 - Usando várias PSSessions em vários computadores

Esta série de comandos mostra como o Disconnect-PSSession cmdlet pode ser usado em um cenário empresarial. Nesse caso, um novo técnico inicia um script em uma sessão em um computador remoto e se depara com um problema. O técnico se desconecta da sessão para que um gerente mais experiente possa se conectar à sessão e resolver o problema.

PS> $s = New-PSSession -ComputerName Srv1, Srv2, Srv30 -Name ITTask
PS> Invoke-Command $s -FilePath \\Server01\Scripts\Get-PatchStatus.ps1
PS> Get-PSSession -Name ITTask -ComputerName Srv1 | Disconnect-PSSession
Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
1 ITTask           Srv1            Disconnected  Microsoft.PowerShell          None

PS> Get-PSSession -ComputerName Srv1, Srv2, Srv30 -Name ITTask
Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 ITTask          Srv1            Disconnected  Microsoft.PowerShell          None
 2 ITTask          Srv2            Opened        Microsoft.PowerShell     Available
 3 ITTask          Srv30           Opened        Microsoft.PowerShell     Available

PS> Get-PSSession -ComputerName Srv1 -Name ITTask -Credential Domain01\User01
Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 1 ITTask          Srv1            Disconnected  Microsoft.PowerShell          None

PS> $s = Connect-PSSession -ComputerName Srv1 -Name ITTask -Credential Domain01\User01
PS> Invoke-Command -Session $s {dir $HOME\Scripts\PatchStatusOutput.ps1}
PS> Invoke-Command -Session $s {mkdir $HOME\Scripts\PatchStatusOutput}
PS> Invoke-Command -Session $s -FilePath \\Server01\Scripts\Get-PatchStatus.ps1
PS> Disconnect-PSSession -Session $s

O técnico começa criando sessões em vários computadores remotos e executando um script em cada sessão. O primeiro comando usa o New-PSSession cmdlet para criar a ITTask sessão em três computadores remotos. O comando salva as sessões na $s variável. O segundo comando usa o parâmetro FilePath do Invoke-Command cmdlet para executar um script nas sessões da $s variável.

O script em execução no computador Srv1 gera erros inesperados. O técnico entra em contato com seu gerente e pede ajuda. O gerente orienta o técnico a se desligar da sessão para que ele possa investigar. O segundo comando usa o Get-PSSession cmdlet para obter a ITTask sessão no computador Srv1 e o Disconnect-PSSession cmdlet para desconectá-la. Este comando não afeta as ITTask sessões nos outros computadores.

O terceiro comando usa o Get-PSSession cmdlet para obter as ITTask sessões. A saída mostra que as ITTask sessões nos computadores Srv2 e Srv30 não foram afetadas pelo comando para desconectar.

O gerente faz logon em seu computador doméstico, se conecta à rede corporativa, inicia o PowerShell e usa o Get-PSSession cmdlet para obter a ITTask sessão no computador Srv1. Ele usa as credenciais do técnico para acessar a sessão.

Em seguida, o gerente usa o Connect-PSSession cmdlet para se conectar à ITTask sessão no computador Srv1. O comando salva a sessão na $s variável.

O gerente usa o Invoke-Command cmdlet para executar alguns comandos de diagnóstico na sessão na $s variável. Ele reconhece que o script falhou porque não encontrou um diretório necessário. O gerente usa a MkDir função para criar o diretório e, em seguida, ele reinicia o Get-PatchStatus.ps1 script e se desconecta da sessão. O gerente relata suas descobertas ao técnico, sugere que ele se reconecte à sessão para concluir as tarefas e pede que ele adicione um comando ao Get-PatchStatus.ps1 script que cria o diretório necessário, se ele não existir.

Exemplo 4 - Alterar o valor de tempo limite para uma PSSession

Este exemplo mostra como corrigir o valor da propriedade IdleTimeout de uma sessão para que ela possa ser desconectada.

A propriedade de tempo limite ocioso de uma sessão é fundamental para sessões desconectadas, pois determina por quanto tempo uma sessão desconectada é mantida antes de ser excluída. Você pode definir a opção de tempo limite ocioso ao criar uma sessão e ao desconectá-la. Os valores padrão para o tempo limite ocioso de uma sessão são definidos na $PSSessionOption variável de preferência no computador local e na configuração da sessão no computador remoto. Os valores definidos para a sessão têm precedência sobre os valores definidos na configuração da sessão, mas os valores da sessão não podem exceder as cotas definidas na configuração da sessão, como o valor MaxIdleTimeoutMs .

PS> $Timeout = New-PSSessionOption -IdleTimeout 172800000
PS> $s = New-PSSession -Computer Server01 -Name ITTask -SessionOption $Timeout
PS> Disconnect-PSSession -Session $s
Disconnect-PSSession : The session ITTask cannot be disconnected because the specified
idle timeout value 172800(seconds) is either greater than the server maximum allowed
43200 (seconds) or less that the minimum allowed60(seconds).  Choose an idle time out
value that is within the allowed range and try again.

PS> Invoke-Command -ComputerName Server01 {Get-PSSessionConfiguration Microsoft.PowerShell} |
 Format-List -Property *

Architecture                  : 64
Filename                      : %windir%\system32\pwrshplugin.dll
ResourceUri                   : http://schemas.microsoft.com/powershell/microsoft.powershell
MaxConcurrentCommandsPerShell : 1000
UseSharedProcess              : false
ProcessIdleTimeoutSec         : 0
xmlns                         : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration
MaxConcurrentUsers            : 5
lang                          : en-US
SupportsOptions               : true
ExactMatch                    : true
RunAsUser                     :
IdleTimeoutms                 : 7200000
PSVersion                     : 3.0
OutputBufferingMode           : Block
AutoRestart                   : false
SecurityDescriptorSddl        : O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;SA;GXGW;;;WD)
MaxMemoryPerShellMB           : 1024
MaxIdleTimeoutms              : 2147483647
Uri                           : http://schemas.microsoft.com/powershell/microsoft.powershell
SDKVersion                    : 2
Name                          : microsoft.powershell
XmlRenderingType              : text
Capability                    : {Shell}
RunAsPassword                 :
MaxProcessesPerShell          : 15
ParentResourceUri             : http://schemas.microsoft.com/powershell/microsoft.powershell
Enabled                       : true
MaxShells                     : 25
MaxShellsPerUser              : 25
Permission                    : BUILTIN\Administrators AccessAllowed
PSComputerName                : localhost
RunspaceId                    : aea84310-6dbf-4c21-90ac-13980039925a
PSShowComputerName            : True


PS> $s.Runspace.ConnectionInfo
ConnectionUri                     : http://Server01/wsman
ComputerName                      : Server01
Scheme                            : http
Port                              : 80
AppName                           : /wsman
Credential                        :
ShellUri                          : http://schemas.microsoft.com/powershell/Microsoft.PowerShell
AuthenticationMechanism           : Default
CertificateThumbprint             :
MaximumConnectionRedirectionCount : 5
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         : 209715200
UseCompression                    : True
NoMachineProfile                  : False
ProxyAccessType                   : None
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
NoEncryption                      : False
UseUTF16                          : False
OutputBufferingMode               : Drop
IncludePortInSPN                  : False
Culture                           : en-US
UICulture                         : en-US
OpenTimeout                       : 180000
CancelTimeout                     : 60000
OperationTimeout                  : 180000
IdleTimeout                       : 172800000

PS> Disconnect-PSSession $s -IdleTimeoutSec 43200
Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 4 ITTask          Server01        Disconnected  Microsoft.PowerShell          None

PS> $s.Runspace.ConnectionInfo.IdleTimeout
43200000

O primeiro comando usa o New-PSSessionOption cmdlet para criar um objeto de opção de sessão. Ele usa o parâmetro IdleTimeout para definir um tempo limite ocioso de 48 horas (172800000milissegundos). O comando salva o objeto de opção de sessão na $Timeout variável.

O segundo comando usa o New-PSSession cmdlet para criar a ITTask sessão no computador Server01. O comando salvar a sessão na $s variável. O valor do parâmetro SessionOption é o tempo limite de inatividade de 48 horas na $Timeout variável.

O terceiro comando desconecta $s a ITTask sessão na variável. O comando falha porque o valor de tempo limite ocioso da sessão excede a cota MaxIdleTimeoutMs na configuração da sessão. Como o tempo limite ocioso não é usado até que a sessão seja desconectada, essa violação pode não ser detetada enquanto a sessão estiver em uso.

O quarto comando usa o Invoke-Command cmdlet para executar um Get-PSSessionConfiguration comando para a configuração da Microsoft.PowerShell sessão no computador Server01. O comando usa o Format-List cmdlet para exibir todas as propriedades da configuração da sessão em uma lista. A saída mostra que a propriedade MaxIdleTimeoutMS , que estabelece o valor máximo permitido de IdleTimeout para sessões que usam a configuração de sessão, é 43200000 de milissegundos (12 horas).

O quinto comando obtém os valores de opção de sessão da sessão na $s variável. Os valores de muitas opções de sessão são propriedades da propriedade ConnectionInfo da propriedade Runspace da sessão. A saída mostra que o valor da propriedade IdleTimeout da sessão é 172800000 milissegundos (48 horas), o que viola a cota MaxIdleTimeoutMs de 12 horas na configuração da sessão. Para resolver esse conflito, você pode usar o parâmetro ConfigurationName para selecionar uma configuração de sessão diferente ou usar o parâmetro IdleTimeout para reduzir o tempo limite ocioso da sessão.

O sexto comando desconecta a sessão. Ele usa o parâmetro IdleTimeoutSec para definir o tempo limite ocioso para o máximo de 12 horas.

O sétimo comando obtém o valor da propriedade IdleTimeout da sessão desconectada, que é medida em milissegundos. A saída confirma que o comando foi bem-sucedido.

Parâmetros

-Confirm

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

-Id

Desconecta-se das sessões com o ID de sessão especificado. Digite uma ou mais IDs (separadas por vírgulas) ou use o operador de intervalo (..) para especificar um intervalo de IDs.

Para obter a ID de uma sessão, use o Get-PSSession cmdlet. O ID da instância é armazenado na propriedade ID da sessão.

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

-IdleTimeoutSec

Altera o valor de tempo limite ocioso da PSSessão desconectada. Insira um valor em segundos. O valor mínimo é 60 (1 minuto).

O tempo limite ocioso determina por quanto tempo a PSSession desconectada é mantida no computador remoto. Quando o tempo limite expira, o PSSession é excluído.

PSSessions desconectados são considerados ociosos a partir do momento em que são desconectados, mesmo que os comandos estejam sendo executados na sessão desconectada.

O valor padrão para o tempo limite ocioso de uma sessão é definido pelo valor da propriedade IdleTimeoutMs da configuração da sessão. O valor padrão é 7200000 milissegundos (2 horas).

O valor desse parâmetro tem precedência sobre o valor da propriedade IdleTimeout da variável de $PSSessionOption preferência e o valor padrão de tempo limite ocioso na configuração da sessão. No entanto, esse valor não pode exceder o valor da propriedade MaxIdleTimeoutMs da configuração da sessão. O valor padrão de MaxIdleTimeoutMs é 12 horas (43200000 milissegundos).

Type:	Int32
Position:	Named
Default value:	60
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-InstanceId

Desconecta-se das sessões com os IDs de instância especificados.

O ID da instância é um GUID que identifica exclusivamente uma sessão em um computador local ou remoto. O ID da instância é exclusivo, mesmo em várias sessões em vários computadores.

Para obter a ID da instância de uma sessão, use o Get-PSSession cmdlet. O ID da instância é armazenado na propriedade InstanceID da sessão.

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

-Name

Desconecta-se das sessões com os nomes amigáveis especificados. Curingas são permitidos.

Para obter o nome amigável de uma sessão, use o Get-PSSession cmdlet. O nome amigável é armazenado na propriedade Name da sessão.

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

-OutputBufferingMode

Determina como a saída do comando é gerenciada na sessão desconectada quando o buffer de saída está cheio. O valor predefinido é Block.

Se o comando na sessão desconectada estiver retornando a saída e o buffer de saída for preenchido, o valor desse parâmetro determinará efetivamente se o comando continuará a ser executado enquanto a sessão estiver desconectada. Um valor de Block suspende o comando até que a sessão seja reconectada. Um valor de Drop permite que o comando seja concluído, embora os dados possam ser perdidos. Ao usar o Drop valor, redirecione a saída do comando para um arquivo no disco.

Os valores válidos são:

Block: Quando o buffer de saída está cheio, a execução é suspensa até que o buffer esteja limpo.
Drop: Quando o buffer de saída estiver cheio, a execução continuará. À medida que a nova saída é salva, a saída mais antiga é descartada.
None: Nenhum modo de buffer de saída é especificado. O valor da propriedade OutputBufferingMode da configuração da sessão é usado para a sessão desconectada.

Type:	OutputBufferingMode
Position:	Named
Default value:	Block
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Session

Desconecta-se das PSSessions especificadas. Insira objetos PSSession , como aqueles que o New-PSSession cmdlet retorna. Você também pode canalizar um objeto PSSession para Disconnect-PSSession.

O Get-PSSession cmdlet pode obter todas as PSSessions que terminam em um computador remoto, incluindo PSSessions que estão desconectadas e PSSessions que estão conectadas a outras sessões em outros computadores. Disconnect-PSSession desconecta apenas PSSession que estão conectados à sessão atual. Se você canalizar outras PSSessions para Disconnect-PSSession, o Disconnect-PSSession comando falhará.

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

-ThrottleLimit

Define o limite de aceleração para o Disconnect-PSSession comando.

O limite de aceleração é 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 aceleração aplica-se apenas ao comando atual, não à sessão ou ao computador.

Type:	Int32
Position:	Named
Default value:	32
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-WhatIf

Apresenta o que aconteceria mediante a execução do cmdlet. 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

PSSession

Você pode canalizar uma sessão para este cmdlet.

Saídas

PSSession

Esse cmdlet retorna um objeto que representa a sessão que ele desconectou.

Notas

O PowerShell inclui os seguintes aliases para Disconnect-PSSession:

Windows:
- dnsn

Este cmdlet só está disponível em plataformas Windows.

O Disconnect-PSSession cmdlet funciona somente quando os computadores locais e remotos estão executando o PowerShell 3.0 ou posterior.
Se você usar o Disconnect-PSSession cmdlet em uma sessão desconectada, o comando não terá efeito na sessão e não gerará erros.
As sessões de loopback desconectadas com tokens de segurança interativos (aqueles criados com o parâmetro EnableNetworkAccess ) podem ser reconectadas somente do computador no qual a sessão foi criada. Essa restrição protege o computador contra acesso mal-intencionado.
Quando você desconecta uma PSSession, o estado da sessão é Disconnected e a disponibilidade é Nenhuma.

O valor da propriedade State é relativo à sessão atual. Portanto, um valor de Disconnected significa que o PSSession não está conectado à sessão atual. No entanto, isso não significa que o 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 Availability .

Um valor de Disponibilidade indica None que você pode se conectar à sessão. Um valor de Busy 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 das sessões, consulte Enumeração RunspaceState.

Para obter mais informações sobre os valores da propriedade Availability das sessões, consulte Enumeração RunspaceAvailability.

Disconnect-PSSession

Syntax

Description

Exemplos

Exemplo 1 - Desconectar uma sessão pelo nome

Exemplo 2 - Desconectar uma sessão de um computador específico

Exemplo 3 - Usando várias PSSessions em vários computadores

Exemplo 4 - Alterar o valor de tempo limite para uma PSSession

Parâmetros

-Confirm

-Id

-IdleTimeoutSec

-InstanceId

-Name

-OutputBufferingMode

-Session

-ThrottleLimit

-WhatIf

Entradas

Saídas

Notas

Comentários

Recursos adicionais

Disconnect-PSSession

Syntax

Description

Exemplos

Exemplo 1 - Desconectar uma sessão pelo nome

Exemplo 2 - Desconectar uma sessão de um computador específico

Exemplo 3 - Usando várias PSSessions em vários computadores

Exemplo 4 - Alterar o valor de tempo limite para uma PSSession

Parâmetros

-Confirm

-Id

-IdleTimeoutSec

-InstanceId

-Name

-OutputBufferingMode

-Session

-ThrottleLimit

-WhatIf

Entradas

Saídas

Notas

Ligações Relacionadas

Comentários

Recursos adicionais