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 gerida pelo utilizador (PSSession). Pode utilizar o objeto como o valor do parâmetro SessionOption dos 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 predefinidos para todas as opções. Uma vez que cada propriedade pode ser editada, pode utilizar o objeto resultante como modelo e criar objetos de opção padrão para a sua empresa.

Também pode guardar um objeto SessionOption na $PSSessionOption variável de preferência. Os valores desta variável estabelecem novos valores predefinidos para as opções de sessão. São eficazes quando não são definidas opções de sessão para a sessão e têm precedência sobre as opções definidas na configuração da sessão, mas pode substitui-las ao especificar opções de sessão ou um objeto SessionOption num cmdlet que cria uma sessão. Para obter mais informações sobre a $PSSessionOption variável de preferência, veja about_Preference_Variables.

Quando utiliza um objeto SessionOption num cmdlet que cria uma sessão, os valores das opções de sessão têm precedência sobre os valores predefinidos para sessões definidas na $PSSessionOption variável de preferência e na configuração da sessão. No entanto, não têm precedência sobre os valores máximos, quotas 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 predefinida

Este comando cria um objeto SessionOption com os valores predefinidos.

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 com um objeto de opção de sessão

Este exemplo mostra como utilizar 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 guarda-o no valor da $pso variável. O segundo comando utiliza o New-PSSession cmdlet para criar uma sessão no computador remoto Server01. O comando utiliza 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 utiliza 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 se certificar de que é executado antes do Enter-PSSession comando.

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

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

$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

Utilize este método para criar um objeto de sessão padrão para a sua empresa e, em seguida, crie versões personalizadas do mesmo para utilizações específicas.

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

Este 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, estabelece valores predefinidos para opções nas sessões que são 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 $PSSessionOption variável de preferência, veja 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 utilizar um objeto SessionOption para cumprir os 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 utiliza o New-PSSessionOption cmdlet para criar um objeto SessionOption que tem a propriedade SkipCNCheck . O comando guarda o objeto de sessão resultante na $skipCN variável.

O segundo comando utiliza o New-PSSession cmdlet para criar uma nova sessão num computador remoto. A $skipCN variável de verificação é utilizada no valor do parâmetro SessionOption .

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

Exemplo 7: Disponibilizar argumentos para uma sessão remota

Este exemplo mostra como utilizar o parâmetro ApplicationArguments do New-PSSessionOption cmdlet para disponibilizar dados adicionais à 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, com o parâmetro ApplicationArguments , cria um objeto SessionOption guardado na $team variável. Quando New-PSSessionOption cria o objeto de opção de sessão, converte automaticamente a tabela hash no valor do parâmetro ApplicationArguments num PrimitiveDictionary para que os dados possam ser transmitidos de forma fiável para a sessão remota.

O New-PSSession cmdlet inicia uma sessão no computador Server01. Utiliza 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 são apresentados na propriedade ApplicationArguments da $PSSenderInfo variável automática.

A final Invoke-Command mostra como os dados podem ser utilizados.

Parâmetros

-ApplicationArguments

Especifica um PrimitiveDictionary que é enviado para a sessão remota. Os comandos e scripts na sessão remota, incluindo scripts de arranque na configuração da sessão, podem encontrar este dicionário na propriedade ApplicationArguments da $PSSenderInfo variável automática. Pode utilizar este parâmetro para enviar dados para a sessão remota.

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

Type:PSPrimitiveDictionary
Position:Named
Default value:None
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 a terminar. Introduza um valor em milissegundos.

O valor predefinido é 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
Accept pipeline input:False
Accept wildcard characters:False

-Culture

Especifica a cultura a utilizar para a sessão. Introduza 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 predefinido é $Null, e a cultura definida no sistema operativo é utilizada na sessão.

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

-IdleTimeout

Determina quanto tempo a sessão permanece aberta se o computador remoto não receber qualquer comunicação do computador local. Isto inclui o sinal de heartbeat. Quando o intervalo expirar, a sessão é fechada.

O valor de tempo limite inativo é de importância significativa se pretender desligar e voltar a ligar a uma sessão. Só pode voltar a ligar se a sessão não tiver excedido o tempo limite.

Introduza 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 predefinido, -1, não define um tempo limite inativo.

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

Se o tempo limite de inatividade 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 Microsoft predefinida. A configuração da sessão do PowerShell é 7200000 milissegundos (2 horas). O valor MaxIdleTimeoutMs é 2147483647 milissegundos (>24 dias). O valor predefinido do tempo limite de inatividade da shell WSMan (WSMan:\<ComputerName>\Shell\IdleTimeout) é 7200000 milissegundos (2 horas).

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

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

Type:Int32
Aliases:IdleTimeoutMSec
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-IncludePortInSPN

Inclui o número de porta no Nome principal de serviço (SPN) utilizado para a autenticação Kerberos, por exemplo, HTTP://<ComputerName>:5985. Esta opção permite que um cliente que utilize um SPN não predefinido se autentique num computador remoto que utilize a autenticação Kerberos.

