Receive-PSSession
Obtém resultados de comandos em sessões desconectadas
Sintaxe
Receive-PSSession
[-Session] <PSSession>
[-OutTarget <OutTarget>]
[-JobName <String>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]Receive-PSSession
[-Id] <Int32>
[-OutTarget <OutTarget>]
[-JobName <String>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]Receive-PSSession
[-ComputerName] <String>
[-ApplicationName <String>]
[-ConfigurationName <String>]
-Name <String>
[-OutTarget <OutTarget>]
[-JobName <String>]
[-Credential <PSCredential>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[-Port <Int32>]
[-UseSSL]
[-SessionOption <PSSessionOption>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]Receive-PSSession
[-ComputerName] <String>
[-ApplicationName <String>]
[-ConfigurationName <String>]
-InstanceId <Guid>
[-OutTarget <OutTarget>]
[-JobName <String>]
[-Credential <PSCredential>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[-Port <Int32>]
[-UseSSL]
[-SessionOption <PSSessionOption>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]Receive-PSSession
[-ConfigurationName <String>]
[-ConnectionUri] <Uri>
[-AllowRedirection]
-Name <String>
[-OutTarget <OutTarget>]
[-JobName <String>]
[-Credential <PSCredential>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[-SessionOption <PSSessionOption>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]Receive-PSSession
[-ConfigurationName <String>]
[-ConnectionUri] <Uri>
[-AllowRedirection]
-InstanceId <Guid>
[-OutTarget <OutTarget>]
[-JobName <String>]
[-Credential <PSCredential>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[-SessionOption <PSSessionOption>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]Receive-PSSession
-InstanceId <Guid>
[-OutTarget <OutTarget>]
[-JobName <String>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]Receive-PSSession
-Name <String>
[-OutTarget <OutTarget>]
[-JobName <String>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]Description
Este cmdlet só está disponível na plataforma Windows.
O cmdlet Receive-PSSession obtém os resultados dos comandos em execução nas sessões do PowerShell (PSSession) que foram desconectados. Se a sessão estiver conectada no momento, Receive-PSSession obterá os resultados dos comandos que estavam em execução quando a sessão foi desconectada. Se a sessão ainda estiver desconectada, Receive-PSSession se conectar à sessão, retomará todos os comandos que foram suspensos e obterá os resultados dos comandos em execução na sessão.
Esse cmdlet foi introduzido no PowerShell 3.0.
Você pode usar um Receive-PSSession além ou em vez de um comando Connect-PSSession.
Receive-PSSession pode se conectar a qualquer sessão desconectada ou reconectada iniciada em outras sessões ou em outros computadores.
Se você usar o cmdlet Receive-PSSession para se conectar a uma sessão na qual nenhum comando está em execução ou suspenso, Receive-PSSession se conectará à sessão, mas não retornará nenhum erro ou saída.
Para obter mais informações sobre o recurso Sessões Desconectadas, consulte about_Remote_Disconnected_Sessions.
Alguns exemplos usam a modelagem para reduzir o comprimento da linha e melhorar a legibilidade. Para obter mais informações, consulte about_Splatting.
Exemplos
Exemplo 1: Conectar-se a uma PSSession
Este exemplo se conecta a uma sessão em um computador remoto e obtém os resultados de comandos que estão em execução em uma sessão.
Receive-PSSession -ComputerName Server01 -Name ITTaskO
Como o comando não usa o parâmetro OutTarget, os resultados aparecem na linha de comando.
Exemplo 2: obter resultados de todos os comandos em sessões desconectadas
Este exemplo obtém os resultados de todos os comandos em execução em todas as sessões desconectadas em dois computadores remotos.
Se qualquer sessão não tiver sido desconectada ou não estiver executando comandos, Receive-PSSession não se conectará à sessão e não retornará nenhuma saída ou erros.
Get-PSSession -ComputerName Server01, Server02 | Receive-PSSession
Get-PSSession usa o parâmetro ComputerName para especificar os computadores remotos. Os objetos são enviados pelo pipeline para Receive-PSSession.
Exemplo 3: obter os resultados de um script em execução em uma sessão
Este exemplo usa o cmdlet Receive-PSSession para obter os resultados de um script em execução na sessão de um computador remoto.
$parms = @{
ComputerName = "Server01"
Name = "ITTask"
OutTarget = "Job"
JobName = "ITTaskJob01"
Credential = "Domain01\Admin01"
}
Receive-PSSession @parms
Id Name State HasMoreData Location
-- ---- ----- ----------- --------
16 ITTaskJob01 Running True Server01O comando usa os parâmetros Receive-PSSession para retornar os resultados como um trabalho. O parâmetro JobName especifica um nome para o trabalho na sessão reconectada.
O parâmetro credential executa o comando Receive-PSSession usando as permissões de um administrador de domínio.
A saída mostra que Receive-PSSession retornados os resultados como um trabalho na sessão atual. Para obter os resultados do trabalho, use um comando Receive-Job
Exemplo 4: Obter resultados após uma interrupção de rede
Este exemplo usa o cmdlet Receive-PSSession para obter os resultados de um trabalho depois que uma interrupção de rede interrompe uma conexão de sessão. O PowerShell tenta reconectar automaticamente a sessão uma vez por segundo nos próximos quatro minutos e abandona o esforço somente se todas as tentativas no intervalo de quatro minutos falharem.
PS> $s = New-PSSession -ComputerName Server01 -Name AD -ConfigurationName ADEndpoint
PS> $s
Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
8 AD Server01 Opened ADEndpoint Available
PS> Invoke-Command -Session $s -FilePath \\Server12\Scripts\SharedScripts\New-ADResolve.ps1
Running "New-ADResolve.ps1"
# Network outage
# Restart local computer
# Network access is not re-established within 4 minutes
PS> Get-PSSession -ComputerName Server01
Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
1 Backup Server01 Disconnected Microsoft.PowerShell None
8 AD Server01 Disconnected ADEndpoint None
PS> Receive-PSSession -ComputerName Server01 -Name AD -OutTarget Job -JobName AD
Job Id Name State HasMoreData Location
-- ---- ----- ----------- --------
16 ADJob Running True Server01
PS> Get-PSSession -ComputerName Server01
Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
1 Backup Server01 Disconnected Microsoft.PowerShell Busy
8 AD Server01 Opened ADEndpoint AvailableO cmdlet New-PSSession cria uma sessão no computador Server01 e salva a sessão na variável $s. A variável
O cmdlet Invoke-Command executa um script na sessão na variável $s. O script começa a executar e retornar dados, mas ocorre uma interrupção de rede que interrompe a sessão. O usuário precisa sair da sessão e reiniciar o computador local.
Quando o computador é reiniciado, o usuário inicia o PowerShell e executa um comando Get-PSSession para obter sessões no computador Server01. A saída mostra que a sessão do AD do
O cmdlet
O cmdlet Get-PSSession é usado para verificar o estado do trabalho. A saída confirma que o cmdlet
Exemplo 5: Reconectar-se a sessões desconectadas
Este exemplo usa o cmdlet Receive-PSSession para se reconectar às sessões que foram desconectadas intencionalmente e obter os resultados dos trabalhos em execução nas sessões.
PS> $parms = @{
InDisconnectedSession = $True
ComputerName = "Server01", "Server02", "Server30"
FilePath = "\\Server12\Scripts\SharedScripts\Get-BugStatus.ps1"
Name = "BugStatus"
SessionOption = @{IdleTimeout = 86400000}
ConfigurationName = "ITTasks"
}
PS> Invoke-Command @parms
PS> Exit
PS> $s = Get-PSSession -ComputerName Server01, Server02, Server30 -Name BugStatus
PS> $s
Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
1 ITTask Server01 Disconnected ITTasks None
8 ITTask Server02 Disconnected ITTasks None
2 ITTask Server30 Disconnected ITTasks None
PS> $Results = Receive-PSSession -Session $s
PS> $s
Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
1 ITTask Server01 Opened ITTasks Available
8 ITTask Server02 Opened ITTasks Available
2 ITTask Server30 Opened ITTasks Available
PS> $Results
Bug Report - Domain 01
----------------------
ComputerName BugCount LastUpdated
-------------- --------- ------------
Server01 121 Friday, December 30, 2011 5:03:34 PMO cmdlet Invoke-Command executa um script em três computadores remotos. Como o script coleta e resume dados de vários bancos de dados, muitas vezes o script leva um tempo estendido para ser concluído. O comando usa o parâmetro InDisconnectedSession
No dia seguinte, o usuário retoma o Windows, inicia o PowerShell e usa Get-PSSession para obter as sessões em que os scripts estavam em execução. O comando identifica as sessões pelo nome do computador, pelo nome da sessão e pelo nome da configuração da sessão e salva as sessões na variável $s. O valor da variável $s é exibido e mostra que as sessões estão desconectadas, mas não estão ocupadas.
O cmdlet Receive-PSSession se conecta às sessões na variável $s e obtém seus resultados.
O comando salva os resultados na variável $Results. A variável $s é exibida e mostra que as sessões estão conectadas e disponíveis para comandos.
Os resultados do script na variável $Results são exibidos no console do PowerShell. Se algum dos resultados for inesperado, o usuário poderá executar comandos nas sessões para investigar a causa raiz.
Exemplo 6: Executando um trabalho em uma sessão desconectada
Este exemplo mostra o que acontece com um trabalho em execução em uma sessão desconectada.
PS> $s = New-PSSession -ComputerName Server01 -Name Test
PS> $j = Invoke-Command -Session $s { 1..1500 | Foreach-Object {"Return $_"; sleep 30}} -AsJob
PS> $j
Id Name State HasMoreData Location
-- ---- ----- ----------- --------
16 Job1 Running True Server01
PS> $s | Disconnect-PSSession
Id Name ComputerName State ConfigurationName Availability
-- ---- ------------ ----- ----------------- ------------
1 Test Server01 Disconnected Microsoft.PowerShell None
PS> $j
Id Name State HasMoreData Location
-- ---- ----- ----------- --------
16 Job1 Disconnected True Server01
PS> Receive-Job $j -Keep
Return 1
Return 2
PS> $s2 = Connect-PSSession -ComputerName Server01 -Name Test
PS> $j2 = Receive-PSSession -ComputerName Server01 -Name Test
PS> Receive-Job $j
Return 3
Return 4O cmdlet New-PSSession cria a sessão teste no computador Server01. O comando salva a sessão na variável $s.
O cmdlet Invoke-Command executa um comando na sessão na variável $s. O comando usa o parâmetro AsJob para executar o comando como um trabalho e cria o objeto de trabalho na sessão atual.
O comando retorna um objeto de trabalho salvo na variável $j. A variável $j exibe o objeto de trabalho.
O objeto de sessão na variável $s é enviado pelo pipeline para Disconnect-PSSession e a sessão é desconectada.
A variável $j é exibida e mostra o efeito de desconectar o objeto de trabalho na variável $j. O estado do trabalho agora está desconectado.
O Receive-Job é executado no trabalho na variável $j. A saída mostra que o trabalho começou a retornar a saída antes da sessão e o trabalho foi desconectado.
O cmdlet Connect-PSSession é executado na mesma sessão do cliente. O comando se reconecta à sessão de teste no computador Server01 e salva a sessão na variável $s2.
O cmdlet Receive-PSSession obtém os resultados do trabalho em execução na sessão. Como o comando é executado na mesma sessão, Receive-PSSession retorna os resultados como um trabalho por padrão e reutiliza o mesmo objeto de trabalho. O comando salva o trabalho na variável $j2. O cmdlet Receive-Job obtém os resultados do trabalho na variável $j.
Parâmetros
-AllowRedirection
Indica que esse cmdlet permite o redirecionamento dessa conexão para um URI (Uniform Resource Identifier) alternativo.
Quando você usa o parâmetro ConnectionURI, o destino remoto pode retornar uma instrução para redirecionar para um URI diferente. Por padrão, o PowerShell não redireciona conexões, mas você pode usar esse parâmetro para habilitá-lo para redirecionar a conexão.
Você também pode limitar o número de vezes que a conexão é redirecionada alterando o valor da opção MaximumConnectionRedirectionCount sessão. Use o parâmetro MaximumRedirection do cmdlet New-PSSessionOption ou defina a propriedade MaximumConnectionRedirectionCount da variável de preferência $PSSessionOption. O valor padrão é 5.
| Tipo: | SwitchParameter |
| Cargo: | Named |
| Valor padrão: | False |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-ApplicationName
Especifica um aplicativo. Esse cmdlet se conecta apenas às sessões que usam o aplicativo especificado.
Insira o segmento de nome do aplicativo do URI de conexão. Por exemplo, no seguinte URI de conexão, WSMan é o nome do aplicativo: http://localhost:5985/WSMAN.
O nome do aplicativo de uma sessão é armazenado na propriedade Runspace.ConnectionInfo.AppName da sessão.
O valor do parâmetro é usado para selecionar e filtrar sessões. Ele não altera o aplicativo que a sessão usa.
| Tipo: | String |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | False |
-Authentication
Especifica o mecanismo usado para autenticar as credenciais do usuário no comando para se reconectar a uma sessão desconectada. Os valores aceitáveis para este parâmetro são:
- Inadimplência
- Básico
- Credssp
- Digerir
- Kerberos
- Negociar
- NegotiateWithImplicitCredential
O valor padrão é Default.
Para obter mais informações sobre os valores desse parâmetro, consulte de Enumeração AuthenticationMechanism .
Cuidado
A autenticação credSSP (Provedor de Suporte à Segurança de Credencial), na qual as credenciais do usuário são passadas para um computador remoto a ser autenticado, foi projetada para comandos que exigem autenticação em mais de um recurso, como acessar um compartilhamento de rede remoto. Esse mecanismo aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, as credenciais passadas para ele poderão ser usadas para controlar a sessão de rede.
| Tipo: | AuthenticationMechanism |
| Valores aceitos: | Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos |
| Cargo: | Named |
| Valor padrão: | Default |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-CertificateThumbprint
Especifica o certificado de chave pública digital (X509) de uma conta de usuário que tem permissão para se conectar à sessão desconectada. Insira a impressão digital do certificado.
Os certificados são usados na autenticação baseada em certificado do cliente. Os certificados podem ser mapeados apenas para contas de usuário locais e não funcionam com contas de domínio.
Para obter uma impressão digital do certificado, use um comando Get-Item ou Get-ChildItem na unidade de Cert: do PowerShell.
| Tipo: | String |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-ComputerName
Especifica o computador no qual a sessão desconectada é armazenada. As sessões são armazenadas no computador que está no lado do servidor ou recebendo o fim de uma conexão. O padrão é o computador local.
Digite o nome NetBIOS, um endereço IP ou um FQDN (nome de domínio totalmente qualificado) de um computador.
Caracteres curinga não são permitidos. Para especificar o computador local, digite o nome do computador, um ponto (.), $env:COMPUTERNAMEou localhost.
| Tipo: | String |
| Aliases: | Cn |
| Cargo: | 0 |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | False |
-ConfigurationName
Especifica o nome de uma configuração de sessão. Esse cmdlet se conecta 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á acrescentado:
http://schemas.microsoft.com/powershell.
O nome de configuração de uma sessão é armazenado na propriedade ConfigurationName da sessão.
O valor do parâmetro é usado para selecionar e filtrar sessões. Ele não altera a configuração de sessão usada pela sessão.
Para obter mais informações sobre configurações de sessão, consulte about_Session_Configurations.
| Tipo: | String |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | False |
-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 |
-ConnectionUri
Especifica um URI que define o ponto de extremidade de conexão usado para se reconectar à sessão desconectada.
O URI deve ser totalmente qualificado. O formato da cadeia de caracteres é o seguinte:
<Transport>://<ComputerName>:<Port>/<ApplicationName>
O valor padrão é o seguinte:
http://localhost:5985/WSMAN
Se você não especificar um URI de conexão, poderá usar os parâmetros UseSSL, ComputerName, Porte ApplicationName para especificar os valores de URI de conexão.
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 redirecionar a conexão para um URI diferente, o PowerShell impedirá o redirecionamento, a menos que você use o parâmetro AllowRedirection no comando.
| Tipo: | Uri |
| Aliases: | URI, CU |
| Cargo: | 0 |
| Valor padrão: | http://localhost:5985/WSMAN |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | False |
-Credential
Especifica uma conta de usuário que tem permissão para se conectar à sessão desconectada. O padrão é o usuário atual.
Digite um nome de usuário, como
As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.
Nota
Para obter mais informações sobre proteção de dados SecureString, consulte Quão seguro é SecureString?.
| Tipo: | PSCredential |
| Cargo: | Named |
| Valor padrão: | Current user |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-Id
Especifica a ID de uma sessão desconectada. A ID parâmetro funciona somente quando a sessão desconectada foi conectada anteriormente à sessão atual.
Esse parâmetro é válido, mas não eficaz, quando a sessão é armazenada no computador local, mas não foi conectada à sessão atual.
| Tipo: | Int32 |
| Cargo: | 0 |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | False |
-InstanceId
Especifica a ID da instância da sessão desconectada. A ID da instância é um GUID que identifica exclusivamente um de PSSession
| Tipo: | Guid |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-JobName
Especifica um nome amigável para o trabalho que Receive-PSSession retorna.
Receive-PSSession retorna um trabalho quando o valor do parâmetro OutTarget é Job ou o trabalho em execução na sessão desconectada foi iniciado na sessão atual.
Se o trabalho em execução na sessão desconectada tiver sido iniciado na sessão atual, o PowerShell reutilizará o objeto de trabalho original na sessão e ignorará o valor do parâmetro JobName.
Se o trabalho em execução na sessão desconectada tiver sido iniciado em uma sessão diferente, o PowerShell criará um novo objeto de trabalho. Ele usa um nome padrão, mas você pode usar esse parâmetro para alterar o nome.
Se o valor padrão ou o valor explícito do parâmetro OutTarget não for Job, o comando terá êxito, mas o parâmetro JobName não terá efeito.
| Tipo: | String |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-Name
Especifica o nome amigável da sessão desconectada.
| Tipo: | String |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-OutTarget
Determina como os resultados da sessão são retornados. Os valores aceitáveis para este parâmetro são:
- Job. Retorna os resultados de forma assíncrona em um objeto de trabalho. Você pode usar o parâmetro JobName para especificar um nome ou novo nome para o trabalho.
- host. Retorna os resultados para a linha de comando (síncrona). Se o comando estiver sendo retomado ou os resultados consistirem em um grande número de objetos, a resposta poderá ser atrasada.
O valor padrão do parâmetro OutTarget é Host. Se o comando que está sendo recebido em uma sessão desconectada tiver sido iniciado na sessão atual, o valor padrão do parâmetro OutTarget será o formulário no qual o comando foi iniciado. Se o comando tiver sido iniciado como um trabalho, por padrão, ele será retornado como um trabalho. Caso contrário, ele será retornado para o programa host por padrão.
Normalmente, o programa host exibe objetos retornados na linha de comando sem demora, mas esse comportamento pode variar.
| Tipo: | OutTarget |
| Valores aceitos: | Default, Host, Job |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-Port
Especifica a porta de rede do computador remoto usada para se reconectar à sessão. Para se conectar a um computador remoto, ele 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 escutar 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\>
Não use o parâmetro Porta, a menos que seja necessário. A porta definida no comando se aplica a todos os computadores ou sessões nas quais o comando é executado. Uma configuração de porta alternativa pode impedir que o comando seja executado em todos os computadores.
| Tipo: | Int32 |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-Session
Especifica a sessão desconectada. Insira uma variável que contenha o PSSession ou um comando que cria ou obtém o PSSession, como um comando Get-PSSession.
| Tipo: | PSSession |
| Cargo: | 0 |
| Valor padrão: | None |
| Obrigatório: | True |
| Aceitar a entrada de pipeline: | True |
| Aceitar caracteres curinga: | 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 por opções definidas na configuração da sessão.
Os valores de opção de sessão têm precedência sobre 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 valores máximos, cotas ou limites definidos na configuração da sessão.
Para obter uma descrição das opções de sessão que incluem 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 |
| Cargo: | Named |
| Valor padrão: | None |
| Obrigatório: | False |
| Aceitar a entrada de pipeline: | False |
| Aceitar caracteres curinga: | False |
-UseSSL
Indica que esse cmdlet usa o protocolo SSL (Secure Sockets Layer) para se conectar à sessão desconectada. Por padrão, o SSL não é usado.
WS-Management criptografa todo o conteúdo do PowerShell transmitido pela rede. UseSSL é uma proteção adicional que envia os dados em uma conexão HTTPS em vez de uma conexão HTTP.
Se você usar esse parâmetro e o SSL não estiver disponível na porta usada para o comando, o comando falhará.
| Tipo: | SwitchParameter |
| Cargo: | Named |
| Valor padrão: | False |
| 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
Você pode redirecionar objetos de sessão para esse cmdlet, como objetos retornados pelo cmdlet Get-PSSession.
Você pode redirecionar IDs de sessão para este cmdlet.
Você pode canalizar as IDs de instância das sessões deste cmdlet.
Você pode canalizar nomes de sessão para este cmdlet.
Saídas
Se o valor ou o valor padrão do parâmetro OutTarget for Job, Receive-PSSession retornará um objeto de trabalho.
Esse cmdlet retorna os resultados dos comandos executados na sessão desconectada, se houver.
Observações
O PowerShell inclui os seguintes aliases para Receive-PSSession:
- Todas as plataformas:
rcsn
Esse cmdlet só está disponível em plataformas Windows.
Receive-PSSession obtém resultados somente de sessões que foram desconectadas. Somente as sessões que estão conectadas ou terminam em computadores que executam o PowerShell 3.0 ou versões posteriores podem ser desconectadas e reconectadas.
Se os comandos que estavam em execução na sessão desconectada não geraram resultados ou se os resultados já foram retornados para outra sessão, Receive-PSSession não gerará nenhuma saída.
O modo de buffer de saída de uma sessão determina como os comandos na sessão gerenciam a saída quando a sessão é desconectada. Quando o valor da opção OutputBufferingMode da sessão for Drop e o buffer de saída estiver cheio, o comando começará a excluir a saída.
Receive-PSSession não consegue recuperar essa saída. Para obter mais informações sobre a opção de modo de buffer de saída, consulte os artigos de ajuda para os cmdlets New-PSSessionOption e New-PSTransportOption.
Não é possível alterar o valor de tempo limite ocioso de um de PSSession ao se conectar ao de PSSession ou receber resultados. O parâmetro
- Você pode definir e alterar o tempo limite ocioso de uma de PSSession
ao criar ode PSSession , usando os cmdlets ou e quando você se desconectar do PSSession. - A propriedade IdleTimeout de um PSSession é essencial para sessões desconectadas porque determina por quanto tempo uma sessão desconectada é mantida no computador remoto. As sessões 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.
Se você iniciar um trabalho em uma sessão remota usando o parâmetro AsJob do cmdlet Invoke-Command, o objeto de trabalho será criado na sessão atual, mesmo que o trabalho seja executado na sessão remota. Se você desconectar a sessão remota, o objeto de trabalho na sessão atual será desconectado do trabalho. O objeto de trabalho contém todos os resultados que foram retornados a ele, mas não recebe novos resultados do trabalho na sessão desconectada.
Se um cliente diferente se conectar à sessão que contém o trabalho em execução, os resultados que foram entregues ao objeto de trabalho original na sessão original não estarão disponíveis na sessão conectada recentemente. Somente os resultados que não foram entregues ao objeto de trabalho original estão disponíveis na sessão reconectada.
Da mesma forma, se você iniciar um script em uma sessão e se desconectar da sessão, todos os resultados que o script entregar à sessão antes de desconectar não estão disponíveis para outro cliente que se conecta à sessão.
Para evitar a perda de dados em sessões que você pretende desconectar, use o parâmetro
Você também pode evitar a perda de dados usando o cmdlet Invoke-Command para executar um comando Start-Job na sessão remota. Nesse caso, o objeto de trabalho é criado na sessão remota. Você não pode usar o cmdlet Receive-PSSession para obter os resultados do trabalho. Em vez disso, use o cmdlet Connect-PSSession para se conectar à sessão e, em seguida, use o cmdlet Invoke-Command para executar um comando Receive-Job na sessão.
Quando uma sessão que contém um trabalho em execução é desconectada e reconectada, o objeto de trabalho original é reutilizado somente se o trabalho for desconectado e reconectado à mesma sessão e o comando para reconectar não especificar um novo nome de trabalho. Se a sessão for reconectada a uma sessão de cliente diferente ou um novo nome de trabalho for especificado, o PowerShell criará um novo objeto de trabalho para a nova sessão.
Quando você desconecta um PSSession, o estado da sessão é Desconectado e a disponibilidade é Nenhuma.
- O valor da propriedade State é relativo à sessão atual. Um valor desconectado significa que o 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 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.
- Para obter mais informações sobre os valores da propriedade disponibilidade de
de sessões, consulte RunspaceAvailability .