New-PSSessionOption

Módulo:

Microsoft.PowerShell.Core

Cria um objeto que contém opções avançadas para uma PSSession.

Sintaxe

New-PSSessionOption
   [-MaximumRedirection <Int32>]
   [-NoCompression]
   [-NoMachineProfile]
   [-Culture <CultureInfo>]
   [-UICulture <CultureInfo>]
   [-MaximumReceivedDataSizePerCommand <Int32>]
   [-MaximumReceivedObjectSize <Int32>]
   [-OutputBufferingMode <OutputBufferingMode>]
   [-MaxConnectionRetryCount <Int32>]
   [-ApplicationArguments <PSPrimitiveDictionary>]
   [-OpenTimeout <Int32>]
   [-CancelTimeout <Int32>]
   [-IdleTimeout <Int32>]
   [-ProxyAccessType <ProxyAccessType>]
   [-ProxyAuthentication <AuthenticationMechanism>]
   [-ProxyCredential <PSCredential>]
   [-SkipCACheck]
   [-SkipCNCheck]
   [-SkipRevocationCheck]
   [-OperationTimeout <Int32>]
   [-NoEncryption]
   [-UseUTF16]
   [-IncludePortInSPN]
   [<CommonParameters>]

Description

O New-PSSessionOption cmdlet cria um objeto que contém opções avançadas para uma sessão gerenciada pelo usuário (PSSession). Você pode usar o objeto como o valor do parâmetro SessionOption de cmdlets que criam uma PSSession, como New-PSSession, Enter-PSSessione Invoke-Command.

Sem parâmetros, New-PSSessionOption gera um objeto que contém os valores padrão para todas as opções. Como cada propriedade pode ser editada, você pode usar o objeto resultante como um modelo e criar objetos de opção padrão para sua empresa.

Você também pode salvar um objeto SessionOption na variável de $PSSessionOption preferência. Os valores dessa variável estabelecem novos valores padrão para as opções de sessão. Eles são eficazes quando nenhuma opção de sessão é definida para a sessão e têm precedência sobre as opções definidas na configuração da sessão, mas você pode substituí-las especificando opções de sessão ou um objeto SessionOption em um cmdlet que cria uma sessão. Para obter mais informações sobre a variável de $PSSessionOption preferência, consulte about_Preference_Variables.

Quando você usa um objeto SessionOption em um cmdlet que cria uma sessão, os valores de opção de sessão têm precedência sobre os valores padrão para sessões definidas na $PSSessionOption 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 mais informações sobre configurações de sessão, consulte about_Session_Configurations.

Exemplos

Exemplo 1: Criar uma opção de sessão padrão

Este comando cria um objeto SessionOption com os valores padrão.

New-PSSessionOption

MaximumConnectionRedirectionCount : 5
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         :
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:03:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

Exemplo 2: Configurar uma sessão usando um objeto de opção de sessão

Este exemplo mostra como usar um objeto SessionOption para configurar uma sessão.

$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $pso

O primeiro comando cria um novo objeto SessionOption e o salva no valor da $pso variável. O segundo comando usa o New-PSSession cmdlet para criar uma sessão no computador remoto Server01. O comando usa o objeto SessionOption no valor da $pso variável como o valor do parâmetro SessionOption do comando.

Exemplo 3: Iniciar uma sessão interativa

Este comando usa o Enter-PSSession cmdlet para iniciar uma sessão interativa com o computador Server01.

Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)

O valor do parâmetro SessionOption é um New-PSSessionOption comando que tem os parâmetros NoEncryption e NoCompressão .

O New-PSSessionOption comando é colocado entre parênteses para garantir que é executado antes do Enter-PSSession comando.

Exemplo 4: Modificar um objeto de opção de sessão

Este exemplo demonstra que você pode modificar o objeto SessionOption . Todas as propriedades têm valores de leitura/gravação.

$a = New-PSSessionOption
$a.OpenTimeout

