Compartilhar via

New-PSSession

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

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>]
New-PSSession
   [-Name <String[]>]
   [-UseWindowsPowerShell]
   [<CommonParameters>]
New-PSSession
   [-Name <String[]>]
   [-Port <Int32>]
   [-HostName] <String[]>
   [-UserName <String>]
   [-KeyFilePath <String>]
   [-Subsystem <String>]
   [-ConnectingTimeout <Int32>]
   [-SSHTransport]
   [-Options <Hashtable>]
   [<CommonParameters>]
New-PSSession
   [-Name <String[]>]
   -SSHConnection <Hashtable[]>
   [<CommonParameters>]

Description

O cmdlet New-PSSession cria uma sessão do PowerShell (PSSession) em um computador local ou remoto. Quando você cria um 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 cmdlet Invoke-Command. Para usar o PSSession para 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 uma de PSSession com 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.

A partir do PowerShell 6.0, você pode usar o Secure Shell (SSH) para estabelecer uma conexão e criar uma sessão em um computador remoto, se o SSH estiver disponível no computador local e o computador remoto estiver configurado com um ponto de extremidade SSH do PowerShell. O benefício de uma sessão remota do PowerShell baseada em SSH é que ela pode funcionar em várias plataformas (Windows, Linux, macOS). Para sessões baseadas em SSH, você usa o parâmetro HostName ou SSHConnection definido para especificar o computador remoto e as informações de conexão relevantes. Para obter mais informações sobre como configurar a comunicação remota do SSH do PowerShell, consulte comunicação remota do PowerShell sobre o SSH.

Nota

Ao usar a comunicação remota do WSMan de um cliente Linux ou macOS com um ponto de extremidade HTTPS em que o certificado do servidor não é confiável (por exemplo, um certificado autoassinado). Você deve fornecer um PSSessionOption que inclua os valores SkipCACheck e SkipCNCheck definidos como $true para estabelecer a conexão com êxito. Faça isso somente se você estiver em um ambiente em que possa ter certeza do certificado do servidor e da conexão de rede com o sistema de destino.

Exemplos

Exemplo 1: Criar uma sessão no computador local

$s = New-PSSession

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

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

Exemplo 2: criar uma sessão em um computador remoto

$Server01 = New-PSSession -ComputerName Server01

Esse comando cria um novo PSSession no computador Server01 e o salva na variável $Server01.

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

Esse 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 de PSSession a variáveis: $s1, $s2, $s3. Ele atribui o de PSSession do Server01 a $s1, a de PSSession do Server02 a $s2e a de PSSession do Server03 a $s3.

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

Esse comando cria um novo PSSession no computador Server01 que se conecta à porta do servidor 8081 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

Esse comando cria um PSSession com as mesmas propriedades de um PSSessionexistente. Você pode usar esse formato de comando quando os recursos de um de PSSession existentes estiverem esgotados e um novo de PSSession for necessário para descarregar parte da demanda.

O comando usa o parâmetro sessão de New-PSSession para especificar o de PSSession salvo na variável $s. Ele usa as credenciais do usuário Domain1\Admin01 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 um PSSession com um escopo global em um computador em um domínio diferente.

Por padrão, 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 de PSSession com escopo global, crie uma nova de PSSession e armazene a de 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: Criar sessões para muitos computadores

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

Esse comando cria um PSSession em cada um dos 200 computadores listados no arquivo Servers.txt e armazena o PSSession resultante na variável $rs. Os objetos PSSession têm um limite 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 de texto.

Exemplo 8: Criar uma sessão usando um URI

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

Esse comando cria um PSSession no computador Server01 e o 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

$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 de de PSSession.

O primeiro comando cria um novo PSSession em cada um dos computadores listados no arquivo Servers.txt. Ele usa o cmdlet New-PSSession para criar o 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 o 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 Get-Process PowerShell em cada um dos objetos de PSSession em $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

Esse comando cria um PSSession objetos que se conectam 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 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.

Exemplo 12: Criar uma sessão usando SSH

New-PSSession -HostName UserA@LinuxServer01

Este exemplo mostra como criar uma nova de PSSession usando o SSH (Secure Shell). Se o SSH estiver configurado no computador remoto para solicitar senhas, você receberá um prompt de senha. Caso contrário, você precisará usar a autenticação de usuário baseada em chave SSH.

Exemplo 13: Criar uma sessão usando SSH e especificar a porta e a chave de autenticação do usuário

New-PSSession -HostName UserA@LinuxServer01:22 -KeyFilePath c:\<path>\userAKey_rsa

Este exemplo mostra como criar um de PSSession usando o Secure Shell (SSH). Ele usa o parâmetro Port para especificar a porta a ser usada e o parâmetro KeyFilePath para especificar uma chave RSA usada para identificar e autenticar o usuário no computador remoto.

