New-PSSession
Cria uma conexão persistente para um computador local ou remoto.
Syntax
New-PSSession
[[-ComputerName] <String[]>]
[-Credential <PSCredential>]
[-Name <String[]>]
[-EnableNetworkAccess]
[-Port <Int32>]
[-UseSSL]
[-ConfigurationName <String>]
[-ApplicationName <String>]
[-ThrottleLimit <Int32>]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[<CommonParameters>]New-PSSession
[-Credential <PSCredential>]
[-Name <String[]>]
[-EnableNetworkAccess]
[-ConfigurationName <String>]
[-ThrottleLimit <Int32>]
[-ConnectionUri] <Uri[]>
[-AllowRedirection]
[-SessionOption <PSSessionOption>]
[-Authentication <AuthenticationMechanism>]
[-CertificateThumbprint <String>]
[<CommonParameters>]New-PSSession
[[-Session] <PSSession[]>]
[-Name <String[]>]
[-EnableNetworkAccess]
[-ThrottleLimit <Int32>]
[<CommonParameters>]Description
O cmdlet New-PSSession cria uma sessão de Windows PowerShell (PSSession) em um computador local ou remoto. Quando você cria uma PSSession, Windows PowerShell estabelece uma conexão persistente com o computador remoto.
Use uma PSSession para executar vários comandos que compartilham dados, como uma função ou o valor de uma variável. Para executar comandos em uma PSSession, use o cmdlet Invoke-Command. Para usar a PSSession para interagir diretamente com um computador remoto, use o cmdlet Enter-PSSession. Para obter mais informações, consulte about_PSSessions (https://go.microsoft.com/fwlink/?LinkID=135181).
Você pode executar comandos em um computador remoto sem criar uma PSSession usando os parâmetros ComputerName de Enter-PSSession ou Invoke-Command. Quando você usa o parâmetro ComputerName, o Windows PowerShell cria uma conexão temporária que é usada para o comando e, em seguida, é fechada.
Exemplos
Exemplo 1: Create uma sessão no computador local
PS C:\> $s = New-PSSessionEsse comando cria uma nova PSSession no computador local e salva a PSSession na variável $s.
Agora você pode usar essa PSSession para executar comandos no computador local.
Exemplo 2: Create uma sessão em um computador remoto
PS C:\> $Server01 = New-PSSession -ComputerName Server01Esse comando cria uma nova PSSession no computador Server01 e o salva na variável $Server 01.
Ao criar vários objetos PSSession , atribua-os a variáveis com nomes úteis. Isso ajudará você a gerenciar os objetos PSSession em comandos subsequentes.
Exemplo 3: Create sessões em vários computadores
PS C:\> $s1, $s2, $s3 = New-PSSession -ComputerName Server01,Server02,Server03Esse comando cria três objetos PSSession , um em cada um dos computadores especificados pelo parâmetro ComputerName .
O comando usa o operador de atribuição (=) para atribuir os novos objetos PSSession a variáveis: $s 1, $s 2 $s 3. Ele atribui a PSSession server01 a $s 1, a PSSession Server02 a $s 2 e a PSSession Server03 para $s 3.
Quando você atribui vários objetos a uma série de variáveis, Windows PowerShell atribui cada objeto a uma variável na série, respectivamente. Se houver mais objetos que variáveis, todos os objetos restantes serão atribuídos à última variável. Se houver mais variáveis que objetos, as variáveis restantes ficarão vazias (nulas).
Exemplo 4: Create uma sessão com uma porta especificada
PS C:\> New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12Esse comando cria uma nova PSSession no computador Server01 que se conecta à porta do servidor 8081 e usa o protocolo SSL. A nova PSSession usa uma configuração de sessão alternativa chamada E12.
Antes de configurar a porta, você deve configurar o ouvinte WinRM no computador remoto para escutar na porta 8081. Para obter mais informações, consulte a descrição do parâmetro Port .
Exemplo 5: Create uma sessão com base em uma sessão existente
PS C:\> New-PSSession -Session $s -Credential Domain01\User01Esse comando cria uma PSSession com as mesmas propriedades que uma PSSession existente. Você pode usar esse formato de comando quando os recursos de uma PSSession existente estiverem esgotados e uma nova PSSession for necessária para descarregar parte da demanda.
O comando usa o parâmetro Session de New-PSSession para especificar a PSSession salva na variável $s. Ele usa as credenciais do usuário Domain1\Admin01 para concluir o comando.
Exemplo 6: Create uma sessão com um escopo global em um domínio diferente
PS C:\> $global:s = New-PSSession -ComputerName Server1.Domain44.Corpnet.Fabrikam.com -Credential Domain01\Admin01Este exemplo mostra como criar uma PSSession com um escopo global em um computador em um domínio diferente.
Por padrão, os objetos PSSession criados na linha de comando são criados com escopo local e objetos PSSession criados em um script têm escopo de script.
Para criar uma PSSession com escopo global, crie uma nova PSSession e armazene a PSSession em uma variável que é convertida em um escopo global. Nesse caso, a variável $s é convertida em um escopo global.
O comando usa o parâmetro ComputerName para especificar o computador remoto. Como o computador está em um domínio diferente da conta de usuário, o nome completo do computador é especificado junto com as credenciais do usuário.
Exemplo 7: sessões de Create para muitos computadores
PS C:\> $rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50Esse comando cria uma PSSession em cada um dos 200 computadores listados no arquivo Servers.txt e armazena a PSSession resultante na variável $rs. Os objetos PSSession têm um limite de limitação de 50.
Você pode usar esse formato de comando quando os nomes dos computadores são armazenados em um banco de dados, arquivo de texto, planilha ou outro formato convertível em texto.
Exemplo 8: Create uma sessão usando um URI
PS C:\> $s = New-PSSession -URI http://Server01:91/NewSession -Credential Domain01\User01Esse comando cria uma PSSession no computador Server01 e a armazena na variável $s. Ele usa o parâmetro URI para especificar o protocolo de transporte, o computador remoto, a porta e uma configuração de sessão alternativa. Ele também usa o parâmetro Credential para especificar uma conta de usuário que tenha permissão para criar uma sessão no computador remoto.
Exemplo 9: executar um trabalho em segundo plano em um conjunto de sessões
PS C:\> $s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential Domain01\Admin01 -ThrottleLimit 16
PS C:\> Invoke-Command -Session $s -ScriptBlock {Get-Process PowerShell} -AsJobEsses comandos criam um conjunto de objetos PSSession e, em seguida, executam um trabalho em segundo plano em cada um dos objetos PSSession .
O primeiro comando cria uma nova PSSession em cada um dos computadores listados no arquivo Servers.txt. Ele usa o cmdlet New-PSSession para criar a PSSession. O valor do parâmetro ComputerName é um comando que usa o cmdlet Get-Content para obter a lista de nomes de computador do arquivo Servers.txt.
O comando usa o parâmetro Credential para criar os objetos PSSession que têm a permissão de um administrador de domínio e usa o parâmetro ThrottleLimit para limitar o comando a 16 conexões simultâneas. O comando salva os objetos PSSession na variável $s.
O segundo comando usa o parâmetro AsJob do cmdlet Invoke-Command para iniciar um trabalho em segundo plano que executa um comando em cada um Get-Process PowerShell dos objetos PSSession no $s.
Para obter mais informações sobre Windows PowerShell trabalhos em segundo plano, consulte about_Jobs e about_Remote_Jobs.
Exemplo 10: Create uma sessão para um computador usando seu URI
PS C:\> New-PSSession -ConnectionURI https://management.exchangelabs.com/ManagementEsse comando cria objetos PSSession que se conectam a um computador especificado por um URI em vez de um nome de computador.
Exemplo 11: Create uma opção de sessão
PS C:\> $so = New-PSSessionOption -SkipCACheck
PS C:\> New-PSSession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -Credential Server01\Admin01Este exemplo mostra como criar um objeto de opção de sessão e usar o parâmetro SessionOption .
O primeiro comando usa o cmdlet New-PSSessionOption para criar uma opção de sessão. Ele salva o objeto SessionOption resultante na variável $so.
O segundo comando usa a opção em uma nova sessão. O comando usa o cmdlet New-PSSession para criar uma nova sessão. O valor do parâmetro SessionOption é o objeto SessionOption na variável $so.
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, Windows PowerShell não redireciona conexões, mas você pode usar esse parâmetro para habilitá-lo para redirecionar a conexão.
É possível também limitar o número de vezes que a conexão é redirecionada alterando o valor da opção de sessão MaximumConnectionRedirectionCount. 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.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ApplicationName
Especifica o segmento de nome de aplicativo do URI de conexão. Use esse parâmetro para especificar o nome do aplicativo quando 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 esta variável de preferência não estiver definida, o valor padrão é 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 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.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Authentication
Especifica o mecanismo usado para autenticar as credenciais do usuário. Os valores aceitáveis para esse parâmetro são:
- Default
- Basic
- Credssp
- Digest
- Kerberos
- Negotiate
- NegotiateWithImplicitCredential
O valor padrão é Default.
Para obter mais informações sobre os valores desse parâmetro, consulte AutenticaçãoMecanismo Enumeração na biblioteca MSDN.
Cuidado: a autenticação credSSP (Provedor de Suporte de 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 que são passadas a ele podem ser usadas para controlar a sessão de rede.
| Type: | AuthenticationMechanism |
| Accepted values: | Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-CertificateThumbprint
Especifica o certificado de chave pública digital (X509) de uma conta de usuário com permissão para executar essa ação. Insira a impressão digital do certificado.
Os certificados são utilizados na autenticação baseada em certificado do cliente. Eles podem ser mapeados somente 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 Windows PowerShell Cert: drive.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ComputerName
Especifica uma matriz de nomes de computadores. Esse cmdlet cria uma conexão persistente (PSSession) com o computador especificado. Se você inserir vários nomes de computador, New-PSSession criará vários objetos PSSession , um para cada 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. Para especificar o computador local, digite o nome do computador, localhost ou um ponto (.). Quando o computador está em um domínio diferente do usuário, é necessário o nome de domínio totalmente qualificado. Você também pode canalizar um nome de computador, entre aspas, para New-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 o 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 hosts confiáveis" em about_Remote_Troubleshooting (https://go.microsoft.com/fwlink/?LinkID=135188).
Para incluir o computador local no valor do parâmetro ComputerName, comece Windows PowerShell usando a opção Executar como administrador.
| Type: | String[] |
| Aliases: | Cn |
| Position: | 0 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-ConfigurationName
Especifica a configuração de sessão usada para a nova PSSession.
Insira um nome de configuração ou o URI do 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á anexado: https://schemas.microsoft.com/PowerShell.
A configuração da sessã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 valor padrão é o valor da variável de preferência $PSSessionConfigurationName no computador local. Se esta variável de preferência não for definida, o padrão é Microsoft. Para obter mais informações, consulte about_Preference_Variables.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | 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:
<Transporte>://<ComputerName>:<Port>/<ApplicationName>
O valor padrão é o seguinte:
https://localhost:5985/WSMAN
Se não especificar um ConnectionURI, poderá usar os parâmetros UseSSL, ComputerName, Port e ApplicationName para especificar os valores do 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 transporte, mas não especificar uma porta, a sessão será criada com portas padrões: 80 para HTTP e 443 para HTTPS. Para utilizar 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.
| Type: | Uri[] |
| Aliases: | URI, CU |
| Position: | 0 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Credential
Especifica uma conta de usuário que tem permissão para executar esta ação. O padrão é o usuário atual.
Digite um nome de usuário, como User01, Domain01\User01 ou 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.
| Type: | PSCredential |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | 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 no 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 dot (.), localhost ou o nome do computador local.
Por padrão, esse cmdlet cria sessões de loopback usando um token de rede, o 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 habilitar o acesso remoto em uma sessão de loopback usando o valor CredSSP do parâmetro Authentication , que delega as credenciais de sessão para outros computadores.
Para proteger o computador contra acesso mal-intencionado, as sessões de loopback desconectadas que têm tokens interativos, que são criados usando o parâmetro EnableNetworkAccess , só podem ser reconectadas do computador no qual a sessão foi criada. Sessões desconectadas que usam a autenticação CredSSP podem ser reconectadas por meio de outros computadores. Para obter mais informações, consulte Disconnect-PSSession.
Este parâmetro foi introduzido no Windows PowerShell 3.0.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Name
Especifica um nome amigável para a PSSession.
Você pode usar o nome para se referir à PSSession ao usar outros cmdlets, como Get-PSSession e Enter-PSSession. Não é necessário que o nome do computador ou da sessão atual seja exclusivo.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Port
Especifica a porta de rede no computador remoto que é usada para esta conexão. Para se conectar a um computador remoto, este deve estar escutando na porta usada pela conexão. As portas padrão são 5985, que é a porta WinRM para HTTP e 5986, que é a porta WinRM para HTTPS.
Antes de usar outra porta, você deve configurar o ouvinte 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 em que o comando for executado. Uma configuração de porta alternativa pode impedir que o comando seja executado em todos os computadores.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Session
Especifica uma matriz de objetos PSSession que esse cmdlet usa como modelo para a nova PSSession. Esse parâmetro cria novos objetos PSSession que têm as mesmas propriedades que os objetos PSSession especificados.
Insira uma variável que contenha os objetos PSSession ou um comando que cria ou obtém os objetos PSSession , como um comando New-PSSession ou Get-PSSession.
Os objetos PSSession resultantes têm o mesmo nome do computador, nome do aplicativo, URI de conexão, porta, nome de configuração, limite de limitação e valor SSL (Secure Sockets Layer) que os originais, mas eles têm um nome de exibição, ID e GUID (ID de instância) diferentes.
| Type: | PSSession[] |
| Position: | 0 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | 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 das opções são determinados pelo valor da variável de preferência $PSSessionOption, se 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 da sessão têm precedência sobre os valores padrão de sessões definidos 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.
| Type: | PSSessionOption |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ThrottleLimit
Especifica o número máximo de conexões simultâneas que podem ser estabelecidas para executar o comando. Se você omitir esse parâmetro ou digitar o valor 0 (zero), o valor padrão, 32, será usado.
O limite de aceleração aplica-se somente ao comando atual e não à sessão ou ao computador.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-UseSSL
Indica que esse cmdlet usa o protocolo SSL para estabelecer uma conexão com o computador remoto. Por padrão, SSL não é usado.
O WS-Management criptografa todo o conteúdo do Windows PowerShell transmitido pela rede. O parâmetro UseSSL oferece 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á.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Entradas
System.String, System.URI, System.Management.Automation.Runspaces.PSSession
Você pode canalizar uma cadeia de caracteres, um URI ou um objeto de sessão para esse cmdlet.
Saídas
Observações
Esse cmdlet usa a infraestrutura de comunicação remota do Windows PowerShell. Para usar esse cmdlet, o computador local e quaisquer computadores remotos devem ser configurados para comunicação remota do Windows PowerShell. Para obter mais informações, consulte about_Remote_Requirements.
Para criar uma PSSession no computador local, comece Windows PowerShell com a opção Executar como administrador.
Quando terminar de usar o PSSession, use o cmdlet Remove-PSSession para excluir a PSSession e liberar seus recursos.