Days              : 0
Hours             : 0
Minutes           : 3
Seconds           : 0
Milliseconds      : 0
Ticks             : 1800000000
TotalDays         : 0.00208333333333333
TotalHours        : 0.05
TotalMinutes      : 3
TotalSeconds      : 180
TotalMilliseconds : 180000

$a.UICulture = (Get-UICulture)
$a.OpenTimeout = (New-Timespan -Minutes 4)
$a.MaximumConnectionRedirectionCount = 1
$a

MaximumConnectionRedirectionCount : 1
NoCompression                     : False
NoMachineProfile                  : False
ProxyAccessType                   : IEConfig
ProxyAuthentication               : Negotiate
ProxyCredential                   :
SkipCACheck                       : False
SkipCNCheck                       : False
SkipRevocationCheck               : False
OperationTimeout                  : 00:03:00
NoEncryption                      : False
UseUTF16                          : False
Culture                           :
UICulture                         : en-US
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize         :
ApplicationArguments              :
OpenTimeout                       : 00:04:00
CancelTimeout                     : 00:01:00
IdleTimeout                       : 00:04:00

Use esse método para criar um objeto de sessão padrão para sua empresa e, em seguida, crie versões personalizadas dele para usos específicos.

Exemplo 5: Criar uma variável de preferência

Este comando cria uma variável de $PSSessionOption preferência.

$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000

Quando a $PSSessionOption variável de preferência é definida na sessão, ela estabelece valores padrão para opções nas sessões criadas com os New-PSSessioncmdlets , Enter-PSSessione Invoke-Command .

Para disponibilizar a $PSSessionOption variável em todas as sessões, adicione-a à sua sessão do PowerShell e ao seu perfil do PowerShell.

Para obter mais informações sobre a variável de $PSSessionOption preferência, consulte about_Preference_Variables. Para obter mais informações sobre perfis, consulte about_Profiles.

Exemplo 6: Cumprir os requisitos para uma configuração de sessão remota

Este exemplo mostra como usar um objeto SessionOption para atender aos requisitos de uma configuração de sessão remota.

$skipCN = New-PSSessionOption -SkipCNCheck
New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN

O primeiro comando usa o New-PSSessionOption cmdlet para criar um objeto SessionOption que tem a propriedade SkipCNCheck . O comando salva o objeto de sessão resultante na $skipCN variável.

O segundo comando usa o New-PSSession cmdlet para criar uma nova sessão em um computador remoto. A $skipCN variável check é usada no valor do parâmetro SessionOption .

Como o computador é identificado por seu endereço IP, o valor do parâmetro ComputerName não corresponde a nenhum dos nomes comuns no certificado usado para SSL (Secure Sockets Layer). Como resultado, a opção SkipCNCheck é necessária.

Exemplo 7: Disponibilizar argumentos para uma sessão remota

Este exemplo mostra como usar o parâmetro ApplicationArguments do New-PSSessionOption cmdlet para disponibilizar dados adicionais para a sessão remota.

$team = @{Team="IT"; Use="Testing"}
$TeamOption = New-PSSessionOption -ApplicationArguments $team
$s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption
Invoke-Command -Session $s {$PSSenderInfo.ApplicationArguments}

Name                 Value
----                 -----
Team                 IT
Use                  Testing
PSVersionTable       {CLRVersion, BuildVersion, PSVersion, WSManStackVersion...}

Invoke-Command -Session $s {
  if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {
    .\logFiles.ps1
  }
  else {
    "Just testing."
  }
}

Just testing.

O primeiro comando cria uma tabela hash com duas chaves, Team e Use. O comando guarda a tabela hash na variável $team. Para obter mais informações sobre tabelas hash, veja about_Hash_Tables.

Em seguida, o New-PSSessionOption cmdlet, usando o parâmetro ApplicationArguments , cria um objeto SessionOption salvo na $team variável. Quando New-PSSessionOption cria o objeto de opção de sessão, ele converte automaticamente a tabela de hash no valor do parâmetro ApplicationArguments em um PrimitiveDictionary para que os dados possam ser transmitidos de forma confiável para a sessão remota.