Exemplo 14: Criar várias sessões usando SSH

$sshConnections = @(
    @{
          HostName    = 'WinServer1'
          UserName    = 'domain\userA'
          KeyFilePath = 'c:\users\UserA\id_rsa'
    }
    @{
        HostName    = 'UserB@LinuxServer5'
        KeyFilePath = 'c:\UserB\<path>\id_rsa'
    }
)
New-PSSession -SSHConnection $sshConnections

Este exemplo mostra como criar várias sessões usando o Secure Shell (SSH) e o conjunto de parâmetros SSHConnection. O parâmetro SSHConnection usa uma matriz de tabelas de hash que contêm informações de conexão para cada sessão. Observe que este exemplo requer que os computadores remotos de destino tenham o SSH configurado para dar suporte à autenticação de usuário baseada em chave.

Exemplo 15: Criar uma nova sessão usando opções de SSH

$options = @{
    Port=22
    User = 'UserB'
    Host = 'LinuxServer5'
}
New-PSSession -KeyFilePath '/Users/UserB/id_rsa' -Options $options

Este exemplo mostra como criar uma nova sessão baseada em SSH em um computador remoto baseado em Linux usando opções SSH. O parâmetro Options usa um hashtable de valores que são passados como opções para o comando ssh subjacente a conexão estabelecida com o sistema remoto.

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 para 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 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:False
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:

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

O valor padrão é Default.

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

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 na unidade de Cert: do PowerShell.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 de de 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, localhostou 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 redirecionar 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 host confiável" em 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
Cargo:0
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-ConfigurationName

Especifica a configuração de sessão usada para o novo de 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 de esquema será acrescentado: http://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

-ConnectingTimeout

Especifica a quantidade de tempo em milissegundos permitida para que a conexão SSH inicial seja concluída. Se a conexão não for concluída dentro do tempo especificado, um erro será retornado.

Esse parâmetro foi introduzido no PowerShell 7.2

Tipo:Int32
Cargo:Named
Valor padrão:unlimited
Obrigatório:False
Aceitar a entrada de pipeline:False
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:

<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, 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 com portas padrões: 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 para HTTPS.

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

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

-ContainerId

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

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

-Credential

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

Digite um nome de usuário, como User01 ou Domain01\User01, ou insira um objeto PSCredential gerado pelo cmdlet Get-Credential. Se você digitar um nome de usuário, será solicitado que você insira a senha.

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

Nota

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

Tipo:PSCredential
Cargo:Named
Valor padrão:Current user
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 (.), 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 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 aqueles criados usando o parâmetro EnableNetworkAccess, podem ser reconectadas somente do computador no qual a sessão foi criada. Sessões desconectadas que usam a autenticação CredSSP podem ser reconectadas de outros computadores. Para obter mais informações, consulte Disconnect-PSSession.

Esse parâmetro foi introduzido no PowerShell 3.0.

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

-HostName

Especifica uma matriz de nomes de computador para uma conexão baseada em SSH (Secure Shell). Isso é semelhante ao parâmetro ComputerName exceto que a conexão com o computador remoto é feita usando SSH em vez do Windows WinRM.

Esse parâmetro foi introduzido no PowerShell 6.0.

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

-KeyFilePath

Especifica um caminho de arquivo de chave usado pelo Secure Shell (SSH) para autenticar um usuário em um computador remoto.

O SSH permite que a autenticação do usuário seja executada por meio de chaves privadas/públicas como uma alternativa à autenticação básica de senha. Se o computador remoto estiver configurado para autenticação de chave, esse parâmetro poderá ser usado para fornecer a chave que identifica o usuário.

Esse parâmetro foi introduzido no PowerShell 6.0.

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

-Name

Especifica um nome amigável para o PSSession.

Você pode usar o nome para se referir à PSSession ao usar outros cmdlets, como Get-PSSession e Enter-PSSession. O nome não é necessário para ser exclusivo para o computador ou a sessão atual.

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

-Options

Especifica um hashtable de opções de SSH usadas ao se conectar a uma sessão remota baseada em SSH. As opções possíveis são quaisquer valores compatíveis com a versão baseada em Unix do comando ssh do.

Todos os valores passados explicitamente por parâmetros têm precedência sobre os valores passados nas opções hashtable. Por exemplo, o uso do parâmetro Port substitui qualquer par chave-valor Port passado no hashtable opções de.

Tipo:Hashtable
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 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

-RunAsAdministrator

Indica que o PSSession é executado como administrador.

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

-Session

Especifica uma matriz de objetos PSSession que esse cmdlet usa como modelo para o novo 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 de 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 diferente, ID e GUID (ID de instância).

Tipo:PSSession[]
Cargo:0
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga: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 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 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.

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

-SSHConnection

