Partilhar via

Disconnect-PSSession

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

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

O Disconnect-PSSession cmdlet desliga uma sessão do PowerShell ("PSSession"), como uma iniciada com o New-PSSession cmdlet, da sessão atual. Como resultado, a PSSession está num estado desligado. Pode ligar à PSSession desligada a partir da sessão atual ou de outra sessão no computador local ou num computador diferente.

O Disconnect-PSSession cmdlet desliga apenas as PSSessions que estão ligadas à sessão atual. Disconnect-PSSession Não é possível desligar PSSessions quebradas ou fechadas ou PSSessions interativas iniciadas com o Enter-PSSession cmdlet e não pode desligar PSSessions que estão ligadas a outras sessões.

Para ligar novamente a uma PSSession desligada, utilize os Connect-PSSession cmdlets ou Receive-PSSession .

Quando uma PSSession é desligada, os comandos na PSSession continuam a ser executados até serem concluídos, a menos que a PSSession exceda o limite de tempo ou os comandos na PSSession sejam bloqueados por uma memória intermédia de saída completa. Para alterar o tempo limite de inatividade, utilize o parâmetro IdleTimeoutSec . Para alterar o modo de memória intermédia de saída, utilize o parâmetro OutputBufferingMode Também pode utilizar o parâmetro InDisconnectedSession do Invoke-Command cmdlet para executar um comando numa sessão desligada.

Para obter mais informações sobre a funcionalidade Sessões Desligadas, consulte about_Remote_Disconnected_Sessions.

Este cmdlet é introduzido no Windows PowerShell 3.0.

Exemplos

Exemplo 1 - Desligar uma sessão por nome

Este comando desliga a PSSession UpdateSession no computador Server01 da sessão atual. O comando utiliza o parâmetro Nome para identificar a 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 desligar foi bem-sucedida. O estado da sessão é Desligado e a Disponibilidade é Nenhuma, o que indica que a sessão não está ocupada e pode ser restabelecida novamente.

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

Este comando desliga a ITTask PSSession no computador Server12 da sessão atual. A sessão ITTask foi criada na sessão atual e liga-se ao computador Server12. O comando utiliza o Get-PSSession cmdlet para obter a sessão e o Disconnect-PSSession cmdlet para o desligar.

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 utiliza o parâmetro OutputBufferingMode para definir o modo de saída como Drop. Esta definição garante que o script que está em execução na sessão pode continuar a ser executado mesmo que a memória intermédia de saída da sessão esteja cheia. Uma vez que o script escreve o resultado num relatório numa partilha de ficheiros, pode perder-se outra saída sem consequências.

O comando também utiliza o parâmetro IdleTimeoutSec para prolongar o tempo limite de inatividade da sessão para 24 horas. Esta definição permite que este administrador ou outros administradores voltem a ligar-se à sessão para verificar se o script foi executado e resolver problemas, se necessário.

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

Esta série de comandos mostra como o Disconnect-PSSession cmdlet pode ser utilizado num cenário empresarial. Neste caso, um novo técnico inicia um script numa sessão num computador remoto e encontra um problema. O técnico desliga-se da sessão para que um gestor mais experiente possa ligar-se à 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 por criar sessões em vários computadores remotos e executar um script em cada sessão. O primeiro comando utiliza o New-PSSession cmdlet para criar a sessão ITTask em três computadores remotos. O comando guarda as sessões na variável $s. O segundo comando utiliza o parâmetro FilePath do Invoke-Command cmdlet para executar um script nas sessões na variável $s.

O script em execução no computador Srv1 gera erros inesperados. O técnico contacta o seu gestor e pede ajuda. O gestor direciona o técnico a desligar-se da sessão para que possa investigar. O segundo comando utiliza o Get-PSSession cmdlet para obter a sessão ITTask no computador Srv1 e o cmdlet para o Disconnect-PSSession desligar. Este comando não afeta as sessões de ITTask nos outros computadores.

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

O gestor inicia sessão no seu computador doméstico, liga-se à sua rede empresarial, inicia Windows PowerShell e utiliza o Get-PSSession cmdlet para obter a sessão ITTask no computador Srv1. Utiliza as credenciais do técnico para aceder à sessão.