O New-PSSession cmdlet inicia uma sessão no computador Server01. Ele usa o parâmetro SessionOption para incluir as opções na $teamOption variável.

O Invoke-Command cmdlet demonstra que os $team dados na variável estão disponíveis para comandos na sessão remota. Os dados aparecem na propriedade ApplicationArguments da $PSSenderInfo variável automática.

O final Invoke-Command mostra como os dados podem ser usados.

Parâmetros

-ApplicationArguments

Especifica um PrimitiveDictionary que é enviado para a sessão remota. Comandos e scripts na sessão remota, incluindo scripts de inicialização na configuração da sessão, podem encontrar esse dicionário na propriedade ApplicationArguments da $PSSenderInfo variável automática. Você pode usar esse parâmetro para enviar dados para a sessão remota.

Para obter mais informações, consulte about_Hash_Tables, about_Session_Configurations e about_Automatic_Variables.

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

-CancelTimeout

Determina quanto tempo o PowerShell aguarda a conclusão de uma operação de cancelamento (CTRL+C) antes de encerrá-la. Insira um valor em milissegundos.

O valor padrão é 60000 (um minuto). Um valor de 0 (zero) significa que não há tempo limite, o comando continua indefinidamente.

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

-Culture

Especifica a cultura a ser usada para a sessão. Insira um nome de cultura no <languagecode2>-<country/regioncode2> formato (como ja-JP), uma variável que contenha um objeto CultureInfo ou um comando que obtenha um objeto CultureInfo .

O valor padrão é $Null, e a cultura definida no sistema operacional é usada na sessão.

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

-IdleTimeout

Determina por quanto tempo a sessão permanece aberta se o computador remoto não receber nenhuma comunicação do computador local. Isto inclui o sinal de batimento cardíaco. Quando o intervalo expira, a sessão é fechada.

O valor de tempo limite ocioso é de importância significativa se você pretende desconectar e reconectar a uma sessão. Você pode se reconectar somente se a sessão não tiver expirado.

Insira um valor em milissegundos. O valor mínimo é 60000 (1 minuto). O máximo é o valor da propriedade MaxIdleTimeoutms da configuração da sessão. O valor padrão, -1, não define um tempo limite ocioso.

A sessão usa o tempo limite ocioso definido nas opções de sessão, se houver. Se nenhum estiver definido (-1), a sessão usará o valor da propriedade IdleTimeoutMs da configuração da sessão ou o valor de tempo limite do shell WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout), o que for mais curto.

Se o tempo limite ocioso definido nas opções de sessão exceder o valor da propriedade MaxIdleTimeoutMs da configuração da sessão, o comando para criar uma sessão falhará.

O valor IdleTimeoutMs da configuração de sessão padrão do Microsoft.PowerShell é 7200000 milissegundos (2 horas). Seu valor MaxIdleTimeoutMs é 2147483647 milissegundos (>24 dias). O valor padrão do tempo limite ocioso do shell WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout) é 7200000 milissegundos (2 horas).

O valor de tempo limite ocioso de uma sessão também pode ser alterado ao se desconectar de uma sessão ou se reconectar a uma sessão. Para obter mais informações, consulte Disconnect-PSSession e Connect-PSSession.

No Windows PowerShell 2.0, o valor padrão do parâmetro IdleTimeout é 240000 (4 minutos).

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

-IncludePortInSPN

Inclui o número da porta no SPN (Nome da Entidade de Serviço) usado para autenticação Kerberos, por exemplo, HTTP://<ComputerName>:5985. Essa opção permite que um cliente que usa um SPN não padrão se autentique em um computador remoto que usa a autenticação Kerberos.

A opção foi projetada para empresas em que vários serviços que suportam a autenticação Kerberos estão sendo executados em diferentes contas de usuário. Por exemplo, um aplicativo do IIS que permite a autenticação Kerberos pode exigir que o SPN padrão seja registrado em uma conta de usuário diferente da conta do computador. Nesses casos, a comunicação remota do PowerShell não pode usar Kerberos para autenticar porque requer um SPN registrado na conta do computador. Para resolver esse problema, os administradores podem criar SPNs diferentes, como usando Setspn.exe, que são registrados em contas de usuário diferentes e podem distinguir entre eles incluindo o número da porta no SPN.

