Share via

New-PSSessionOption

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

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

Syntax

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 $PSSessionOption variável de preferência. Os valores desta variável estabelecem novos valores padrão para as opções da sessão. Elas são eficazes quando nenhuma opção de sessão é definida para a sessão e elas 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 $PSSessionOption variável de 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 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 obter mais informações sobre configurações de sessão, consulte about_Session_Configurations.

Exemplos

Exemplo 1: Create 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 está 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: Create uma variável de preferência

Esse comando cria uma $PSSessionOption variável de 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 à sessão do PowerShell e ao seu perfil do PowerShell.

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

Exemplo 6: atender aos requisitos de uma configuração de sessão remota

Este exemplo mostra como usar um objeto SessionOption para atender os requisitos para a configuração de uma 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 tenha 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 marcar é 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 é obrigató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, Equipe e Uso. 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 dados na $team variável estão disponíveis para comandos na sessão remota. Os dados aparecem na propriedade ApplicationArguments da $PSSenderInfo variável automática.

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

Type:PSPrimitiveDictionary
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:Int32
Aliases:CancelTimeoutMSec
Position:Named
Default value:60000
Required:False
Accept pipeline input:False
Accept wildcard characters: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 contém um objeto CultureInfo ou um comando que obtém um objeto CultureInfo .

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

Type:CultureInfo
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IdleTimeout

Determina por quanto tempo a sessão permanecerá aberta se o computador remoto não receber nenhuma comunicação do computador local. Isso inclui o sinal de pulsação. Quando o intervalo expira, a sessão é fechada.

O valor de tempo limite ocioso será 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 de 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 de 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.

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

Type:Int32
Aliases:IdleTimeoutMSec
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 de 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 resolve esse problema, os administradores podem criar SPNs diferentes, como usando Setspn.exe, que são registrados em diferentes contas de usuário 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.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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. Começando no Windows PowerShell 3.0, se você omitir esse parâmetro, o valor padrão será 200.

Type:Int32
Position:Named
Default value:200 MB
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:Int32
Position:Named
Default value:5
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-NoEncryption

Desativa a criptografia de dados.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:Int32
Aliases:OpenTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

O OperationTimeoutnã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 o SSH.

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

Type:Int32
Aliases:OperationTimeoutMSec
Position:Named
Default value:180000 (3 minutes)
Required:False
Accept pipeline input:False
Accept wildcard characters: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 de OutputBufferingMode do objeto SessionOption será None. Um valor de Block ou Drop substitui a opção de transporte do modo de 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.

Type:OutputBufferingMode
Accepted values:None, Drop, Block
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAccessType

Determina qual mecanismo é usado para resolve 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.

Type:ProxyAccessType
Accepted values:None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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, confira Enumeração AuthenticationMechanism.

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:Negotiate
Required:False
Accept pipeline input:False
Accept wildcard characters: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 obtém um objeto PSCredential , como um Get-Credential comando. Se esta opção não for definida, nenhuma credencial será especificada.

Type:PSCredential
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipCACheck

Especifica que, quando ele se conecta via HTTPS, o cliente não valida se o certificado do servidor é assinado por uma AC (autoridade de certificação) 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.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SkipRevocationCheck

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

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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 no <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 é $nulle a cultura da interface do usuário definida no sistema operacional quando a sessão é criada.

Type:CultureInfo
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UseUTF16

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

Não é possível redirecionar a entrada para este cmdlet.

Saídas

PSSessionOption

Observações

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