New-PSSession

Sintaxe

ComputerName (Predefinição)

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

Uri

New-PSSession
    [-ConnectionUri] <Uri[]>
    [-Credential <PSCredential>]
    [-Name <String[]>]
    [-EnableNetworkAccess]
    [-ConfigurationName <String>]
    [-ThrottleLimit <Int32>]
    [-AllowRedirection]
    [-SessionOption <PSSessionOption>]
    [-Authentication <AuthenticationMechanism>]
    [-CertificateThumbprint <String>]
    [<CommonParameters>]

Session

New-PSSession
    [[-Session] <PSSession[]>]
    [-Name <String[]>]
    [-EnableNetworkAccess]
    [-ThrottleLimit <Int32>]
    [<CommonParameters>]

Description

Exemplos

Exemplo 1: Criar uma sessão no computador local

PS C:\> $s = New-PSSession

Exemplo 2: Criar uma sessão num computador remoto

PS C:\> $Server01 = New-PSSession -ComputerName Server01

Exemplo 3: Criar sessões em vários computadores

PS C:\> $s1, $s2, $s3 = New-PSSession -ComputerName Server01,Server02,Server03

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

PS C:\> New-PSSession -ComputerName Server01 -Port 8081 -UseSSL -ConfigurationName E12

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

PS C:\> New-PSSession -Session $s -Credential Domain01\User01

Exemplo 6: Criar 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\Admin01

Exemplo 7: Criar sessões para muitos computadores

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

Exemplo 8: Criar uma sessão usando um URI

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

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

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

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

Exemplo 11: Criar 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\Admin01

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 Windows 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 MaximumConnectionRedirectionCount valor da opção de 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.

Propriedades dos parâmetros

Conjuntos de parâmetros

-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 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 sobre_Variáveis_de_Preferência.

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.

Propriedades dos parâmetros

Conjuntos de parâmetros

-Authentication

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

• Predefinido
• Básico
• Credssp
• Resumo
• Kerberos
• Negociar
• NegociarComImplicitCredential

O valor padrão é Default.

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

Cuidado: 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.

Propriedades dos parâmetros

Conjuntos de parâmetros

-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 (thumbprint) 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 comando Get-Item ou Get-ChildItem na unidade Windows PowerShell Cert:.

Propriedades dos parâmetros

Conjuntos de parâmetros

-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 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, localhost 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 (https://go.microsoft.com/fwlink/?LinkID=135188).

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

Propriedades dos parâmetros

Conjuntos de parâmetros

-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 de esquema será precedido: 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 essa variável de preferência não estiver definida, o padrão será Microsoft.PowerShell. Para obter mais informações, consulte sobre_Variáveis_de_Preferência.

Propriedades dos parâmetros

Conjuntos de parâmetros

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

Transporte <>://<ComputerName>:<Port>/<ApplicationName>

O valor padrão é o seguinte:

https://localhost:5985/WSMAN

Se você não especificar um ConnectionURI, poderá usar os parâmetros UseSSL, ComputerName, Porte ApplicationName parâmetros para especificar os valores de 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 Windows PowerShell, especifique a porta 5985 para HTTP ou 5986 para HTTPS.

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

Propriedades dos parâmetros

Conjuntos de parâmetros

-Credential

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

Digite um nome de usuário, como User01, Domain01\User01 ou , 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.

Propriedades dos parâmetros

Conjuntos de parâmetros

-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 é um 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, que pode não fornecer permissão suficiente para autenticação em computadores remotos.

O parâmetro EnableNetworkAccess é efetivo 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 valor CredSSP 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 aquelas criadas 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, consulte Disconnect-PSSession.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Propriedades dos parâmetros

Conjuntos de parâmetros

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

Propriedades dos parâmetros

Conjuntos de parâmetros

-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 a escutar na porta à qual a ligação é feita. 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.

Propriedades dos parâmetros

Conjuntos de parâmetros

-Session

Especifica uma matriz de objetos PSSession que esse cmdlet usa como modelo para o novoPSSession . Este parâmetro cria novos PSSession objetos que têm as mesmas propriedades que os objetos especificados PSSession.

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

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 têm um nome de exibição, ID e ID de instância (GUID) diferentes.

Propriedades dos parâmetros

Conjuntos de parâmetros

-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 pelas opções definidas na configuração da sessão.

Os valores de opção de sessão têm precedência sobre os 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 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 preferência $PSSessionOption, consulte about_Preference_Variables. Para obter mais informações sobre configurações de sessão, consulte about_Session_Configurations.

Propriedades dos parâmetros

Conjuntos de parâmetros

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

Propriedades dos parâmetros

Conjuntos de parâmetros

-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 Windows 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á.

Propriedades dos parâmetros

Conjuntos de parâmetros

CommonParameters

Entradas

System.String, System.URI, System.Management.Automation.Runspaces.PSSession

Saídas

PSSession

Notas

Ligações Relacionadas

• Connect-PSSession
• Desconectar-PSSession
• Entrar na sessão do PowerShell (Enter-PSSession)
• ** Encerrar a sessão do PowerShell
• Get-PSSession
• Invoke-Command
• Receive-PSSession
• Remove-PSSession
• sobre_PSSessions
• sobre_Remoto