Partilhar via

Get-PSSession

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

Obtém as sessões do Windows PowerShell em computadores locais e remotos.

Sintaxe

Get-PSSession
   [-Name <String[]>]
   [<CommonParameters>]
Get-PSSession
   [-ComputerName] <String[]>
   [-ApplicationName <String>]
   [-ConfigurationName <String>]
   [-Name <String[]>]
   [-Credential <PSCredential>]
   [-Authentication <AuthenticationMechanism>]
   [-CertificateThumbprint <String>]
   [-Port <Int32>]
   [-UseSSL]
   [-ThrottleLimit <Int32>]
   [-State <SessionFilterState>]
   [-SessionOption <PSSessionOption>]
   [<CommonParameters>]
Get-PSSession
   [-ComputerName] <String[]>
   [-ApplicationName <String>]
   [-ConfigurationName <String>]
   -InstanceId <Guid[]>
   [-Credential <PSCredential>]
   [-Authentication <AuthenticationMechanism>]
   [-CertificateThumbprint <String>]
   [-Port <Int32>]
   [-UseSSL]
   [-ThrottleLimit <Int32>]
   [-State <SessionFilterState>]
   [-SessionOption <PSSessionOption>]
   [<CommonParameters>]
Get-PSSession
   [-ConnectionUri] <Uri[]>
   [-ConfigurationName <String>]
   [-AllowRedirection]
   [-Name <String[]>]
   [-Credential <PSCredential>]
   [-Authentication <AuthenticationMechanism>]
   [-CertificateThumbprint <String>]
   [-ThrottleLimit <Int32>]
   [-State <SessionFilterState>]
   [-SessionOption <PSSessionOption>]
   [<CommonParameters>]
Get-PSSession
   [-ConnectionUri] <Uri[]>
   [-ConfigurationName <String>]
   [-AllowRedirection]
   -InstanceId <Guid[]>
   [-Credential <PSCredential>]
   [-Authentication <AuthenticationMechanism>]
   [-CertificateThumbprint <String>]
   [-ThrottleLimit <Int32>]
   [-State <SessionFilterState>]
   [-SessionOption <PSSessionOption>]
   [<CommonParameters>]
Get-PSSession
   [-InstanceId <Guid[]>]
   [<CommonParameters>]
Get-PSSession
   [-Id] <Int32[]>
   [<CommonParameters>]

Description

O cmdlet Get-PSSession obtém as sessões do PowerShell gerenciadas pelo usuário (PSSessions) em computadores locais e remotos.

A partir do Windows PowerShell 3.0, as sessões são armazenadas nos computadores na extremidade remota de cada conexão. Você pode usar o ComputerName ou parâmetros ConnectionUri de Get-PSSession para obter as sessões que se conectam ao computador local ou a computadores remotos, mesmo que não tenham sido criadas na sessão atual.

Sem parâmetros, Get-PSSession obtém todas as sessões que foram criadas na sessão atual.

Use os parâmetros de filtragem, incluindo Name, ID, InstanceID, State, ApplicationNamee ConfigurationName para selecionar entre as sessões que Get-PSSession retorna.

Use os parâmetros restantes para configurar a conexão temporária na qual o comando Get-PSSession é executado quando você usa o ComputerName ou parâmetros de ConnectionUri.

Observação : no Windows PowerShell 2.0, sem parâmetros, Get-PSSession obtém todas as sessões que foram criadas na sessão atual. O parâmetro ComputerName obtém sessões que foram criadas na sessão atual e se conectam ao computador especificado.

Para obter mais informações sobre sessões do PowerShell, consulte about_PSSessions.

Exemplos

Exemplo 1: Obter sessões criadas na sessão atual

Get-PSSession

Este comando obtém todos os PSSessions que foram criados na sessão atual. Ele não obtém PSSessions que foram criados em outras sessões ou em outros computadores, mesmo se eles se conectarem a este computador.

Exemplo 2: Obter sessões conectadas ao computador local

Get-PSSession -ComputerName "localhost"

Este comando obtém os PSSessions que estão conectados ao computador local. Para indicar o computador local, digite o nome do computador, localhost ou um ponto (.)