Para obter mais informações, consulte Visão geral do Setspn.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

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

-MaxConnectionRetryCount

Especifica o número de vezes que o PowerShell tenta fazer uma conexão com uma máquina de destino se a tentativa atual falhar devido a problemas de rede. O valor predefinido é 5.

Este parâmetro foi adicionado para o PowerShell versão 5.0.

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

-MaximumReceivedDataSizePerCommand

Especifica o número máximo de bytes que o computador local pode receber do computador remoto em um único comando. Insira um valor em bytes. Por padrão, não há limite de tamanho de dados.

Esta opção foi concebida para proteger os recursos no computador cliente.

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

-MaximumReceivedObjectSize

Especifica o tamanho máximo de um objeto que o computador local pode receber do computador remoto. Esta opção foi concebida para proteger os recursos no computador cliente. Insira um valor em bytes.

No Windows PowerShell 2.0, se você omitir esse parâmetro, não haverá limite de tamanho de objeto. A partir do Windows PowerShell 3.0, se você omitir esse parâmetro, o valor padrão será 209715200 bytes (ou 200MB).

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

-MaximumRedirection

Determina quantas vezes o PowerShell redireciona uma conexão para um URI (Uniform Resource Identifier) alternativo antes que a conexão falhe. O valor predefinido é 5. Um valor de 0 (zero) impede todo o redirecionamento.

Essa opção é usada na sessão somente quando o parâmetro AllowRedirection é usado no comando que cria a sessão.

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

-NoCompression

Desativa a compactação de pacotes na sessão. A compressão usa mais ciclos de processador, mas torna a transmissão mais rápida.

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

-NoEncryption

Desativa a encriptação de dados.

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

-NoMachineProfile

Impede o carregamento do perfil de usuário do Windows do usuário. Como resultado, a sessão pode ser criada mais rapidamente, mas configurações de registro específicas do usuário, itens como variáveis de ambiente e certificados não estão disponíveis na sessão.

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

-OpenTimeout

Determina quanto tempo o computador cliente aguarda para que a conexão de sessão seja estabelecida. Quando o intervalo expira, o comando para estabelecer a conexão falha. Insira um valor em milissegundos.

O valor padrão é 180000 (3 minutos). Um valor de 0 (zero) significa que não há tempo limite, o comando continua indefinidamente.

Tipo:	Int32
Aliases:	OpenTimeoutMSec
Position:	Named
Default value:	180000 (3 minutes)
Necessário:	False
Aceitar entrada de pipeline:	False
Aceitar carateres universais:	False

-OperationTimeout

Determina o tempo máximo que o WinRM aguarda por testes de conexão positivos de uma conexão ao vivo antes de iniciar um tempo limite de conexão. Para obter mais informações sobre o WinRM, consulte a documentação de gerenciamento remoto do Windows.

OperationTimeout não impõe um limite de tempo para comandos ou processos em execução em uma sessão remota e não afeta outros protocolos de comunicação remota, como SSH.

O valor padrão é 180000 (3 minutos). Um valor de 0 (zero) significa que não há tempo limite.

Tipo:	Int32
Aliases:	OperationTimeoutMSec
Position:	Named
Default value:	180000 (3 minutes)
Necessário:	False
Aceitar entrada de pipeline:	False
Aceitar carateres universais:	False

-OutputBufferingMode

Determina como a saída do comando é gerenciada em sessões desconectadas quando o buffer de saída fica cheio.

Se o modo de buffer de saída não estiver definido na sessão ou na configuração da sessão, o valor padrão será Block. Os usuários também podem alterar o modo de buffer de saída ao desconectar a sessão.

