Compartilhar via

New-PSSession

  • Artigo

Cria uma conexão persistente com um computador local ou remoto.

Sintaxe

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

New-PSSession [[-Session] <PSSession[]>] [-Name <string[]>] [-ThrottleLimit <int>] [<CommonParameters>]

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

Descrição

O cmdlet New-PSSession cria uma sessão do Windows PowerShell (PSSession) em um computador local ou remoto. Quando você cria um PSSession, o Windows PowerShell estabelece uma conexão persistente com o computador remoto.

Use um PSSession para executar vários comandos que compartilham dados, como uma função ou o valor de uma variável. Para executar comandos em um PSSession, use o cmdlet Invoke-Command. Para usar a PSSession a fim de interagir diretamente com um computador remoto, use o cmdlet Enter-PSSession. Para obter mais informações, consulte about_PSSessions.

Você pode executar comandos em um computador remoto sem criar um PSSession usando os parâmetros ComputerName de Enter-PSSession ou Invoke-Command. Quando você usar o parâmetro ComputerName, o Windows PowerShell criará uma conexão temporária que será usada para a sessão interativa ou para um único comando e depois será fechada.

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 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

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

Default

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[]>

Cria uma conexão especificada (PSSession) com o computador especificado.. Se você inserir vários nomes de computadores, New-PSSession criará várias PSSessions, 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 e o usuário estão em domínios diferentes, é necessário usar 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. 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?

false

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 nova PSSession.

Digite um nome de configuração ou o URI (Uniform Resource Identifier) 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. O URI deve ser totalmente qualificado.

O formato dessa cadeia de caracteres é o seguinte:

<Transport>://<ComputerName>:<Port>/<ApplicationName>

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?

true

Posição?

1

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

Aceitar entrada do pipeline?

true (ByPropertyName)

Aceitar caracteres curinga?

false

-Name <string[]>

Especifica um nome amigável para a PSSession.

Você pode usar o nome para fazer referência à PSSession quando usar outros cmdlets, como Get-PSSession e Enter-PSSession. O nome não precisa ser exclusivo no computador ou na sessão atual.

Necessário?

false

Posição?

named

Valor padrão

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-Port <int>

Especifica a porta de rede no computador remoto que é 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=&quot;&lt;número-da-porta&gt;&quot;}

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 e 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

80

Aceitar entrada do pipeline?

false

Aceitar caracteres curinga?

false

-Session <PSSession[]>

Usa a PSSession especificada como um modelo para a nova PSSession. Esse parâmetro cria novas PSSessions com as mesmas propriedades das PSSessions especificadas.

Insira uma variável que contenha as PSSessions ou um comando que crie ou obtenha as PSSessions, como o comando New-PSSession ou Get-PSSession.

As PSSessions resultantes têm nome de computador, nome de aplicativo, URI de conexão, porta, nome de configuração, limite, tempo limite e valor SSL iguais às originais, mas o nome de exibição, a ID e a ID da instância (GUID) são diferentes.

Necessário?

false

Posição?

1

Valor padrão

Aceitar entrada do pipeline?

true (ByValue, ByPropertyName)

Aceitar caracteres curinga?

false

-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

-ThrottleLimit <int>

Especifica o número máximo de conexões simultâneas que podem ser estabelecidas para executar esse comando. Se você omitir esse parâmetro ou inserir um valor igual a 0 (zero), será usado o valor padrão, 32.

O limite se aplica somente ao comando atual, não à sessão ou ao computador.

Necessário?

false

Posição?

named

Valor padrão

32

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, System.URI, System.Management.Automation.Runspaces.PSSession

Você pode canalizar um objeto ComputerName (string), ConnectionURI (URI) ou Session (PSSession) para New-PSSession.

Saídas

System.Management.Automation.Runspaces.PSSession

Observações

Esse cmdlet usa a infraestrutura remota do Windows PowerShell. Para usar esse cmdlet, o computador local e qualquer computador remoto deve ser configurado para a comunicação remota do Windows PowerShell. Para obter mais informações, consulte about_Remote_Requirements.

No Windows Vista e em versões mais recentes do Windows, para criar uma PSSession no computador local, você precisa iniciar o Windows PowerShell com a opção "Executar como administrador".

Quando tiver terminado de usar a PSSession, use o cmdlet Remove-PSSession para excluir a PSSession e liberar seus recursos.

Exemplo 1

C:\PS>$s = new-pssession

Descrição
-----------
Esse comando cria uma nova PSSession no computador local e salva-a na variável $s.

Você agora pode usar essa PSSession para executar comandos no computador local.

Exemplo 2

C:\PS>$Server01 = new-pssession -ComputerName Server01

Descrição
-----------
Esse comando cria uma nova PSSession no computador Server01 e salva-a na variável $Server01. 