Em seguida, o gestor utiliza o Connect-PSSession cmdlet para ligar à sessão ITTask no computador Srv1. O comando guarda a sessão na variável $s.

O gestor utiliza o Invoke-Command cmdlet para executar alguns comandos de diagnóstico na sessão na $s variável. Reconhece que o script falhou porque não encontrou um diretório necessário. O gestor utiliza a MkDir função para criar o diretório e, em seguida, reinicia o Get-PatchStatus.ps1 script e desliga-se da sessão. O gestor comunica as suas conclusões ao técnico, sugere que se volte a ligar à sessão para concluir as tarefas e pede-lhe para adicionar um comando ao Get-PatchStatus.ps1 script que cria o diretório necessário se não existir.

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

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

A propriedade de tempo limite de inatividade de uma sessão é fundamental para sessões desligadas, uma vez que determina quanto tempo uma sessão desligada é mantida antes de ser eliminada. Pode definir a opção de tempo limite de inatividade quando cria uma sessão e quando a desliga. Os valores predefinidos para o tempo limite de inatividade 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 de sessão não podem exceder as quotas 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                   : https://schemas.microsoft.com/powershell/microsoft.powershell
MaxConcurrentCommandsPerShell : 1000
UseSharedProcess              : false
ProcessIdleTimeoutSec         : 0
xmlns                         : https://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                           : https://schemas.microsoft.com/powershell/microsoft.powershell
SDKVersion                    : 2
Name                          : microsoft.powershell
XmlRenderingType              : text
Capability                    : {Shell}
RunAsPassword                 :
MaxProcessesPerShell          : 15
ParentResourceUri             : https://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                          : https://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 utiliza o New-PSSessionOption cmdlet para criar um objeto de opção de sessão. Utiliza o parâmetro IdleTimeout para definir um tempo limite de inatividade de 48 horas (1728000000 milissegundos). O comando guarda o objeto de opção de sessão na variável $Timeout.

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

O terceiro comando desliga a sessão ITTask na variável $s. O comando falha porque o valor de tempo limite de inatividade da sessão excede a quota MaxIdleTimeoutMs na configuração da sessão. Uma vez que o tempo limite de inatividade não é utilizado até a sessão estar desligada, esta violação pode não ser detetada enquanto a sessão estiver a ser utilizada.

O quarto comando utiliza o Invoke-Command cmdlet para executar um Get-PSSessionConfiguration comando para a configuração da sessão Microsoft.PowerShell no computador Server01. O comando utiliza o Format-List cmdlet para apresentar todas as propriedades da configuração da sessão numa lista. O resultado mostra que a propriedade MaxIdleTimeoutMS , que estabelece o valor máximo permitido idleTimeout para sessões que utilizam a configuração da sessão, é de 43200000 milissegundos (12 horas).

O quinto comando obtém os valores de opção de sessão da sessão na variável $s. Os valores de muitas opções de sessão são propriedades da propriedade ConnectionInfo da propriedade Runspace da sessão. O resultado mostra que o valor da propriedade IdleTimeout da sessão é 1728000000 milissegundos (48 horas), o que viola a quota maxIdleTimeoutMs de 12 horas na configuração da sessão. Para resolver este conflito, pode utilizar o parâmetro ConfigurationName para selecionar uma configuração de sessão diferente ou utilizar o parâmetro IdleTimeout para reduzir o tempo limite de inatividade da sessão.

O sexto comando desliga a sessão. Utiliza o parâmetro IdleTimeoutSec para definir o tempo limite de inatividade para o máximo de 12 horas.

O sétimo comando obtém o valor da propriedade IdleTimeout da sessão desligada, que é medida em milissegundos. O resultado 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

Desliga-se das sessões com o ID de sessão especificado. Escreva um ou mais IDs (separados por vírgulas) ou utilize o operador de intervalo (..) para especificar um intervalo de IDs.

Para obter o ID de uma sessão, utilize 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 inativo da PSSession desligada. Introduza um valor em segundos. O valor mínimo é 60 (1 minuto).