O comando retorna todas as sessões no computador local, mesmo que tenham sido criadas em sessões diferentes ou em computadores diferentes.

Exemplo 3: Obter sessões conectadas a um computador

Get-PSSession -ComputerName "Server02"

Id Name            ComputerName    State         ConfigurationName     Availability
 -- ----            ------------    -----         -----------------     ------------
  2 Session3        Server02       Disconnected  ITTasks                       Busy
  1 ScheduledJobs   Server02       Opened        Microsoft.PowerShell     Available
  3 Test            Server02       Disconnected  Microsoft.PowerShell          Busy

Este comando obtém o PSSessions que estão conectados ao computador Server02.

O comando retorna todas as sessões no Server02, mesmo que tenham sido criadas em sessões diferentes ou em computadores diferentes.

A saída mostra que duas das sessões têm um estado Desconectado e uma disponibilidade Ocupado. Eles foram criados em diferentes sessões e estão atualmente em uso. A sessão ScheduledJobs, que é Aberta e Disponível, foi criada na sessão atual.

Exemplo 4: Salvar resultados deste comando

New-PSSession -ComputerName Server01, Server02, Server03
$s1, $s2, $s3 = Get-PSSession

Este exemplo mostra como salvar os resultados de um comando Get-PSSession em várias variáveis.

O primeiro comando usa o cmdlet New-PSSession para criar PSSessions em três computadores remotos.

O segundo comando usa um cmdlet Get-PSSession para obter os três PSSessions. Em seguida, ele salva cada um dos PSSessions em uma variável separada.

Quando o PowerShell atribui uma matriz de objetos a uma matriz de variáveis, ele atribui o primeiro objeto à primeira variável, o segundo objeto à segunda variável e assim por diante. Se houver mais objetos do que variáveis, ele atribuirá todos os objetos restantes à última variável na matriz. Se houver mais variáveis do que objetos, as variáveis extras não serão usadas.

Exemplo 5: Excluir uma sessão usando um ID de instância

Get-PSSession | Format-Table -Property ComputerName, InstanceID
$s = Get-PSSession -InstanceID a786be29-a6bb-40da-80fb-782c67f7db0f
Remove-PSSession -Session $s

Este exemplo mostra como obter um PSSession usando sua ID de instância e, em seguida, excluir o PSSession.

O primeiro comando obtém todos os PSSessions que foram criados na sessão atual. Ele envia o PSSessions para o cmdlet Format-Table, que exibe as ComputerName e propriedades InstanceID de cada PSSession.

O segundo comando usa o cmdlet Get-PSSession para obter um específico PSSession e salvá-lo na variável $s. O comando usa o parâmetro InstanceID para identificar o PSSession.

O terceiro comando usa o cmdlet Remove-PSSession para excluir o PSSession na variável $s.

Exemplo 6: Obter uma sessão com um nome específico

Os comandos neste exemplo localizam uma sessão que tem um formato de nome específico e usam uma configuração de sessão específica e, em seguida, conectam-se à sessão. Você pode usar um comando como este para encontrar uma sessão na qual um colega iniciou uma tarefa e se conectar para concluir a tarefa.

Get-PSSession -ComputerName Server02, Server12 -Name BackupJob* -ConfigurationName ITTasks -SessionOption @{OperationTimeout=240000}

Id Name            ComputerName    State         ConfigurationName     Availability
 -- ----            ------------    -----         -----------------     ------------
  3 BackupJob04     Server02        Disconnected        ITTasks                  None

$s = Get-PSSession -ComputerName Server02 -Name BackupJob04 -ConfigurationName ITTasks | Connect-PSSession
$s

Id Name            ComputerName    State         ConfigurationName     Availability
-- ----            ------------    -----         -----------------     ------------
 5 BackupJob04     Server02        Opened        ITTasks                  Available

