Disconnect-PSSession

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

Desconecta-se de uma sessão.

Sintaxe

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 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 ao PSSession desconectado da sessão atual ou de outra sessão no computador local ou em um computador diferente.

O Disconnect-PSSession cmdlet desconecta apenas PSSessions abertos que estão conectados à 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 um PSSession desconectado, use os Connect-PSSession cmdlets ou Receive-PSSession .

Quando um PSSession é desconectado, os comandos no PSSession continuam a ser executados até serem concluídos, a menos que o PSSession atinja o tempo limite ou os comandos no PSSession sejam bloqueados por um buffer de saída completo. Para alterar o tempo limite de ociosidade, 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 por nome

Esse comando desconecta o UpdateSession PSSession 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 desconectar 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

Esse comando desconecta o ITTask PSSession 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 pode ser executado mesmo que o buffer de saída da sessão esteja cheio. Como o script grava a saída de um relatório em um compartilhamento de arquivos, outras saídas podem ser perdidas 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 concede tempo para que esse e outros administradores reconectem-se à sessão para verificar se o script foi executado e solucionem os problemas necessários.

Exemplo 3 – Usando vários PSSessions em vários computadores

Esta série de comandos mostra como o Disconnect-PSSession cmdlet pode ser usado em um cenário corporativo. Nesse caso, um novo técnico inicia um script em uma sessão em um computador remoto e encontra um problema. O técnico se desconecta da sessão para que um gerente mais experiente possa se conectar a ela 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 na $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 desconectar 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 de desconexão.

O gerente faz logon em seu computador doméstico, conecta-se à sua 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 gerenciador usa o Connect-PSSession cmdlet para se conectar à ITTask sessão no computador Srv1. O comando salva a sessão na variável $s.

O gerenciador 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, 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, caso ele não exista.

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

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

A propriedade do tempo limite de inatividade de uma sessão é crítica para sessões desconectadas, pois ela determina quanto tempo uma sessão desconectada é mantida antes de ser excluída. Você pode definir a opção de tempo limite de inatividade ao criar uma sessão e quando desconectar-se. Os valores padrão para o tempo limite ocioso $PSSessionOption de uma sessão são definidos na 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 salva a sessão na $s variável. O valor do parâmetro SessionOption é o tempo limite ocioso de 48 horas na $Timeout variável.

O terceiro comando desconecta a ITTask sessão na $s 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 de ociosidade não é usado até que a sessão seja desconectada, essa violação pode passar despercebida 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 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 de ociosidade 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 é medido em milissegundos. A saída confirma que o comando foi bem-sucedido.

Parâmetros

-Confirm

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

-Id

Desconecta-se de sessões com a ID de sessão especificada. 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.

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

-IdleTimeoutSec

Altera o valor de tempo limite ocioso do PSSession desconectado. Insira um valor em segundos. O valor mínimo é 60 (1 minuto).

O tempo limite ocioso determina por quanto tempo o PSSession desconectado é mantido 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 em execução 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 de tempo limite ocioso padrão 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 é de 12 horas (43200000 milissegundos).

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

-InstanceId

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

A ID de instância é um GUID que identifica exclusivamente uma sessão em um computador local ou remoto. O ID de 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.

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

-Name

Desconecta de sessões com os nomes amigáveis especificados. Caracteres curinga 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.

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

-OutputBufferingMode

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

Se o comando na sessão desconectada estiver retornando uma saída e o buffer de saída ficar cheio, o valor desse parâmetro efetivamente determina se o comando continuará a ser executado enquanto a sessão está 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 está cheio, a execução continua. Conforme uma 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.
Tipo:OutputBufferingMode
Cargo:Named
Valor padrão:Block
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 todos os PSSessions que terminam em um computador remoto, incluindo PSSessions que estão desconectados e PSSessions que estão conectados a outras sessões em outros computadores. Disconnect-PSSession desconecta apenas PSSession que estão conectados à sessão atual. Se você canalizar outros PSSessions para Disconnect-PSSession, o Disconnect-PSSession comando falhará.

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

-ThrottleLimit

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

Especifica o número máximo de conexões simultâneas que podem ser estabelecidas para executar este 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.

Tipo:Int32
Cargo:Named
Valor padrão:32
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 canalizar uma sessão para esse cmdlet.

Saídas

PSSession

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

Observações

O Windows PowerShell inclui os seguintes aliases para Disconnect-PSSession:

  • dnsn

  • 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.

  • Sessões de loopback desconectadas com tokens de segurança interativos (aquelas criadas 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 acessos mal-intencionados.

  • Quando você desconecta um PSSession, o estado da sessão é Disconnected e a disponibilidade é Nenhum.

    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 . Ela pode ser conectada a uma sessão diferente. Para determinar se você pode se conectar ou reconectar à sessão, use a propriedade Disponibilidade .

    Um valor de Disponibilidade de None indica 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.