Ao criar várias PSSessions, atribua-as a variáveis com nomes úteis. Isso ajudará você a gerenciar as PSSessions em comandos subsequentes.

Exemplo 3

C:\PS>$s1, $s2, $s3 = new-session -computername server1,server2,server3

Descrição
-----------
Esse comando cria três novas PSSessions, uma em cada um dos computadores especificados pelo parâmetro ComputerName. 

O comando usa o operador de atribuição (=) para atribuir as novas PSSessions a uma matriz de variáveis: $s1, $s2, $s3. Ele atribui a PSSession de Server01 para $s1, a PSSession de Server02 para $s2 e a PSSession de Server03 para $s3.

Quando você atribui vários objetos a uma matriz de variáveis, o Windows PowerShell atribui cada objeto a uma variável na matriz respectivamente. Se houver mais objetos do 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 (nulo).

Exemplo 4

C:\PS>new-pssession -computername Server01 -port 8081 -useSSL -ConfigurationName E12

Descrição
-----------
Esse comando cria uma nova PSSession no computador Server01 que se conecta à porta 8081 do servidor e usa o protocolo SSL. A nova PSSession usa uma configuração de sessão alternativa chamada "E12".

Antes de definir a porta, você deve configurar a escuta WinRM no computador remoto para escutar na porta 8081. Para obter mais informações, consulte a descrição do parâmetro Port.

Exemplo 5

C:\PS>new-pssession -session $s -credential domain01\user01

Descrição
-----------
Esse comando cria uma nova PSSession com as mesmas propriedades da 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 atender a 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

C:\PS>$global:s = new-pssession -computername server1.domain44.corpnet.fabrikam.com -credential domain01\admin01

Descrição
-----------
Esse exemplo mostra como criar uma PSSession com um escopo global em um computador de um domínio diferente.

Por padrão, PSSessions criadas na linha de comando têm escopo local, enquanto PSSessions criadas em um script têm escopo de script. 

Para criar uma PSSession com escopo global, crie uma nova PSSession e armazene-a em uma variável que seja convertida para um escopo global. Nesse caso, a variável $s é convertida para 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 do usuário, o nome completo do computador é especificado juntamente com as credenciais do usuário.

Exemplo 7

C:\PS>$rs = get-content c:\test\servers.txt | new-PSsession -throttleLimit 50

Descrição
-----------
Esse comando cria uma PSSession em cada um dos 200 computadores listados no arquivo Servers.txt e armazena a PSSession resultante na variável $rs. As PSSessions têm um limite de aceleração de 50.

Você poderá usar esse formato de comando quando os nomes de computadores estiverem armazenados em um banco de dados, uma planilha, um arquivo de texto ou outro formato que possa ser convertido em texto.

Exemplo 8

C:\PS>$s = new-PSSession -URI http://Server01:91/NewSession -credential domain01\user01

Descrição
-----------
Esse 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 com permissão para criar uma sessão no computador remoto.

Exemplo 9

C:\PS>$s = new-PSSession -computername (import-csv servers.csv) -credential domain01\admin01 -throttlelimit 16

C:\PS> invoke-command -session $s -scriptblock {get-process powershell} -AsJob

Descrição
-----------
Esses comandos criam um conjunto de PSSessions e executam um trabalho em segundo plano em cada uma das PSSessions. 

O primeiro comando cria uma nova PSSession em cada um dos computadores listados no arquivo Servers.csv. Ele usa o cmdlet New-PSSession para criar a PSSession. O valor do parâmetro ComputerName é um comando que usa o cmdlet Import-Csv para importar o arquivo Servers.csv e ler seu conteúdo. 

O comando usa o parâmetro Credential para criar as PSSessions com 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 as PSSessions na variável $s.
   
O segundo comando usa o parâmetro AsJob de Invoke-Command para iniciar um trabalho em segundo plano que executa um comando "Get-Process PowerShell" em cada uma das PSSessions em $s. 

Para obter mais informações sobre trabalhos em segundo plano, consulte about_Jobs e about_Remote_Jobs.

Exemplo 10

C:\PS>new-PSSession -ConnectionURI https://management.exchangelabs.com/Management

Descrição
-----------
Esse comando cria uma nova PSSession que se conecta a um computador especificado por um URI, em vez de um nome de computador.

Exemplo 11

C:\PS>$so = New-WSManSessionOption -SkipCACheck

PS C:\> new-pssession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -credential server01\admin01

Descrição
-----------
Esse exemplo mostra como criar e usar um parâmetro SessionOption. 

O primeiro comando usa o cmdlet New-WSManSessionOption para criar uma opção de sessão. Ele salva o objeto SessionOption resultante no parâmetro $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.

Consulte também

Conceitos

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