O primeiro comando obtém sessões nos computadores remotos Server02 e Server12 que têm nomes que começam com BackupJob e usam a configuração de sessão ITTasks. O comando usa o parâmetro Name para especificar o padrão name e o parâmetro ConfigurationName para especificar a configuração da sessão. O valor do parâmetro SessionOption é uma tabela de hash que define o valor do OperationTimeout como 240000 milissegundos (4 minutos). Essa configuração dá ao comando mais tempo para ser concluído. Os parâmetros ConfigurationName e SessionOption são usados para configurar as sessões temporárias nas quais o cmdlet Get-PSSession é executado em cada computador. A saída mostra que o comando retorna a sessão BackupJob04. A sessão está desconectada e o de disponibilidade de é Nenhum, o que indica que ele não está em uso.

O segundo comando usa o cmdlet Get-PSSession para chegar à sessão BackupJob04 e o cmdlet Connect-PSSession para se conectar à sessão. O comando salva a sessão na variável $s.

O terceiro comando obtém a sessão na variável $s. A saída mostra que o comando Connect-PSSession foi bem-sucedido. A sessão está no estado Aberto e está disponível para uso.

Exemplo 7: Obter uma sessão usando sua ID

Get-PSSession -Id 2

Este comando obtém o PSSession com ID 2. Como o valor da propriedade ID é exclusivo somente na sessão atual, o parâmetro Id é válido apenas para comandos locais.

Parâmetros

-AllowRedirection

Indica que esse cmdlet permite o redirecionamento dessa conexão para um URI (Uniform Resource Identifier) alternativo. Por padrão, o PowerShell não redireciona conexões.

Este parâmetro configura a conexão temporária criada para executar um comando Get-PSSession com o parâmetro ConnectionUri.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ApplicationName

Especifica o nome de um aplicativo. Esse cmdlet se conecta somente a sessões que usam o aplicativo especificado.

Insira o segmento de nome do aplicativo do URI de conexão. Por exemplo, no URI de conexão a seguir, o nome do aplicativo é WSMan: https://localhost:5985/WSMAN. O nome do 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 que a sessão usa.

Tipo:String
Position:Named
Default value:All sessions
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Authentication

Especifica o mecanismo usado para autenticar credenciais para a sessão na qual o comando Get-PSSession é executado.

Este parâmetro configura a conexão temporária criada para executar um comando Get-PSSession com o ComputerName ou parâmetro ConnectionUri.

Os valores aceitáveis para este parâmetro são:

  • Inadimplência
  • Básico
  • Credssp
  • Resumo
  • Kerberos
  • Negociar
  • NegotiateWithImplicitCredential.

O valor padrão é Default.

Para obter mais informações sobre os valores desse parâmetro, consulte de enumeração AuthenticationMechanism na biblioteca MSDN.

CUIDADO: A autenticação CredSSP (Credential Security Support Provider), na qual as credenciais do usuário são passadas para um computador remoto para ser autenticado, é projetada para comandos que exigem autenticação em mais de um recurso, como acessar um compartilhamento de rede remoto. Este mecanismo aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, as credenciais que são passadas para ele podem ser usadas para controlar a sessão de rede.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:AuthenticationMechanism
Valores aceites:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:Default
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-CertificateThumbprint

Especifica o certificado de chave pública digital (X509) de uma conta de usuário que tem permissão para criar a sessão na qual o comando Get-PSSession é executado. Insira a impressão digital do certificado.

Este parâmetro configura a conexão temporária criada para executar um comando Get-PSSession com o ComputerName ou parâmetro ConnectionUri.

Os certificados são usados na autenticação baseada em certificado de cliente. Eles podem ser mapeados apenas para contas de usuário locais; eles não funcionam com contas de domínio.

Para obter uma impressão digital de certificado, use um comando Get-Item ou Get-ChildItem na unidade PowerShell Cert:.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ComputerName

Especifica uma matriz de nomes de computadores. Obtém as sessões que se conectam aos computadores especificados. Caracteres curinga não são permitidos. Não há nenhum valor padrão.

A partir do Windows PowerShell 3.0, objetos de PSSession são armazenados nos computadores na extremidade remota de cada conexão. Para obter as sessões nos computadores especificados, o PowerShell cria uma conexão temporária com cada computador e executa um comando Get-PSSession.

Digite o nome NetBIOS, um endereço IP ou um nome de domínio totalmente qualificado de um ou mais computadores. Para especificar o computador local, digite o nome do computador, localhost ou um ponto (.).

