Compartilhar via

Enter-PSSession

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

Inicia uma sessão interativa com um computador remoto.

Sintaxe

Enter-PSSession
     [-ComputerName] <String>
     [-EnableNetworkAccess]
     [-Credential <PSCredential>]
     [-Port <Int32>]
     [-UseSSL]
     [-ConfigurationName <String>]
     [-ApplicationName <String>]
     [-SessionOption <PSSessionOption>]
     [-Authentication <AuthenticationMechanism>]
     [-CertificateThumbprint <String>]
     [<CommonParameters>]
Enter-PSSession
     [[-Session] <PSSession>]
     [<CommonParameters>]
Enter-PSSession
     [[-ConnectionUri] <Uri>]
     [-EnableNetworkAccess]
     [-Credential <PSCredential>]
     [-ConfigurationName <String>]
     [-AllowRedirection]
     [-SessionOption <PSSessionOption>]
     [-Authentication <AuthenticationMechanism>]
     [-CertificateThumbprint <String>]
     [<CommonParameters>]
Enter-PSSession
     [-InstanceId <Guid>]
     [<CommonParameters>]
Enter-PSSession
     [[-Id] <Int32>]
     [<CommonParameters>]
Enter-PSSession
     [-Name <String>]
     [<CommonParameters>]
Enter-PSSession
     [-VMGuid] <Guid>
     -Credential <PSCredential>
     [<CommonParameters>]
Enter-PSSession
     [-VMName] <String>
     -Credential <PSCredential>
     [<CommonParameters>]

Description

O cmdlet Enter-PSSession inicia uma sessão interativa com um único computador remoto. Durante a sessão, os comandos que você digita são executados no computador remoto, como se estivesse digitando diretamente no computador remoto. Você pode ter apenas uma sessão interativa por vez.

Normalmente, você usa o parâmetro ComputerName para especificar o nome do computador remoto. No entanto, você também pode usar uma sessão criada usando o cmdlet New-PSSession para a sessão interativa. No entanto, você não pode usar os cmdlets Disconnect-PSSession, Connect-PSSession ou Receive-PSSession para se desconectar ou se conectar novamente a uma sessão interativa.

Para encerrar a sessão interativa e desconectar do computador remoto, use o cmdlet Exit-PSSession ou digite exit.

Exemplos

Exemplo 1: iniciar uma sessão interativa

PS C:\> Enter-PSSession
[localhost]: PS C:\>

Esse comando inicia uma sessão interativa no computador local. O prompt de comando é alterado para indicar que agora você está executando comandos em uma sessão diferente.

Os comandos inseridos são executados na nova sessão e os resultados são retornados à sessão padrão como texto.

Exemplo 2: Trabalhar com uma sessão interativa

The first command uses the **Enter-PSSession** cmdlet to start an interactive session with Server01, a remote computer. When the session starts, the command prompt changes to include the computer name.
PS C:\> Enter-PSSession -ComputerName Server01
[Server01]: PS C:\>

The second command gets the Windows PowerShell process and redirects the output to the Process.txt file. The command is submitted to the remote computer, and the file is saved on the remote computer.
[Server01]: PS C:\> Get-Process PowerShell > C:\ps-test\Process.txt

The third command uses the **Exit** keyword to end the interactive session and close the connection.
[Server01]: PS C:\> exit
PS C:\>

The fourth command confirms that the Process.txt file is on the remote computer. A **Get-ChildItem** ("dir") command on the local computer cannot find the file.
PS C:\> dir C:\ps-test\process.txt
Get-ChildItem : Cannot find path 'C:\ps-test\process.txt' because it does not exist.
At line:1 char:4
+ dir <<<<  c:\ps-test\process.txt

Este comando mostra como trabalhar em uma sessão interativa com um computador remoto.

Exemplo 3: Usar o parâmetro Session

PS C:\> $s = New-PSSession -ComputerName Server01
PS C:\> Enter-PSSession -Session $s
[Server01]: PS C:\>

Esses comandos usam o parâmetro Session de Enter-PSSession para executar a sessão interativa em uma sessão existente do Windows PowerShell (PSSession).

Exemplo 4: iniciar uma sessão interativa e especificar os parâmetros porta e credencial

PS C:\> Enter-PSSession -ComputerName Server01 -Port 90 -Credential Domain01\User01
[Server01]: PS C:\>

Esse comando inicia uma sessão interativa com o computador Server01. Ele usa o parâmetro Port para especificar a porta e o parâmetro para especificar a conta de um usuário que tem permissão para se conectar ao computador remoto.

Exemplo 5: Interromper uma sessão interativa

PS C:\> Enter-PSSession -ComputerName Server01
[Server01]: PS C:\> Exit-PSSession
PS C:\>

Este exemplo mostra como iniciar e parar uma sessão interativa. O primeiro comando usa o cmdlet Enter-PSSession para iniciar uma sessão interativa com o computador Server01.

