Partilhar via


New-PSSession

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

Sintaxe

New-PSSession
   [[-ComputerName] <String[]>]
   [-Credential <PSCredential>]
   [-Name <String[]>]
   [-EnableNetworkAccess]
   [-ConfigurationName <String>]
   [-Port <Int32>]
   [-UseSSL]
   [-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
   -Credential <PSCredential>
   [-Name <String[]>]
   [-ConfigurationName <String>]
   [-VMId] <Guid[]>
   [-ThrottleLimit <Int32>]
   [<CommonParameters>]
New-PSSession
   -Credential <PSCredential>
   [-Name <String[]>]
   [-ConfigurationName <String>]
   -VMName <String[]>
   [-ThrottleLimit <Int32>]
   [<CommonParameters>]
New-PSSession
   [[-Session] <PSSession[]>]
   [-Name <String[]>]
   [-EnableNetworkAccess]
   [-ThrottleLimit <Int32>]
   [<CommonParameters>]
New-PSSession
   [-Name <String[]>]
   [-ConfigurationName <String>]
   -ContainerId <String[]>
   [-RunAsAdministrator]
   [-ThrottleLimit <Int32>]
   [<CommonParameters>]

Description

O New-PSSession cmdlet cria uma sessão do PowerShell (PSSession) em um computador local ou remoto. Quando você cria uma PSSession, o 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 Invoke-Command cmdlet. Para usar o PSSession para interagir diretamente com um computador remoto, use o Enter-PSSession cmdlet. Para obter mais informações, consulte about_PSSessions.

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 PowerShell cria uma conexão temporária que é usada para o comando e, em seguida, é fechada.

Exemplos

Exemplo 1: Criar uma sessão no computador local

$s = New-PSSession

Este comando cria uma nova PSSession no computador local e salva a PSSession na $s variável.

Agora você pode usar este PSSession para executar comandos no computador local.

Exemplo 2: Criar uma sessão num computador remoto

$Server01 = New-PSSession -ComputerName Server01

Este comando cria uma nova PSSession no computador Server01 e salva-a $Server01 na variável.

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: Criar sessões em vários computadores

$s1, $s2, $s3 = New-PSSession -ComputerName Server01,Server02,Server03

Este 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: $s1, $s2, $s3. Ele atribui o Server01 PSSession a , o Server02 PSSession a $s2, e o Server03 PSSession a $s3.$s1

Quando você atribui vários objetos a uma série de variáveis, o PowerShell atribui cada objeto a uma variável na série, 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 do que objetos, as variáveis restantes estarão vazias ($null).

Exemplo 4: Criar uma sessão com uma porta especificada

New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12

Este comando cria uma nova PSSession no computador Server01 que se conecta à porta 8081 do servidor e usa o protocolo SSL. O novo PSSession usa uma configuração de sessão alternativa chamada E12.

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

Exemplo 5: Criar uma sessão com base em uma sessão existente

New-PSSession -Session $s -Credential Domain01\User01

Este comando cria uma PSSession com as mesmas propriedades de 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 $s variável. Ele usa as Domain1\Admin01 credenciais do usuário para concluir o comando.

Exemplo 6: Criar uma sessão com um escopo global em um domínio diferente

$global:s = New-PSSession -ComputerName Server1.Domain44.Corpnet.Fabrikam.com -Credential Domain01\Admin01

Este 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 os 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 para um escopo global. Nesse caso, a variável é convertida $s 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 de usuário, o nome completo do computador é especificado junto com as credenciais do usuário.

Exemplo 7: Criar sessões para muitos computadores

$rs = Get-Content C:\Test\Servers.txt | New-PSSession -ThrottleLimit 50

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

Você pode usar esse formato de comando quando os nomes dos computadores são armazenados em um banco de dados, planilha, arquivo de texto ou outro formato conversível em texto.

Exemplo 8: Criar uma sessão usando um URI

$s = New-PSSession -URI http://Server01:91/NewSession -Credential Domain01\User01

Este comando cria uma PSSession no computador Server01 e armazena-a $s na variável. 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

$s = New-PSSession -ComputerName (Get-Content Servers.txt) -Credential Domain01\Admin01 -ThrottleLimit 16
Invoke-Command -Session $s -ScriptBlock {Get-Process PowerShell} -AsJob

Esses 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 Servers.txt arquivo. Ele usa o New-PSSession cmdlet para criar o PSSession. O valor do parâmetro ComputerName é um comando que usa o Get-Content cmdlet para obter a lista de nomes de computador do Servers.txt arquivo.

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 $s variável.

O segundo comando usa o parâmetro AsJob do cmdlet para iniciar um trabalho em Invoke-Command segundo plano que executa um comando em cada um Get-Process PowerShell dos objetos PSSession no $s.

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

Exemplo 10: Criar uma sessão para um computador usando seu URI

New-PSSession -ConnectionURI https://management.exchangelabs.com/Management

Este comando cria um objeto PSSession que se conecta a um computador especificado por um URI em vez de um nome de computador.

Exemplo 11: Criar uma opção de sessão

$so = New-PSSessionOption -SkipCACheck
New-PSSession -ConnectionUri https://management.exchangelabs.com/Management -SessionOption $so -Credential Server01\Admin01

Este exemplo mostra como criar um objeto de opção de sessão e usar o parâmetro SessionOption .

O primeiro comando usa o New-PSSessionOption cmdlet para criar uma opção de sessão. Ele salva o objeto SessionOption resultante na $so variável.

O segundo comando usa a opção em uma nova sessão. O comando usa o New-PSSession cmdlet para criar uma nova sessão. O valor do parâmetro SessionOption é o objeto SessionOption na $so variável.

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 a 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 de sessão MaximumConnectionRedirectionCount . Use o parâmetro MaximumRedirection do New-PSSessionOption cmdlet ou defina a propriedade MaximumConnectionRedirectionCount da variável de preferência $PSSessionOption . O valor predefinido é 5.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 não estiver usando o parâmetro ConnectionURI no comando.

O valor padrão é o valor da variável de $PSSessionApplicationName preferência 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
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Authentication

Especifica o mecanismo usado para autenticar as credenciais do usuário. Os valores aceitáveis para este parâmetro são:

  • Default
  • Basic
  • Credssp
  • Digest
  • Kerberos
  • Negotiate
  • NegotiateWithImplicitCredential

O valor predefinido é Default.

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

Atenção

A autenticação CredSSP (Credential Security Support Provider), na qual as credenciais do usuário são passadas para um computador remoto para ser autenticado, foi projetada para comandos que exigem autenticação em mais de um recurso, como acessar um compartilhamento de rede remoto. Este mecanismo aumenta o risco de segurança da operação remota. Se o computador remoto estiver comprometido, as credenciais que são passadas para ele podem ser usadas para controlar a sessão de rede.

Tipo:AuthenticationMechanism
Valores aceites:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais: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 de cliente. Eles podem ser mapeados apenas para contas de usuário locais; eles não funcionam com contas de domínio.

Para obter um certificado, use o Get-Item comando ou Get-ChildItem na unidade do PowerShell Cert: .

Tipo:String
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ComputerName

Especifica uma matriz de nomes de computadores. Este 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. A predefiniçã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 localhostdo computador ou um ponto (.). Quando o computador está em um domínio diferente do usuário, o nome de domínio totalmente qualificado é necessário. 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 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" no about_Remote_Troubleshooting.

Para incluir o computador local no valor do parâmetro ComputerName , inicie o Windows PowerShell usando a opção Executar como administrador.

Tipo:String[]
Aliases:Cn
Position:0
Default value:None
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-ConfigurationName

Especifica a configuração de sessão usada para o novo PSSession.

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 do esquema será precedido: http://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 $PSSessionConfigurationName preferência 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
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais: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 desta 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 ConnectionURI, poderá usar os parâmetros UseSSL, ComputerName, Port e ApplicationName para especificar os valores 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 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 HTTPS.

Se o computador de destino redireciona a conexão para um URI diferente, o PowerShell impede o redirecionamento, a menos que você use o parâmetro AllowRedirection no comando.

Tipo:Uri[]
Aliases:URI, CU
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-ContainerId

Especifica uma matriz de IDs de contêineres. Este cmdlet inicia uma sessão interativa com cada um dos contêineres especificados. Use o docker ps comando para obter uma lista de IDs de contêiner. Para obter mais informações, consulte a ajuda para o comando docker ps .

Tipo:String[]
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-Credential

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

Digite um nome de usuário, como User01 or Domain01\User01, ou insira um objeto PSCredential gerado pelo Get-Credential cmdlet. Se escrever um nome de utilizador, ser-lhe-á pedido que introduza a palavra-passe.

As credenciais são armazenadas em um objeto PSCredential e a senha é armazenada como um SecureString.

Nota

Para obter mais informações sobre a proteção de dados do SecureString , consulte Quão seguro é o SecureString?.

Tipo:PSCredential
Position:Named
Default value:Current user
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-EnableNetworkAccess

Indica que esse cmdlet adiciona um token de segurança interativo às 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 dot (.), localhostou o nome do computador local.

Por padrão, esse cmdlet cria sessões de loopback usando um token de rede, que pode não fornecer permissão suficiente para autenticação em computadores remotos.

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

Você também pode habilitar o acesso remoto em uma sessão de loopback usando o CredSSP valor do parâmetro Authentication, que delega as credenciais da sessão a outros computadores.

Para proteger o computador contra acesso mal-intencionado, as sessões de loopback desconectadas que têm tokens interativos, que são aqueles criados usando o parâmetro EnableNetworkAccess , podem ser reconectadas somente do computador no qual a sessão foi criada. As sessões desconectadas que usam a autenticação CredSSP podem ser reconectadas de outros computadores. Para obter mais informações, veja Disconnect-PSSession.

Esse parâmetro foi introduzido no PowerShell 3.0.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Name

Especifica um nome amigável para o PSSession.

Você pode usar o nome para fazer referência ao PSSession quando usar outros cmdlets, como Get-PSSession e Enter-PSSession. Não é necessário que o nome seja exclusivo do computador ou da sessão atual.

Tipo:String[]
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Port

Especifica a porta de rede no computador remoto que é usada para essa conexão. 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 outra porta, você deve configurar o ouvinte do 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="\<port-number\>"}

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 nos quais o comando é executado. Uma configuração de porta alternativa pode impedir que o comando seja executado em todos os computadores.