Observação: esse parâmetro obtém sessões somente de computadores que executam o Windows PowerShell 3.0 ou versões posteriores do PowerShell. As versões anteriores não armazenam sessões.

Tipo:String[]
Aliases:Cn
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-ConfigurationName

Especifica o nome de uma configuração. Este cmdlet chega apenas a sessões que usam a configuração de sessão especificada.

Insira um nome de configuração ou o URI de 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á precedido: https://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 da sessão que a sessão usa.

Para obter mais informações sobre configurações de sessão, consulte about_Session_Configurations.

Tipo:String
Position:Named
Default value:All sessions
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-ConnectionUri

Especifica um URI que define o ponto de extremidade de conexão para a sessão temporária na qual o comando Get-PSSession é executado. O URI deve ser totalmente qualificado.

Este parâmetro configura a conexão temporária criada para executar um comando Get-PSSession com o parâmetro ConnectionUri.

O formato desta cadeia de caracteres é:

Transporte <>://<ComputerName>:<Port>/<ApplicationName>

O valor padrão é: https://localhost:5985/WSMAN.

Se você não especificar um ConnectionUri, poderá usar os UseSSL, ComputerName, Porte parâmetros ApplicationName para especificar os valores de ConnectionURI. 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 de Transporte, mas não especificar uma porta, a sessão será criada com portas padrão: 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 redireciona a conexão para um URI diferente, o PowerShell impede o redirecionamento, a menos que você use o parâmetro AllowRedirection no comando.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Esse parâmetro obtém sessões somente de computadores que executam o Windows PowerShell 3.0 ou versões posteriores do Windows PowerShell. As versões anteriores não armazenam sessões.

Tipo:Uri[]
Aliases:URI, CU
Position:0
Default value:Http://localhost:5985/WSMAN
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Credential

Especifica uma credencial de usuário. Este cmdlet executa o comando com as permissões do usuário especificado. Especifique uma conta de usuário que tenha permissão para se conectar ao computador remoto e execute um comando Get-PSSession. O padrão é o usuário atual. Digite um nome de usuário, como User01, Domain01\User01ou User@Domain.com, ou insira um objeto PSCredential, como um retornado pelo cmdlet Get-Credential. Quando você digita um nome de usuário, esse cmdlet solicita uma senha.

Este parâmetro configura para a conexão temporária que é criada para executar um comando Get-PSSession com o ComputerName ou parâmetro ConnectionUri.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:PSCredential
Position:Named
Default value:Current user
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Id

Especifica uma matriz de IDs de sessão. Este cmdlet obtém apenas as sessões com as IDs especificadas. Digite uma ou mais IDs, separadas por vírgulas, ou use o operador de intervalo (..) para especificar um intervalo de IDs. Não é possível usar o parâmetro ID junto com o parâmetro ComputerName.

Um ID é um número inteiro que identifica exclusivamente as sessões gerenciadas pelo usuário na sessão atual. É mais fácil de lembrar e digitar do que o InstanceId, mas é exclusivo apenas dentro da sessão atual. A ID de uma sessão é armazenada na propriedade ID da sessão.

Tipo:Int32[]
Position:0
Default value:All sessions
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-InstanceId

Especifica uma matriz de IDs de instância de sessões. Este cmdlet obtém apenas as sessões com as IDs de instância especificadas.

O ID da instância é um GUID que identifica exclusivamente uma sessão em um computador local ou remoto. O InstanceID é exclusivo, mesmo quando você tem várias sessões em execução no PowerShell.

O ID da instância de uma sessão é armazenado na propriedade InstanceID da sessão.

Tipo:Guid[]
Position:Named
Default value:All sessions
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Name

Especifica uma matriz de nomes de sessão. Este cmdlet obtém apenas as sessões que têm os nomes amigáveis especificados. Caracteres curinga são permitidos.

O nome amigável de uma sessão é armazenado na propriedade Name da sessão.

Tipo:String[]
Position:Named
Default value:All sessions
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:True

-Port

