Compartilhar via

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

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

O cmdlet Disconnect-PSSession desconecta uma sessão do PowerShell (PSSession), como uma iniciada usando o cmdlet New-PSSession, 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 cmdlet Disconnect-PSSession se desconecta apenas PSSessions que estão conectados à sessão atual. Disconnect-PSSession não pode desconectar PSSessionsou PSSessions de interativas iniciadas usando o cmdlet Enter-PSSession e não pode desconectar PSSessions que estão conectadas a outras sessões.

Para se reconectar a umPSSession desconectado, use os cmdlets ou .

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

Esse cmdlet é introduzido no Windows PowerShell 3.0.

Exemplos

Exemplo 1 – Desconectar uma sessão por nome

Esse comando desconecta o 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 desconexão foi bem-sucedida. O estado da sessão é e o de Disponibilidade é , 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 PSSession no computador Server12 da sessão atual. A sessão ITTask foi criada na sessão atual e se conecta ao computador Server12. O comando usa o cmdlet Get-PSSession para obter a sessão e o cmdlet Disconnect-PSSession 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 comando Disconnect-PSSession 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 permite 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 cmdlet Disconnect-PSSession 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 despede de 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 cmdlet New-PSSession para criar a sessão ITTask em três computadores remotos. O comando salva as sessões na variável $s. O segundo comando usa o parâmetro FilePath do cmdlet Invoke-Command 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 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 cmdlet Get-PSSession para obter a sessão ITTask no computador Srv1 e o cmdlet Disconnect-PSSession para desconectá-lo. Esse comando não afeta as sessões de ITTask nos outros computadores.

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

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

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

O gerente usa o cmdlet Invoke-Command para executar alguns comandos de diagnóstico na sessão na variável $s. Ele reconhece que o script falhou porque não encontrou um diretório necessário. O gerente usa a função MkDir para criar o diretório e, em seguida, reinicia o script Get-PatchStatus.ps1 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 script Get-PatchStatus.ps1 que cria o diretório necessário se ele não existir.

Exemplo 4 – Alterar o valor do 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 é essencial 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 desconectá-la. Os valores padrão para o tempo limite ocioso de uma sessão são definidos na variável de preferência $PSSessionOption no computador local e na configuração de 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 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 cmdlet New-PSSessionOption 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 (172800000 milissegundos). O comando salva o objeto de opção de sessão na variável $Timeout.

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

O terceiro comando desconecta a sessão ITTask na variável $s. O comando falha porque o valor de tempo limite ocioso da sessão excede a cota de 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 passar despercebida enquanto a sessão estiver em uso.

O quarto comando usa o cmdlet Invoke-Command para executar um comando Get-PSSessionConfiguration para a configuração de sessão Microsoft.PowerShell no computador Server01. O comando usa o cmdlet Format-List 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 IdleTimeout para sessões que usam a configuração da sessão, é 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. A saída mostra que o valor da propriedade IdleTimeout da sessão é milissegundos (48 horas), o que viola a cota de 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 como 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 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 das 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 cmdlet Get-PSSession. A ID da instância é armazenada 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 doPSSession desconectado. Insira um valor em segundos. O valor mínimo é 60 (1 minuto).

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

As PSSessions desconectadas são consideradas ociosas a partir do momento em que estão desconectadas, mesmo que os comandos estejam em execução na sessão desconectada.

O valor padrão do tempo limite ocioso de uma sessão é definido pelo valor do idleTimeoutMs propriedade 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 preferência $PSSessionOption 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 é 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 das sessões com as IDs de instância especificadas.

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

Para obter a ID da instância de uma sessão, use o cmdlet Get-PSSession. A ID da instância é armazenada 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 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 cmdlet Get-PSSession. 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 a saída e o buffer de saída for preenchido, o valor desse parâmetro determinará efetivamente se o comando continua 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 valor Drop, redirecione a saída do comando para um arquivo em disco.

Os valores válidos são:

  • Block: quando o buffer de saída estiver cheio, a execução será suspensa até que o buffer esteja limpo.
  • Drop: quando o buffer de saída está cheio, a execução continua. À 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.
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 cmdlet New-PSSession retorna. Você também pode redirecionar um objeto PSSession para Disconnect-PSSession.

O cmdlet Get-PSSession pode obter todas as PSSessions que terminam em um computador remoto, incluindo PSSessions desconectadas e PSSessions que estão conectadas a outras sessões em outros computadores. Disconnect-PSSession desconecta apenas de PSSession que estão conectadas à sessão atual. Se você redirecionar outras PSSessions para Disconnect-PSSession, o comando Disconnect-PSSession 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 limitação para o comando Disconnect-PSSession.

O limite de limitaçã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 limitação se aplica somente ao comando atual, 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 este cmdlet.

Saídas

PSSession

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

Observações

O PowerShell inclui os seguintes aliases para Disconnect-PSSession:

  • Windows:
    • dnsn

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

  • O cmdlet Disconnect-PSSession funciona somente quando os computadores locais e remotos estão executando o PowerShell 3.0 ou posterior.

  • Se você usar o cmdlet Disconnect-PSSession 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 (aqueles criados com o parâmetro EnableNetworkAccess do ) só podem ser reconectados do computador no qual a sessão foi criada. Essa restrição protege o computador contra acesso mal-intencionado.

  • Quando você desconecta umde PSSession , o estado da sessão é e a disponibilidade é None.

    O valor da propriedade State é relativo à sessão atual. Portanto, um valor de significa que o de PSSession não está conectado à sessão atual. No entanto, isso não significa que o de PSSession esteja desconectado de todas as sessões. Ele pode estar conectado a uma sessão diferente. Para determinar se você pode se conectar ou se reconectar à sessão, use a propriedade de Disponibilidade .

    Um valor de disponibilidade de de 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 de sessões, consulte de Enumeração RunspaceState.

    Para obter mais informações sobre os valores da propriedade Availability de sessões, consulte RunspaceAvailability Enumeration.