Esse parâmetro usa uma matriz de hashtables em que cada hashtable contém um ou mais parâmetros de conexão necessários para estabelecer uma conexão SSH (HostName, Port, UserName, KeyFilePath).

Os parâmetros de conexão hashhable são os mesmos definidos para o conjunto de parâmetros SSHHost.

O parâmetro SSHConnection é útil para criar várias sessões em que cada sessão requer informações de conexão diferentes.

Esse parâmetro foi introduzido no PowerShell 6.0.

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

-SSHTransport

Indica que a conexão remota é estabelecida usando o Secure Shell (SSH).

Por padrão, o PowerShell usa o Windows WinRM para se conectar a um computador remoto. Essa opção força o PowerShell a usar o conjunto de parâmetros HostName para estabelecer uma conexão remota baseada em SSH.

Esse parâmetro foi introduzido no PowerShell 6.0.

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

-Subsystem

Especifica o subsistema SSH usado para o novo PSSession.

Isso especifica o subsistema a ser usado no destino, conforme definido em sshd_config. O subsistema inicia uma versão específica do PowerShell com parâmetros predefinidos. Se o subsistema especificado não existir no computador remoto, o comando falhará.

Se esse parâmetro não for usado, o padrão será o subsistema powershell.

Tipo:String
Cargo:Named
Valor padrão:powershell
Obrigatório:False
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga: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 limitação se aplica somente ao comando atual, não à sessão ou ao computador.

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

-UserName

Especifica o nome de usuário da conta usada para criar uma sessão no computador remoto. O método de autenticação do usuário depende de como o Secure Shell (SSH) é configurado no computador remoto.

Se o SSH estiver configurado para autenticação básica de senha, você será solicitado a fornecer a senha do usuário.

Se o SSH estiver configurado para autenticação de usuário baseada em chave, um caminho de arquivo de chave poderá ser fornecido por meio do parâmetro KeyFilePath e você não será solicitado a fornecer uma senha. Observe que, se o arquivo de chave do usuário cliente estiver localizado em um local conhecido do SSH, o parâmetro KeyFilePath não será necessário para autenticação baseada em chave e a autenticação do usuário ocorrerá automaticamente com base no nome de usuário. Consulte a documentação do SSH sobre a autenticação de usuário baseada em chave para obter mais informações.

Esse não é um parâmetro necessário. Se nenhum parâmetro UserName for especificado, o nome de usuário do logon atual será usado para a conexão.

Esse parâmetro foi introduzido no PowerShell 6.0.

Tipo:String
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 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 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á.

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

-UseWindowsPowerShell

Cria uma conexão remota com um novo runspace do Windows PowerShell no sistema local.

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

-VMId

Especifica uma matriz de IDs de máquina virtual. Esse 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
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-VMName

Especifica uma matriz de nomes de máquinas virtuais. Esse 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[]
Cargo:Named
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga: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 este cmdlet.

Saídas

PSSession

Observações

O PowerShell inclui os seguintes aliases para New-PSSession:

  • Todas as plataformas:

    • nsn

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

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

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

  • Os conjuntos de parâmetros HostName e SSHConnection foram incluídos a partir do PowerShell 6.0. Eles foram adicionados para fornecer comunicação remota do PowerShell com base no Secure Shell (SSH). O SSH e o PowerShell têm suporte em várias plataformas (Windows, Linux, macOS) e a comunicação remota do PowerShell funcionarão nessas plataformas em que o PowerShell e o SSH estão instalados e configurados. Isso é separado da comunicação remota somente do Windows anterior baseada no WinRM e muitos dos recursos e limitações específicos do WinRM não se aplicam. Por exemplo, não há suporte para cotas baseadas em WinRM, opções de sessão, configuração de ponto de extremidade personalizado e recursos de desconexão/reconexão. Para obter mais informações sobre como configurar a comunicação remota do SSH do PowerShell, consulte comunicação remota do PowerShell sobre o SSH.

O executável ssh obtém dados de configuração das seguintes fontes na seguinte ordem:

  1. opções de linha de comando
  2. arquivo de configuração do usuário (~/.ssh/config)
  3. arquivo de configuração em todo o sistema (/etc/ssh/ssh_config)

Os seguintes parâmetros de cmdlet são mapeados para ssh parâmetros e opções:

Parâmetro cmdlet parâmetro ssh opção ssh -o equivalente
-KeyFilePath -i <KeyFilePath> -o IdentityFile=<KeyFilePath>
-UserName -l <UserName> -o User=<UserName>
-Port -p <Port> -o Port=<Port>
-ComputerName -Subsystem -s <ComputerName> <Subsystem> -o Host=<ComputerName>

Todos os valores passados explicitamente por parâmetros têm precedência sobre os valores passados nas opções hashtable. Para obter mais informações sobre arquivos ssh_config, consulte ssh_config(5).