Especifica a porta de rede especificada que é usada para a conexão temporária na qual o comando Get-PSSession é executado. Para se conectar a um computador remoto, o computador remoto deve estar escutando na porta que a conexão usa. 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 do WinRM no computador remoto para ouvir nessa 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\>

Este parâmetro configura para a conexão temporária que é criada para executar um comando Get-PSSession com o ComputerName ou parâmetro ConnectionUri.

Não use o parâmetro Port, a menos que seja necessário. O de Porta definido no comando aplica-se 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.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:Int32
Position:Named
Default value:5985, 5986
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-SessionOption

Especifica opções avançadas para a sessão. Insira um objeto SessionOption, como um que você cria usando o cmdlet New-PSSessionOption, 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 preferência $PSSessionOption, se ela estiver definida. Caso contrário, os valores padrão são estabelecidos pelas opções definidas na configuração da sessão.

Os valores de opção de sessão têm precedência sobre os valores padrão para sessões definidas na variável de preferência $PSSessionOption e na configuração da sessão. No entanto, eles não têm precedência sobre os valores máximos, cotas ou limites definidos na configuração da sessão.

Para obter uma descrição das opções de sessão, incluindo 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.

Tipo:PSSessionOption
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-State

Especifica um estado de sessão. Este cmdlet obtém apenas sessões no estado especificado. Os valores aceitáveis para este parâmetro são: Todos, Aberto, Desconectado, Fechado e Quebrado. O valor padrão é All.

O valor do estado da sessão é relativo às sessões atuais. As sessões que não foram criadas nas sessões atuais e não estão conectadas à sessão atual têm um estado de Desconectadas, mesmo quando estão conectadas a uma sessão diferente.

O estado de uma sessão é armazenado na propriedade State da sessão.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:SessionFilterState
Valores aceites:All, Opened, Disconnected, Closed, Broken
Position:Named
Default value:All
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ThrottleLimit

Especifica o número máximo de conexões simultâneas que podem ser estabelecidas para executar o comando Get-PSSession. Se você omitir esse parâmetro ou inserir um valor de 0 (zero), 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.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:Int32
Position:Named
Default value:32
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-UseSSL

Indica que esse cmdlet usa o protocolo SSL (Secure Sockets Layer) para estabelecer a conexão na qual o comando Get-PSSession é executado. Por padrão, o SSL não é usado. Se você usar esse parâmetro, mas o SSL não estiver disponível na porta usada para o comando, o comando falhará.

Este parâmetro configura a conexão temporária criada para executar um comando Get-PSSession com o parâmetro ComputerName.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

Entradas

None

Não é possível canalizar a entrada para este cmdlet.

Saídas

PSSession

Notas

  • Este cmdlet obtém sessões gerenciadas pelo usuário objetos de PSSession", como aqueles que são criados usando os cmdlets New-PSSession, Enter-PSSessione Invoke-Command. Ele não obtém a sessão gerenciada pelo sistema que é criada quando você inicia o PowerShell.
  • A partir do Windows PowerShell 3.0, objetos de PSSession são armazenados no computador que está no lado do servidor ou na extremidade recetora de uma conexão. Para obter as sessões armazenadas no computador local ou em um computador remoto, o PowerShell estabelece uma sessão temporária no computador especificado e executa comandos de consulta na sessão.
  • Para obter sessões que se conectam a um computador remoto, use os parâmetros ComputerName ou ConnectionUri para especificar o computador remoto. Para filtrar as sessões que Get-PSSession obtém, use os parâmetros Name, ID, InstanceIDe State parâmetros. Use os parâmetros restantes para configurar a sessão temporária que Get-PSSession usa.
  • Quando você usa o ComputerName ou parâmetros de ConnectionUri, Get-PSSession obtém apenas sessões de computadores que executam o Windows PowerShell 3.0 e versões posteriores do PowerShell.
  • O valor da propriedade State de um PSSession é relativo à sessão atual. Portanto, um valor de Desconectado 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 ao PSSession da sessão atual, use a propriedade Disponibilidade .

Um valor de de Disponibilidade de de Nenhum indica que você pode se conectar à sessão. Um valor de Ocupado 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 RunspaceState Enumeration.

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