O segundo comando usa o cmdlet Exit-PSSession para encerrar a sessão. Você também pode usar a palavra-chave Exit para encerrar a sessão interativa. Exit-PSSession e Exit têm o mesmo efeito.

Parâmetros

-AllowRedirection

Permite o redirecionamento dessa conexão para um URI (Uniform Resource Identifier) alternativo. Por padrão, o redirecionamento não é permitido.

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 Windows PowerShell não redireciona conexões, mas você pode usar esse parâmetro para permitir que ele redirecione 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:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ApplicationName

Especifica o segmento de nome do aplicativo do URI de conexão. Use esse parâmetro para especificar o nome do aplicativo quando você não estiver usando o parâmetro ConnectionURI no comando.

O valor padrão é o valor da variável de preferência $PSSessionApplicationName no computador local. Se essa variável de preferência não estiver definida, o valor padrão será WSMAN. Esse valor é apropriado para a maioria dos usos. Para obter mais informações, consulte about_Preference_Variables.

O serviço WinRM usa o nome do aplicativo para selecionar um ouvinte para atender à solicitação de conexão. O valor desse parâmetro deve corresponder ao valor da propriedade URLPrefix de um ouvinte no computador remoto.

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. Os valores aceitáveis para este parâmetro são:

  • Inadimplência
  • Básico
  • Credssp
  • Digerir
  • Kerberos
  • Negociar
  • NegotiateWithImplicitCredential

O valor padrão é Default.

A autenticação credSSP está disponível apenas no Windows Vista, windows server 2008 e versões posteriores do sistema operacional Windows.

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

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:None
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 executar essa ação. Insira a impressão digital do certificado.

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

Para obter um certificado, use o comando Get-Item ou Get-ChildItem no Certificado do Windows PowerShell: unidade.

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

-ComputerName

Especifica um nome de computador. Esse cmdlet inicia uma sessão interativa com o computador remoto especificado. Insira apenas um nome de computador. O padrão é o computador local.

Digite o nome NetBIOS, o endereço IP ou o nome de domínio totalmente qualificado do computador. Você também pode canalizar um nome de computador para Enter-PSSession.

Para usar um endereço IP no valor do parâmetro ComputerName, o comando deve incluir o parâmetro Credential. Além disso, o computador deve ser configurado para transporte HTTPS ou o endereço IP do computador remoto deve ser incluído na lista WinRM TrustedHosts no computador local. Para obter instruções sobre como adicionar um nome de computador à lista TrustedHosts, consulte "Como adicionar um computador à lista de host confiável" em about_Remote_Troubleshooting.

Observação: no Windows Vista e nas versões posteriores do sistema operacional Windows, para incluir o computador local no valor do parâmetro ComputerName, você deve iniciar o Windows PowerShell com a opção Executar como administrador.

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 a configuração de sessão usada para a sessão interativa.

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: https://schemas.microsoft.com/powershell.

A configuração de sessão de uma sessão está localizada no computador remoto. Se a configuração de sessão especificada não existir no computador remoto, o comando falhará.

O valor padrão é o valor da variável de preferência $PSSessionConfigurationName no computador local. Se essa variável de preferência não estiver definida, o padrão será Microsoft.PowerShell. Para obter mais informações, consulte about_Preference_Variables.

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

-ConnectionUri

Especifica um URI que define o ponto de extremidade de conexão para a sessão. O URI deve ser totalmente qualificado. O formato dessa cadeia de caracteres é o seguinte:

< >de Transporte :///<>ComputerName:>de Porta</<> ApplicationName

O valor padrão é o seguinte:

https://localhost:5985/WSMAN

Se você não especificar umConnectionURI, poderá usar os parâmetros UseSSL, ComputerName, Porte ApplicationName para especificar os valores ConnectionURI.

Os valores válidos para o segmento transporte 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 usando portas padrões: 80 para HTTP e 443 para HTTPS. Para usar as portas padrão para comunicação remota do Windows 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 Windows PowerShell impedirá o redirecionamento, a menos que você use o parâmetro AllowRedirection no comando.

Tipo:Uri
Aliases:URI, CU
Cargo:1
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-Credential

Especifica uma conta de usuário que tem permissão para executar essa ação. O padrão é o usuário atual.

Digite um nome de usuário, como , ou , 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.

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

-EnableNetworkAccess

Indica que esse cmdlet adiciona um token de segurança interativo a sessões de loopback. O token interativo permite executar comandos na sessão de loopback que obtêm dados de outros computadores. Por exemplo, você pode executar um comando na sessão que copia arquivos XML de um computador remoto para o computador local.

Uma sessão de loopback é uma PSSession que se origina e termina no mesmo computador. Para criar uma sessão de loopback, omita o parâmetro ComputerName ou defina seu valor como . (ponto), localhost ou o nome do computador local.