Tipo:Int32
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-RunAsAdministrator

Indica que o PSSession é executado como administrador.

Tipo:SwitchParameter
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-Session

Especifica uma matriz de objetos PSSession que esse cmdlet usa como modelo para o novo PSSession. Este 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 crie ou obtenha os objetos PSSession , como um New-PSSession ou Get-PSSession comando.

Os objetos PSSession resultantes têm o mesmo nome de computador, nome do aplicativo, URI de conexão, porta, nome de configuração, limite de aceleração e valor SSL (Secure Sockets Layer) que os originais, mas eles têm um nome de exibição, ID e ID de instância (GUID) diferentes.

Tipo:PSSession[]
Position:0
Default value:None
Necessário:False
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-SessionOption

Especifica opções avançadas para a sessão. Introduza um objeto SessionOption, como o que cria ao utilizar o cmdlet New-PSSessionOption ou uma tabela hash em que 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 $PSSessionOption preferência, se ela estiver definida. Caso contrário, os valores padrão são estabelecidos pelas opções definidas na configuração da sessão.

Os valores de opção de sessão têm precedência sobre os $PSSessionOption valores padrão para sessões definidas na variável de preferência e na configuração da sessão. No entanto, eles não têm precedência sobre os 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 inclui os valores padrão, consulte New-PSSessionOption. Para obter informações sobre a variável de $PSSessionOption preferência, consulte about_Preference_Variables. Para obter mais informações sobre configurações de sessão, consulte about_Session_Configurations.