A opção foi concebida para empresas onde estão em execução vários serviços que suportam a autenticação Kerberos em contas de utilizador diferentes. Por exemplo, uma aplicação IIS que permita a autenticação Kerberos pode exigir que o SPN predefinido seja registado numa conta de utilizador diferente da conta do computador. Nestes casos, a comunicação remota do PowerShell não pode utilizar o Kerberos para autenticar porque requer um SPN registado na conta do computador. Para resolver este problema, os administradores podem criar SPNs diferentes, como, por exemplo, através Setspn.exedo , que estão registados em contas de utilizador diferentes e podem distinguir entre eles ao incluir o número de porta no SPN.

Para obter mais informações, veja Descrição Geral do Setspn.

Este parâmetro foi introduzido no Windows PowerShell 3.0.

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

-MaxConnectionRetryCount

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

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

Type:Int32
Position:Named
Default value:None
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 num único comando. Introduza um valor em bytes. Por predefinição, não existe um limite de tamanho de dados.

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

Type:Int32
Position:Named
Default value:None
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 concebida para proteger os recursos no computador cliente. Introduza um valor em bytes.

No Windows PowerShell 2.0, se omitir este parâmetro, não existe um limite de tamanho de objeto. A partir de Windows PowerShell 3.0, se omitir este parâmetro, o valor predefinido é 209715200 bytes (ou 200MB).

Type:Int32
Position:Named
Default value:209715200
Accept pipeline input:False
Accept wildcard characters:False

-MaximumRedirection

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

Esta opção só é utilizada na sessão quando o parâmetro AllowRedirection é utilizado no comando que cria a sessão.

Type:Int32
Position:Named
Default value:5
Accept pipeline input:False
Accept wildcard characters:False

-NoCompression

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

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

-NoEncryption

Desativa a encriptação de dados.

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

-NoMachineProfile

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

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

-OpenTimeout

Determina quanto tempo o computador cliente aguarda que a ligação de sessão seja estabelecida. Quando o intervalo expirar, o comando para estabelecer a ligação falha. Introduza um valor em milissegundos.

O valor predefinido é 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)
Accept pipeline input:False
Accept wildcard characters:False

-OperationTimeout

Determina o tempo máximo em que o WinRM aguarda testes de ligação positivos a partir de uma ligação em direto antes de iniciar um tempo limite de ligação. Para obter mais informações sobre o WinRM, consulte a Documentação de Gestão Remota do Windows.

OperationTimeoutnão impõe um limite de tempo aos comandos ou processos em execução numa sessão remota e não afeta outros protocolos de remoagem, como o SSH.

O valor predefinido é 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)
Accept pipeline input:False
Accept wildcard characters:False

-OutputBufferingMode

Determina como a saída do comando é gerida em sessões desligadas quando a memória intermédia de saída fica cheia.

Se o modo de memória intermédia de saída não estiver definido na sessão ou na configuração da sessão, o valor predefinido é Block. Os utilizadores também podem alterar o modo de memória intermédia de saída ao desligar a sessão.

Se omitir este parâmetro, o valor de OutputBufferingMode do objeto SessionOption é None. Um valor de Block ou Drop substitui a opção de transporte do modo de memória intermédia de saída definida na configuração da sessão. Os valores aceitáveis para este parâmetro são:

  • Block. Quando a memória intermédia de saída estiver cheia, a execução é suspensa até a memória intermédia estar limpa.
  • Drop. Quando a memória intermédia de saída estiver cheia, a execução continua. À medida que a nova saída é guardada, a saída mais antiga é eliminada.
  • None. Não é especificado nenhum modo de memória intermédia de saída.

Para obter mais informações sobre a opção de transporte do modo de memória intermédia 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
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAccessType

Determina que mecanismo é utilizado para resolver o nome do anfitrião. 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 deste parâmetro, veja Enumeração ProxyAccessType.

Type:ProxyAccessType
Accepted values:None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

-ProxyAuthentication

Especifica o método de autenticação utilizado 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 deste parâmetro, veja AuthenticationMechanism Enumeration (Enumeração AuthenticationMechanism).

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:Negotiate
Accept pipeline input:False
Accept wildcard characters:False

-ProxyCredential

Especifica as credenciais a utilizar para autenticação proxy. Introduza 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 estiver definida, não serão especificadas credenciais.

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

-SkipCACheck

Especifica que, quando liga através de HTTPS, o cliente não valida que o certificado de servidor é assinado por uma autoridade de certificação (AC) fidedigna.

Utilize esta opção apenas quando o computador remoto é fidedigno através de outro mecanismo, como quando o computador remoto faz parte de uma rede fisicamente segura e isolada ou quando o computador remoto é listado como um anfitrião fidedigno numa configuração winRM.

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

-SkipCNCheck

Especifica que o nome comum do certificado (CN) do servidor não tem de corresponder ao nome do anfitrião do servidor. Esta opção é utilizada apenas em operações remotas que utilizam o protocolo HTTPS.

Utilize esta opção apenas para computadores fidedignos.

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

-SkipRevocationCheck

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

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

-UICulture

Especifica a cultura de IU a utilizar 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 predefinido é $nulle a cultura de IU que é definida no sistema operativo quando a sessão é criada.

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

-UseUTF16

Indica que este cmdlet codifica o pedido no formato UTF16 em vez do formato UTF8.

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

Entradas

None

Não pode encaminhar objetos para este cmdlet.

Saídas

PSSessionOption

Notas

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

As propriedades de um objeto de configuração de sessão variam consoante 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 utilizam um ficheiro de configuração de sessão têm propriedades adicionais.