O tempo limite de inatividade determina quanto tempo a PSSession desligada é mantida no computador remoto. Quando o tempo limite expirar, a PSSession é eliminada.

As PSSessions desligadas são consideradas inativas desde o momento em que estão desligadas, mesmo que os comandos estejam em execução na sessão desligada.

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

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

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

-InstanceId

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

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

Para obter o ID de instância de uma sessão, utilize 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

Desliga-se das sessões com os nomes amigáveis especificados. Os carateres universais são permitidos.

Para obter o nome amigável de uma sessão, utilize o Get-PSSession cmdlet. O nome amigável é armazenado na propriedade Nome 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 é gerida na sessão desligada quando a memória intermédia de saída está cheia. O valor predefinido é Bloquear.

Se o comando na sessão desligada estiver a devolver a saída e a memória intermédia de saída for preenchida, o valor deste parâmetro determina efetivamente se o comando continua a ser executado enquanto a sessão está desligada. Um valor de Bloquear suspende o comando até que a sessão seja restabelecida. Um valor de Drop permite que o comando seja concluído, embora os dados possam ser perdidos. Ao utilizar o valor Drop , redirecione a saída do comando para um ficheiro no disco.

Os valores válidos são:

  • Bloco: quando a memória intermédia de saída está cheia, a execução é suspensa até a memória intermédia estar limpa.
  • Largar: quando a memória intermédia de saída está cheia, a execução continua. À medida que a nova saída é guardada, a saída mais antiga é eliminada.
  • Nenhum: não é especificado nenhum modo de memória intermédia de saída. O valor da propriedade OutputBufferingMode da configuração da sessão é utilizado para a sessão desligada.
Type:OutputBufferingMode
Position:Named
Default value:Block
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Session

Desliga-se das PSSessions especificadas. Introduza objetos PSSession, como os que o New-PSSession cmdlet devolve. Também pode encaminhar um objeto PSSession para Disconnect-PSSession.

O Get-PSSession cmdlet pode obter todas as PSSessions que terminam num computador remoto, incluindo PSSessions que estão desligadas e PSSessions que estão ligadas a outras sessões noutros computadores. Disconnect-PSSession desliga apenas a PSSession ligada à sessão atual. Se encaminhar 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 limitação para o Disconnect-PSSession comando.

O limite de limitação é o número máximo de ligações simultâneas que podem ser estabelecidas para executar este comando. Se omitir este parâmetro ou introduzir um valor de 0, é utilizado o valor predefinido, 32.

O limite de limitaçã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

Pode encaminhar uma sessão para Disconnect-PSSession.

Saídas

PSSession

Disconnect-PSSession devolve um objeto que representa a sessão que desligou.

Notas

  • O Disconnect-PSSession cmdlet só funciona quando os computadores locais e remotos executam o PowerShell 3.0 ou posterior.

  • Se utilizar o Disconnect-PSSession cmdlet numa sessão desligada, o comando não tem qualquer efeito na sessão e não gera erros.

  • As sessões de loopback desligadas com tokens de segurança interativos (aqueles criados com o parâmetro EnableNetworkAccess ) só podem ser restabelecidas a partir do computador no qual a sessão foi criada. Esta restrição protege o computador contra acesso malicioso.

  • Quando desliga uma PSSession, o estado da sessão é Desligado e a disponibilidade é Nenhuma.

    O valor da propriedade Estado é relativo à sessão atual. Portanto, um valor de Desligado significa que a PSSession não está ligada à sessão atual. No entanto, não significa que a PSSession esteja desligada de todas as sessões. Pode estar ligado a uma sessão diferente. Para determinar se consegue ligar ou voltar a ligar à sessão, utilize a propriedade Disponibilidade .

    Um valor disponibilidade de Nenhum indica que pode ligar à sessão. Um valor de Ocupado indica que não é possível ligar à PSSession porque está ligado a outra sessão.

    Para obter mais informações sobre os valores da propriedade Estado das sessões, veja Enumeração RunspaceState.

    Para obter mais informações sobre os valores da propriedade Disponibilidade das sessões, veja RunspaceAvailability Enumeration (Enumeração RunspaceAvailability).