Tipo:PSSessionOption
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-ThrottleLimit

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 de 0 (zero), o valor padrão, 32, será usado.

O limite de aceleração aplica-se apenas ao comando atual, não à sessão ou ao computador.

Tipo:Int32
Position:Named
Default value:None
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-UseSSL

Indica que esse cmdlet usa o protocolo SSL para estabelecer uma conexão com o computador remoto. Por padrão, o SSL não é usado.

O WS-Management criptografa todo o conteúdo do PowerShell transmitido pela rede. O parâmetro UseSSL oferece uma proteção adicional que envia os dados através de 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
Position:Named
Default value:False
Necessário:False
Aceitar entrada de pipeline:False
Aceitar carateres universais:False

-VMId

Especifica uma matriz de IDs de máquina virtual. Este cmdlet inicia uma sessão interativa do PowerShell Direct com cada uma das máquinas virtuais especificadas. Para obter mais informações, consulte Automação e gerenciamento de máquinas virtuais usando o PowerShell.

Use Get-VM para ver as máquinas virtuais que estão disponíveis em seu host Hyper-V.

Tipo:Guid[]
Aliases:VMGuid
Position:0
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

-VMName

Especifica uma matriz de nomes de máquinas virtuais. Este cmdlet inicia uma sessão interativa do PowerShell Direct com cada uma das máquinas virtuais especificadas. Para obter mais informações, consulte Automação e gerenciamento de máquinas virtuais usando o PowerShell.

Use Get-VM para ver as máquinas virtuais que estão disponíveis em seu host Hyper-V.

Tipo:String[]
Position:Named
Default value:None
Necessário:True
Aceitar entrada de pipeline:True
Aceitar carateres universais:False

Entradas

String

Você pode canalizar uma cadeia de caracteres para este cmdlet.

System.URI

Você pode canalizar um URI para este cmdlet.

PSSession

Você pode canalizar um objeto de sessão para esse cmdlet.

Saídas

PSSession

Notas

O Windows PowerShell inclui os seguintes aliases para New-PSSession:

  • nsn

  • Este cmdlet usa a infraestrutura remota do PowerShell. Para usar esse cmdlet, o computador local e quaisquer computadores remotos devem ser configurados para comunicação remota do PowerShell. Para obter mais informações, consulte about_Remote_Requirements.

  • Para criar uma PSSession no computador local, inicie o PowerShell com a opção Executar como administrador .

  • Quando terminar o PSSession, use o Remove-PSSession cmdlet para excluir o PSSession e liberar seus recursos.