Enter-PSSession

Artigo
10/30/2009

Inicia uma sessão interativa com um computador remoto.

Sintaxe

Enter-PSSession [-ComputerName] <string> [-ApplicationName <string>] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-Port <int>] [-SessionOption <PSSessionOption>] [-UseSSL] [<CommonParameters>]

Enter-PSSession [[-Id] <int>] [<CommonParameters>]

Enter-PSSession [-InstanceId <Guid>] [<CommonParameters>]

Enter-PSSession [-Name <string>] [<CommonParameters>]

Enter-PSSession [[-Session] <PSSession>] [<CommonParameters>]

Enter-PSSession [[-ConnectionURI] <Uri>] [-AllowRedirection] [-Authentication {<Default> | <Basic> | <Negotiate> | <NegotiateWithImplicitCredential> | <Credssp> | <Digest> | <Kerberos>}] [-CertificateThumbprint <string>] [-ConfigurationName <string>] [-Credential <PSCredential>] [-SessionOption <PSSessionOption>] [<CommonParameters>]

Descrição

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 você estivesse digitando diretamente no computador remoto. Você pode ter somente uma sessão interativa de cada vez.

Normalmente, usa-se o parâmetro ComputerName para especificar o nome do computador remoto. Porém, você também pode usar uma sessão criada com o uso de New-PSSession para a sessão interativa.

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

Parâmetros

-AllowRedirection

Permite o redirecionamento desta 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 Windows PowerShell não redireciona conexões, mas você pode usar esse parâmetro para permitir que ele redirecione a conexão.

Permite o redirecionamento desta conexão para um URI 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 Windows PowerShell não redireciona conexões, mas você pode usar o parâmetro AllowRedirection para permitir que a conexão seja redirecionada.

Também é possível limitar o número de vezes que a conexão é redirecionada configurando a propriedade MaximumConnectionRedirectionCount da variável de preferência $PSSessionOption ou a propriedade MaximumConnectionRedirectionCount do valor do parâmetro SessionOption. O valor padrão é 5. Para obter mais informações, consulte a descrição do parâmetro SessionOption e consulte New-PSSessionOption.

Necessário?	false
Posição?	named
Valor padrão	False
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ApplicationName <string>

Especifica o segmento do 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 padrão é o valor da variável de preferência $PSSessionApplicationName no computador local. Se essa variável de preferência não for definida, o valor padrão será WSMAN. Esse valor é adequado 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 uma escuta que atenda à solicitação de conexão. O valor do parâmetro deve corresponder ao valor da propriedade URLPrefix de uma escuta no computador remoto.

Necessário?	false
Posição?	named
Valor padrão	WSMAN
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-Authentication <AuthenticationMechanism>

Especifica o mecanismo usado para autenticar as credenciais do usuário. Os valores válidos são "Default", "Basic", "Credssp", "Digest", "Kerberos", "Negotiate" e "NegotiateWithImplicitCredential". O valor padrão é "Default".

A autenticação CredSSP está disponível apenas no Windows Vista, no Windows Server 2008 e em versões mais recentes do Windows.

Para obter mais informações sobre os valores desse parâmetro, consulte a descrição da enumeração System.Management.Automation.Runspaces.AuthenticationMechanism na biblioteca MSDN, em https://go.microsoft.com/fwlink/?LinkId=144382.

Cuidado: a autenticação CredSSP (Credential Security Service Provider), na qual as credenciais do usuário são passadas para um computador remoto para serem autenticadas, foi projetada para comandos que exigem autenticação em mais de um recurso, como, por exemplo, o acesso a 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.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-CertificateThumbprint <string>

Especifica o certificado de chave pública digital (X509) de uma conta de usuário com permissão para executar essa ação. Digite a impressão digital do certificado.

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

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

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ComputerName <string>

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, um endereço IP ou um nome de domínio totalmente qualificado de um ou mais computadores remotos. 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. O computador também deve estar configurado para transporte HTTPS, ou o endereço IP do computador remoto deve ser incluído na lista TrustedHosts do WinRM no computador local. Para obter instruções sobre como adicionar um nome de computador à lista TrustedHosts, consulte "Como adicionar um computador à lista de hosts de confiança" em about_Remote_Troubleshooting.

Observação: no Windows Vista e em versões mais recentes do Windows, para incluir o computador local no valor do parâmetro ComputerName, é necessário iniciar o Windows PowerShell com a opção "Executar como administrador".

Necessário?	true
Posição?	1
Valor padrão
Aceitar entrada do pipeline?	true (ByValue, ByPropertyName)
Aceitar caracteres curinga?	false

-ConfigurationName <string>

Especifica a configuração de sessão usada para a sessão interativa.

Digite um nome de configuração ou o URI de recurso totalmente qualificado para uma configuração de sessão. Se você especificar só o nome de configuração, o seguinte URI de esquema será pré-demarcado: https://schemas.microsoft.com/powershell.

A configuração para 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 padrão é o valor da variável de preferência $PSSessionConfigurationName no computador local. Se essa variável de preferência não for definida, o padrão será Microsoft.PowerShell. Para obter mais informações, consulte about_Preference_Variables.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-ConnectionURI <Uri>

Especifica um URI (Uniform Resource Identifier) que define o ponto de extremidade da conexão para a sessão interativa. O URI deve ser totalmente qualificado.

O formato dessa cadeia de caracteres é o seguinte:

O valor padrão é:

https://localhost:80/WSMAN

Os valores válidos para o segmento Transport do URI são HTTP e HTTPS. Se você não especificar um ConnectionURI, poderá usar os parâmetros UseSSL, ComputerName, Port e ApplicationName para especificar os valores de URI.

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.

