New-PSSessionOption
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 cmdlet New-PSSessionOption 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-PSSession e Invoke-Command.
Sem parâmetros, New-PSSessionOption gera um objeto que contém os valores padrão para todas as opções. Como todas as propriedades podem ser editadas, 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 de opção de sessão na variável de preferência $PSSessionOption
. Os valores dessa variável estabelecem novos valores padrão para as opções de sessão. Elas são efetivadas 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 de opção de sessão em um cmdlet que cria uma sessão. Para obter mais informações sobre a variável de preferência $PSSessionOption
, consulte about_Preference_Variables.
Quando você usa um objeto de opção de sessão 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 variável de preferência $PSSessionOption 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: criar uma opção de sessão padrão
Esse comando cria um objeto de opção de sessão que tem todos 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 de opção de sessão 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 de opção de sessão e o salva no valor da variável $pso
. O segundo comando usa o cmdlet New-PSSession
para criar uma sessão no computador remoto Server01. O comando usa o objeto de opção de sessão no valor da variável $pso
como o valor do parâmetro SessionOption do comando.
Exemplo 3: iniciar uma sessão interativa
Esse comando usa o cmdlet Enter-PSSession
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 comando New-PSSessionOption
que tem os parâmetros noEncryption e noCompression.
O comando New-PSSessionOption
está entre parênteses para garantir que ele seja executado antes do comando Enter-PSSession
.
Exemplo 4: Modificar um objeto de opção de sessão
Este exemplo demonstra que você pode modificar o objeto de opção de sessão. 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
Esse comando cria uma variável de preferência $PSSessionOption
.
$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000
Quando a variável de preferência $PSSessionOption
ocorre na sessão, ela estabelece valores padrão para opções nas sessões criadas usando os cmdlets New-PSSession
, Enter-PSSession
e Invoke-Command
.
Para disponibilizar a variável $PSSessionOption
em todas as sessões, adicione-a à sessão do PowerShell e ao seu perfil do PowerShell.
Para obter mais informações sobre a variável de preferência $PSSessionOption
, 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 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 cmdlet $skipCN
.
O segundo comando usa o cmdlet New-PSSession
para criar uma nova sessão em um computador remoto. A variável de verificação $skipCN
é 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
Exemplo 7: disponibilizar argumentos para uma sessão remota
Este exemplo mostra como usar o parâmetro ApplicationArguments do cmdlet New-PSSessionOption
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 variável $team
. Para obter mais informações sobre tabelas de hash, consulte about_Hash_Tables.
Em seguida, o cmdlet New-PSSessionOption
, usando o parâmetro ApplicationArguments, cria um objeto de opção de sessão salvo na variável $team
. 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 dicionário primitivo para que os dados possam ser transmitidos de forma confiável para a sessão remota.
O cmdlet New-PSSession
inicia uma sessão no computador Server01. Ele usa o parâmetro SessionOption para incluir as opções na variável $teamOption
.
O cmdlet Invoke-Command
demonstra que os dados na variável $team
estão disponíveis para comandos na sessão remota. Os dados são exibidos na propriedade ApplicationArguments da variável automática $PSSenderInfo
.
O Invoke-Command
final mostra como os dados podem ser usados.
Parâmetros
-ApplicationArguments
Especifica um dicionário primitivo 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 variável automática $PSSenderInfo
. 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_Configurationse 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 por 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 |
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 formato <languagecode2>-<country/regioncode2>
(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 é $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 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 é de importância significativa se você pretende se desconectar e se reconectar a uma sessão. Você só poderá se reconectar se a sessão não tiver cronometrado.
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 do valor de tempo limite do shell do 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 do MaxIdleTimeoutMs propriedade da configuração da sessão, o comando para criar uma sessão falhará.
O IdleTimeoutMs valor do padrão a configuração de sessão Microsoft.PowerShell é 7200000 milissegundos (2 horas). Seu valor de MaxIdleTimeoutMs 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 |
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
. 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 dão suporte à autenticação Kerberos estão em execução em contas de usuário diferentes. Por exemplo, um aplicativo 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 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 distingui-los 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 |
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.
Essa opção foi projetada 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. Essa opção foi projetada 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á de 200 MB.
Tipo: | Int32 |
Cargo: | Named |
Valor padrão: | 200 MB |
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 usa mais ciclos de 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 do perfil de usuário do Windows do usuário. 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 estão disponíveis na 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 a conexão de sessão ser 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 qualquer operação na sessão pode ser executada. Quando o intervalo expira, a operaçã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; a operação continua indefinidamente.
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á Bloquear. 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
- Bloquear. Quando o buffer de saída estiver cheio, a execução será suspensa até que o buffer esteja limpo.
- Deixar cair. 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.
- Nenhum. 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 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 este parâmetro são:
- IEConfig
- WinHttpConfig
- AutoDetect
- NoProxyServer
- Nenhum
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 usado para resolução de proxy. Os valores aceitáveis para esse parâmetro são: Basic, Digeste Negotiate. O valor padrão é Negociar.
Para obter mais informações sobre os valores desse parâmetro, consulte de 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 serem usadas para autenticação de proxy. Insira uma variável que contenha um objeto
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 via HTTPS, o cliente não valida que o certificado do servidor é assinado por uma AC (autoridade de certificação) confiável.
Use essa opção somente quando o computador remoto for confiável usando outro mecanismo, como quando o computador remoto faz parte de uma rede fisicamente segura e isolada ou quando o computador remoto é listado como um host confiável em uma configuração do 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. Essa opção é usada somente em operações remotas que usam o protocolo HTTPS.
Use essa 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 do usuário a ser usada para a sessão.
Os valores válidos incluem:
- Um nome de cultura no formato
<languagecode2>-<country/regioncode2>
, comoja-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 definida no sistema operacional quando a sessão é criada é 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 |
-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
Não é possível redirecionar a entrada para este cmdlet.
Saídas
Observações
Se o parâmetro SessionOption não for usado em um comando para criar um de PSSession, as opções de sessão serão determinadas pelos valores de propriedade da variável de preferência $PSSessionOption
, se 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 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.