Se você omitir esse parâmetro, o valor do OutputBufferingMode do objeto SessionOption será None. Um valor ou Drop substitui a opção de transporte do modo de buffer de Block saída definida na configuração da sessão. Os valores aceitáveis para este parâmetro são:

• Block. Quando o buffer de saída está cheio, a execução é suspensa até que o buffer esteja limpo.
• Drop. Quando o buffer de saída estiver cheio, a execução continuará. À medida que a nova saída é salva, a saída mais antiga é descartada.
• None. Nenhum modo de buffer de saída é especificado.

Para obter mais informações sobre a opção de transporte do modo de buffer de saída, consulte New-PSTransportOption.

Esse parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:	OutputBufferingMode
Valores aceites:	None, Drop, Block
Position:	Named
Default value:	None
Necessário:	False
Aceitar entrada de pipeline:	False
Aceitar carateres universais:	False

-ProxyAccessType

Determina qual mecanismo é usado para resolver o nome do host. Os valores aceitáveis para este parâmetro são:

• IEConfig
• WinHttpConfig
• AutoDetect
• NoProxyServer
• None

O valor predefinido é None.

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

Tipo:	ProxyAccessType
Valores aceites:	None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer
Position:	Named
Default value:	None
Necessário:	False
Aceitar entrada de pipeline:	False
Aceitar carateres universais:	False

-ProxyAuthentication

Especifica o método de autenticação usado para a resolução de proxy. Os valores aceitáveis para este parâmetro são:

• Basic
• Digest
• Negotiate

O valor predefinido é Negotiate.

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

Tipo:	AuthenticationMechanism
Valores aceites:	Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:	Named
Default value:	Negotiate
Necessário:	False
Aceitar entrada de pipeline:	False
Aceitar carateres universais:	False

-ProxyCredential

Especifica as credenciais a serem usadas para autenticação de proxy. Insira uma variável que contenha um objeto PSCredential ou um comando que obtenha um objeto PSCredential , como um Get-Credential comando. Se essa opção não estiver definida, nenhuma credencial será especificada.

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

-SkipCACheck

Especifica que, quando ele se conecta por HTTPS, o cliente não valida se o certificado do servidor é assinado por uma autoridade de certificação (CA) confiável.

Use essa opção somente quando o computador remoto for confiável usando outro mecanismo, como quando o computador remoto fizer parte de uma rede fisicamente segura e isolada ou quando o computador remoto estiver listado como um host confiável em uma configuração do WinRM.

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

-SkipCNCheck

Especifica que o nome comum do certificado (CN) do servidor não precisa corresponder ao nome do host do servidor. Esta opção é usada apenas em operações remotas que usam o protocolo HTTPS.

Utilize esta opção apenas para computadores fidedignos.

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

-SkipRevocationCheck

Não valida o status de revogação do certificado do servidor.

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

-UICulture

Especifica a cultura da interface do usuário a ser usada para a sessão.

Os valores válidos incluem:

• Um nome de cultura em <languagecode2>-<country/regioncode2> formato, como ja-JP
• Uma variável que contém um objeto CultureInfo
• Um comando que obtém um objeto CultureInfo , como Get-Culture

O valor padrão é $null, e a cultura da interface do usuário que é definida no sistema operacional quando a sessão é criada.

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

-UseUTF16

Indica que esse cmdlet codifica a solicitação no formato UTF16 em vez do formato UTF8.

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

Entradas

None

Não é possível canalizar objetos para este cmdlet.

Saídas

PSSessionOption

Notas

Se o parâmetro SessionOption não for usado em um comando para criar uma PSSession, as opções de sessão serão determinadas pelos valores de propriedade da variável de $PSSessionOption preferência, se ela estiver definida. Para obter mais informações sobre a $PSSessionOption variável, consulte about_Preference_Variables.

As propriedades de um objeto de configuração de sessão variam com as opções definidas para a configuração da sessão e os valores dessas opções. Além disso, as configurações de sessão que usam um arquivo de configuração de sessão têm propriedades adicionais.

Ligações Relacionadas

• Enter-PSSession
• Invoke-Command
• New-PSSession