Necessário?	false
Posição?	2
Valor padrão
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-Credential <PSCredential>

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

Digite um nome de usuário, como "Usuário01", "Domínio01\Usuário01" ou "Usuário@Domínio.com.br", ou insira um objeto PSCredential, como aquele retornado pelo cmdlet Get-Credential.

Quando você digitar um nome de usuário, uma senha será solicitada.

Necessário?	false
Posição?	named
Valor padrão	Usuário atual
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-Id <int>

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.

Necessário?	false
Posição?	1
Valor padrão
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-InstanceId <Guid>

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

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

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-Name <string>

Especifica um 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, InstanceID ou 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.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	true (ByPropertyName)
Aceitar caracteres curinga?	false

-Port <int>

Especifica a porta de rede no computador remoto usada para esse comando. O padrão é a porta 80 (a porta HTTP).

Antes de usar uma porta alternativa, configure o ouvinte WinRM no computador remoto para ouvir 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="<número-da-porta>"}

Não use o parâmetro Port, a menos que seja necessário. A configuração de porta no comando se aplica a todos os computadores ou sessões em que o comando é executado. Uma configuração de porta alternativa pode impedir a execução do comando em todos os computadores.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Session <PSSession>

Especifica uma sessão do Windows PowerShell (PSSession) a ser usada para a sessão interativa. Esse parâmetro assume um objeto de sessão. Você também pode usar os parâmetros Name, InstanceID ou ID para especificar uma PSSession.

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

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

Necessário?	false
Posição?	1
Valor padrão
Aceitar entrada do pipeline?	true (ByValue, ByPropertyName)
Aceitar caracteres curinga?	true

-SessionOption <PSSessionOption>

Define opções avançadas para a sessão. Digite um objeto SessionOption que você cria usando o cmdlet New-PSSessionOption.

Os valores padrão para as opções são determinados pelo valor da variável de preferência $PSSessionOption, se esteja definida. Caso contrário, a sessão usará os padrões do sistema.

Para obter uma descrição das opções da sessão, inclusive os valores padrão, consulte New-PSSessionOption. Para obter informações sobre a variável de preferência $PSSessionOption, consulte about_Preference_Variables.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-UseSSL

Usa o protocolo SSL para estabelecer uma conexão com o computador remoto. Por padrão, SSL não é usado.

WS-Management criptografa todo o conteúdo do Windows PowerShell transmitido pela rede. UseSSL é uma proteção adicional que envia os dados por 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, este falhará.

Necessário?	false
Posição?	named
Valor padrão
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

<CommonParameters>

Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.

Entradas e saídas

O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.

Entradas

System.String ou System.Management.Automation.Runspaces.PSSession

Você pode canalizar um nome de computador (uma cadeia de caracteres) ou um objeto de sessão para Enter-PSSession.

Saídas

Nenhum

O cmdlet não retorna nenhuma saída.

Observações

-- Para conectar-se a um computador remoto, você deve ser membro do grupo Administradores no computador remoto.

-- No Windows Vista e em versões mais recentes do 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ê usar Enter-PSSession, seu perfil do usuário no computador remoto será usado para a sessão interativa. Os comandos no perfil do usuário remoto, inclusive comandos para adicionar snap-ins do Windows PowerShell e alterar o prompt de comando, são executados antes de o aviso remoto ser 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 forem incluídos na configuração de sessão no computador remoto, o comando Enter-PSSession falhará.

-- Ao contrário de Invoke-Command, que analisa e interpreta os comandos antes de enviá-los para o computador remoto, Enter-PSSession envia os comandos diretamente ao computador remoto sem interpretação.

Exemplo 1

C:\PS>Enter-PSSession

LocalHost\PS>

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

Os comandos que você insere são executados na nova sessão, e os resultados são retornados à sessão padrão como texto.

Exemplo 2

C:\PS>enter-pssession -computer Server01

Server01\PS> get-process powershell > C:\ps-test\process.txt

Server01\PS> exit-pssession
C:\PS>

C:\PS> 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

Descrição
-----------
Esse comando mostra como trabalhar em uma sessão interativa com um computador remoto.

O primeiro comando usa o cmdlet Enter-PSSession para iniciar uma sessão interativa com Server01, um computador remoto. Quando a sessão começa, o prompt de comando se altera para incluir o nome do computador.

O segundo comando obtém o processo do PowerShell e redireciona a saída para o arquivo Process.txt. O comando é enviado ao computador remoto e o arquivo é salvo no computador remoto. 

O terceiro comando usa a palavra-chave Exit para encerrar a sessão interativa e fechar a conexão.

O quarto comando confirma que o arquivo Process.txt está no computador remoto. Um comando Get-ChildItem ("dir") no computador local não pode localizar o arquivo.

Exemplo 3

C:\PS>$s = new-pssession -computername Server01

C:\PS> Enter-PSSession -session $s

Server01\PS>

Descrição
-----------
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

C:\PS>Enter-PSSession -computername Server01 -port 90 -credential domain01\user01

Server01\PS>

Descrição
-----------
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 Credential para especificar a conta de um usuário com permissão para se conectar ao computador remoto.

Exemplo 5

C:\PS>Enter-PSSession -computername Server01

Server01:\PS> Exit-PSSession

C:\PS>

Descrição
-----------
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.

Consulte também

Conceitos

about_PSSessions
about_Remote
New-PSSession
Get-PSSession
Exit-PSSession
Remove-PSSession
Invoke-Command

Compartilhar via