Por padrão, as sessões de loopback são criadas usando um token de rede, que pode não fornecer permissão suficiente para autenticar em computadores remotos.

O parâmetro EnableNetworkAccess só é eficaz em sessões de loopback. Se você usar EnableNetworkAccess ao criar uma sessão em um computador remoto, o comando terá êxito, mas o parâmetro será ignorado.

Você também pode permitir o acesso remoto em uma sessão de loopback usando o credSSP valor do parâmetro de Autenticação , que delega as credenciais de sessão para outros computadores.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

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

-Id

Especifica a ID de uma sessão existente. Enter-PSSession usa a sessão especificada para a sessão interativa.

Para localizar a ID de uma sessão, use o cmdlet Get-PSSession.

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

-InstanceId

Especifica a ID da instância de uma sessão existente. Enter-PSSession usa a sessão especificada para a sessão interativa.

A ID da instância é um GUID. Para localizar a ID da instância de uma sessão, use o cmdlet Get-PSSession. Você também pode usar os parâmetros Session, Nameou ID para especificar uma sessão existente. Ou você pode usar o parâmetro ComputerName para iniciar uma sessão temporária.

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

-Name

Especifica o nome amigável de uma sessão existente. Enter-PSSession usa a sessão especificada para a sessão interativa.

Se o nome especificado corresponder a mais de uma sessão, o comando falhará. Você também pode usar os parâmetros Session, InstanceIDou ID para especificar uma sessão existente. Ou você pode usar o parâmetro ComputerName para iniciar uma sessão temporária.

Para estabelecer um nome amigável para uma sessão, use o parâmetro Name do cmdlet New-PSSession.

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

-Port

Especifica a porta de rede no computador remoto que é usada para esse comando. 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 escutar nessa porta. Use os seguintes comandos para configurar o ouvinte:

1. winrm delete winrm/config/listener?Address=*+Transport=HTTP

2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="\<port-number\>"}

Não use o parâmetro Port, a menos que seja necessário. A configuração da porta 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 uma sessão do Windows PowerShell (PSSession) a ser usada para a sessão interativa. Esse parâmetro usa um objeto de sessão. Você também pode usar os parâmetrosde Nome , InstanceIDou de ID para especificar um de PSSession.

Insira uma variável que contenha um objeto de sessão ou um comando que cria ou obtém um objeto de sessão, como um comando New-PSSession ou Get-PSSession. Você também pode canalizar um objeto de sessão para Enter-PSSession. Você pode enviar apenas um PSSession usando esse parâmetro. Se você inserir uma variável que contenha mais de uma PSSession, o comando falhará.

Quando você usa Exit-PSSession ou a palavra-chave exit , a sessão interativa termina, mas o de PSSession que você criou permanece aberto e disponível para uso.

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

-SessionOption

Define 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, 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
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 estabelecer uma conexão com o computador remoto. Por padrão, o SSL não é usado.

WS-Management criptografa todo o conteúdo do Windows PowerShell transmitido pela rede. O parâmetro 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, mas o SSL não estiver disponível na porta usada para o comando, o comando falhará.

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

-VMGuid

Especifica a ID de uma máquina virtual.

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

-VMName

Especifica o nome de uma máquina virtual.

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

Entradas

System.String, System.Management.Automation.Runspaces.PSSession

Você pode canalizar um nome de computador, como uma cadeia de caracteres ou um objeto de sessão para este cmdlet.

Saídas

None

O cmdlet não retorna nenhuma saída.

Observações

  • Para se conectar a um computador remoto, você deve ser um membro do grupo Administradores no computador remoto.
  • No Windows Vista e versões posteriores do sistema operacional Windows, para iniciar uma sessão interativa no computador local, você deve iniciar o Windows PowerShell com a opção Executar como administrador.
  • Quando você usa Enter-PSSession, seu perfil de usuário no computador remoto é usado para a sessão interativa. Os comandos no perfil de usuário remoto, incluindo comandos para adicionar snap-ins do Windows PowerShell e alterar o prompt de comando, são executados antes que o prompt remoto seja exibido.
  • Enter-PSSession usa a configuração de cultura da interface do usuário no computador local para a sessão interativa. Para localizar a cultura da interface do usuário local, use a variável automática $UICulture.
  • Enter-PSSession requer os cmdlets Get-Command, Out-Default e Exit-PSSession. Se esses cmdlets não estiverem incluídos na configuração de sessão no computador remoto, os comandos Enter-PSSession falharão.
  • Ao contrário do Invoke-Command, que analisa e interpreta os comandos antes de enviar para o computador remoto, Enter-PSSession envia os comandos diretamente para o computador remoto sem interpretação.
  • Se a sessão que você deseja inserir estiver ocupada processando um comando, pode haver um atraso antes que o Windows PowerShell responda ao comando Enter-PSSession. Você será conectado assim que a sessão estiver disponível. Para cancelar o comando Enter-PSSession , pressione .