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 um 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 $PSSessionOption variável de preferência. Os valores desta variável estabelecem novos valores padrão para as opções da sessão. Eles são efetivos 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í-los 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 preferência, consulte about_Preference_Variables$PSSessionOption.

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 valores máximos, cotas ou limites definidos na configuração da sessão. Para saber mais sobre configurações de sessão, confira about_Session_Configurations.

Exemplos

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

Esse 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

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

O New-PSSessionOption comando é colocado entre parênteses para garantir que ele seja 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, criar versões personalizadas desse objeto 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 preferência, consulte about_Preference_Variables$PSSessionOption. Para obter mais informações sobre perfis, consulte about_Profiles.

Exemplo 6: Atender aos 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 de verificação é 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 de hash com duas chaves, Team e Use. O comando salva a tabela de hash na $team variável. Para obter informações sobre tabelas de hash, confira 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 este parâmetro para enviar dados à sessão remota.

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

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

-CancelTimeout

Determina quanto tempo o PowerShell aguarda para que uma operação de cancelamento (CTRL+C) seja concluída 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
Cargo:	Named
Valor padrão:	60000
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	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
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-IdleTimeout

Determina por quanto tempo a sessão permanece aberta se o computador remoto não receber nenhuma comunicação do computador local. Isso 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 se desconectar e se reconectar a uma sessão. Você poderá reconectar-se 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 for 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 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
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	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. Esta opção permite que um cliente que usa um SPN não padrão faça a autenticação em um computador remoto que usa autenticação Kerberos.

A opção é projetada para empresas nas quais vários serviços que oferecem suporte à 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 o Kerberos para autenticar porque requer um SPN registrado na conta do computador. Para resolver esse problema, os administradores podem criar SPNs diferentes, por exemplo, usando Setspn.exeo , 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.

Este parâmetro foi introduzido no Windows PowerShell 3.0.

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

-MaxConnectionRetryCount

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

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

Tipo:	Int32
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	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 criada para proteger os recursos no computador cliente.

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

-MaximumReceivedObjectSize

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

No Windows PowerShell 2.0, se você omite esse parâmetro, não há limite para tamanho do 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
Cargo:	Named
Valor padrão:	209715200
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	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 padrão é 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
Cargo:	Named
Valor padrão:	5
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-NoCompression

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

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

-NoEncryption

Desativa a criptografia de dados.

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

-NoMachineProfile

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

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

-OpenTimeout

Determina por quanto tempo o computador cliente aguarda para que a conexão da 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
Cargo:	Named
Valor padrão:	180000 (3 minutes)
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-OperationTimeout

Determina o tempo máximo que o WinRM aguarda por testes de conexão positivos de uma conexão dinâmica 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 em 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
Cargo:	Named
Valor padrão:	180000 (3 minutes)
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	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 buffering de saída ao desconectarem-se da sessão.

Se você omitir esse parâmetro, o valor do OutputBufferingMode do objeto SessionOption será None. Um valor de ou Drop substitui a opção de transporte do modo de Block buffer de saída definida na configuração da sessão. Os valores aceitáveis para esse 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 está cheio, a execução continua. Conforme uma nova saída é salva, a saída mais antiga é descartada.
• None. Nenhum modo de buffering 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.

Este parâmetro foi introduzido no Windows PowerShell 3.0.

Tipo:	OutputBufferingMode
Valores aceitos:	None, Drop, Block
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ProxyAccessType

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

• IEConfig
• WinHttpConfig
• AutoDetect
• NoProxyServer
• None

O valor padrão é None.

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

Tipo:	ProxyAccessType
Valores aceitos:	None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ProxyAuthentication

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

• Basic
• Digest
• Negotiate

O valor padrão é Negotiate.

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

Tipo:	AuthenticationMechanism
Valores aceitos:	Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Cargo:	Named
Valor padrão:	Negotiate
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	False

-ProxyCredential

Especifica as credenciais a usar 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 esta opção não for definida, nenhuma credencial será especificada.

Tipo:	PSCredential
Cargo:	Named
Valor padrão:	None
Obrigatório:	False
Aceitar a entrada de pipeline:	False
Aceitar caracteres curinga:	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 esta opção somente quando o computador remoto for considerado confiável pelo uso de outro mecanismo, como por exemplo quando o computador remoto é parte de uma rede fisicamente segura e isolada, ou quando o computador remoto está listado como um host confiável em uma configuração de WinRM.

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

-SkipCNCheck

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

Use esta opção somente para computadores confiáveis.

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

-SkipRevocationCheck

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

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

-UICulture

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

-UseUTF16

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

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

Entradas

None

Você não pode canalizar objetos para esse cmdlet.

Saídas

PSSessionOption

Observações

Se o parâmetro SessionOption não for usado em um comando para criar um 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 variável $PSSessionOption, consulte about_Preference_Variables.

As propriedades de um objeto de configuração de sessão variam de acordo 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.

Links Relacionados

• ENTER-PSSession
• Invoke-Command
• New-PSSession