Compartilhar via

Set-PSSessionConfiguration

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

Altera as propriedades de uma configuração de sessão registrada.

Sintaxe

Set-PSSessionConfiguration
   [-Name] <String>
   [-ApplicationBase <String>]
   [-RunAsCredential <PSCredential>]
   [-ThreadApartmentState <ApartmentState>]
   [-ThreadOptions <PSThreadOptions>]
   [-AccessMode <PSSessionConfigurationAccessMode>]
   [-UseSharedProcess]
   [-StartupScript <String>]
   [-MaximumReceivedDataSizePerCommandMB <Double>]
   [-MaximumReceivedObjectSizeMB <Double>]
   [-SecurityDescriptorSddl <String>]
   [-ShowSecurityDescriptorUI]
   [-Force]
   [-NoServiceRestart]
   [-PSVersion <Version>]
   [-SessionTypeOption <PSSessionTypeOption>]
   [-TransportOption <PSTransportOption>]
   [-ModulesToImport <Object[]>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Set-PSSessionConfiguration
   [-Name] <String>
   [-AssemblyName] <String>
   [-ApplicationBase <String>]
   [-ConfigurationTypeName] <String>
   [-RunAsCredential <PSCredential>]
   [-ThreadApartmentState <ApartmentState>]
   [-ThreadOptions <PSThreadOptions>]
   [-AccessMode <PSSessionConfigurationAccessMode>]
   [-UseSharedProcess]
   [-StartupScript <String>]
   [-MaximumReceivedDataSizePerCommandMB <Double>]
   [-MaximumReceivedObjectSizeMB <Double>]
   [-SecurityDescriptorSddl <String>]
   [-ShowSecurityDescriptorUI]
   [-Force]
   [-NoServiceRestart]
   [-PSVersion <Version>]
   [-SessionTypeOption <PSSessionTypeOption>]
   [-TransportOption <PSTransportOption>]
   [-ModulesToImport <Object[]>]
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]
Set-PSSessionConfiguration
   [-Name] <String>
   [-RunAsCredential <PSCredential>]
   [-ThreadApartmentState <ApartmentState>]
   [-ThreadOptions <PSThreadOptions>]
   [-AccessMode <PSSessionConfigurationAccessMode>]
   [-UseSharedProcess]
   [-StartupScript <String>]
   [-MaximumReceivedDataSizePerCommandMB <Double>]
   [-MaximumReceivedObjectSizeMB <Double>]
   [-SecurityDescriptorSddl <String>]
   [-ShowSecurityDescriptorUI]
   [-Force]
   [-NoServiceRestart]
   [-TransportOption <PSTransportOption>]
   -Path <String>
   [-WhatIf]
   [-Confirm]
   [<CommonParameters>]

Description

O Set-PSSessionConfiguration cmdlet altera as propriedades das configurações de sessão no computador local.

Use o parâmetro Name para identificar a configuração da sessão que você deseja alterar. Use os outros parâmetros para especificar novos valores para as propriedades da configuração de sessão. Para excluir um valor de propriedade da configuração e usar o valor padrão, insira uma string vazia ("") ou um valor de $Null para o parâmetro correspondente.

A partir do PowerShell 3.0, você pode usar um arquivo de configuração de sessão para definir uma configuração de sessão. Esse recurso fornece um método simples e detectável para definir ou alterar as propriedades de sessões que usam a configuração de sessão. Para especificar um arquivo de configuração de sessão, use o parâmetro Path de Set-PSSessionConfiguration. Para obter informações sobre arquivos de configuração de sessão, consulte about_Session_Configuration_Files. Para obter informações sobre como criar e modificar um arquivo de configuração de sessão, consulte o New-PSSessionConfigurationFile cmdlet.

As configurações de sessão definem o ambiente de sessões remotas (PSSessions) que se conectam ao computador local. Cada PSSession usa uma configuração de sessão. A configuração da sessão determina os recursos do PSSession, como os módulos que estão disponíveis na sessão, os cmdlets que têm permissão para serem executados, o modo de idioma, cotas e tempos limite. O descritor de segurança da configuração da sessão determina quem pode usar a configuração da sessão para se conectar ao computador local. Para saber mais sobre configurações de sessão, confira about_Session_Configurations.

Para ver as propriedades de uma configuração de sessão, use o Get-PSSessionConfiguration cmdlet ou o Provedor WSMan. Para obter mais informações sobre o Provedor WSMan, digite Get-Help WSMan.

Exemplos

Exemplo 1: Alterar o estado do apartamento do thread

PS C:\> Set-PSSessionConfiguration -Name "MaintenanceShell" -ThreadApartmentState STA

Esse comando altera o estado de apartment do thread na configuração MaintenanceShell para STA. A alteração entra em vigor quando você reinicia o serviço WinRM .

Exemplo 2: Criar e alterar uma configuração de sessão

Este exemplo mostra como adicionar e remover um script de inicialização de uma configuração.

O primeiro comando cria a configuração do AdminShell . O segundo comando adiciona o AdminConfig.ps1 script à configuração. A alteração entra em vigor quando você reinicia o WinRM. O terceiro comando remove o AdminConfig.ps1 script da configuração.

Register-PSSessionConfiguration -Name "AdminShell" -AssemblyName "C:\Shells\AdminShell.dll" -ConfigurationTypeName "AdminClass"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript "AdminConfig.ps1"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript $Null

Exemplo 3: Exibir resultados

Este exemplo aumenta o valor da propriedade MaximumReceivedObjectSizeMB para 20. Esse comando também solicita que você reinicie o serviço WinRM . A alteração não entra em vigor até que o serviço WinRM seja reiniciado.

Set-PSSessionConfiguration -Name "IncObj" -MaximumReceivedObjectSizeMB 20

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\IncObj\InitializationParameters

ParamName                       ParamValue
---------                       ----------
psmaximumreceivedobjectsizemb   20

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run the command "restart-service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

Exemplo 3: Exibir resultados de maneiras diferentes

Neste exemplo, Set-PSSessionConfiguration o altera o script de inicialização na configuração da sessão do MaintenanceShell para Maintenance.ps1. A saída mostra a alteração e solicita que você reinicie o serviço WinRM . A resposta é y (sim).

Get-PSSessionConfiguration obtém a configuração da sessão do MaintenanceShell . O operador de pipeline (|) envia os resultados do comando para Format-List, que exibe todas as propriedades do objeto de configuração em uma lista. Em seguida, usando o provedor WSMan, exibimos os parâmetros de inicialização para a configuração do MaintenanceShell . Get-ChildItem obtém os itens filho no nó InitializationParameters para o plug-in MaintenanceShell . Para obter mais informações sobre o provedor WSMan, digite Get-Help wsman.

Set-PSSessionConfiguration -Name "MaintenanceShell" -StartupScript "C:\ps-test\Maintenance.ps1"

WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell\InitializationParameters

ParamName            ParamValue
---------            ----------
startupscript        c:\ps-test\Mainte...

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run
the command "restart-service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

Get-PSSessionConfiguration MaintenanceShell | Format-List -Property *

xmlns            : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration
Name             : MaintenanceShell
Filename         : %windir%\system32\pwrshplugin.dll
SDKVersion       : 1
XmlRenderingType : text
lang             : en-US
PSVersion        : 2.0
startupscript    : c:\ps-test\Maintenance.ps1
ResourceUri      : http://schemas.microsoft.com/powershell/MaintenanceShell
SupportsOptions  : true
ExactMatch       : true
Capability       : {Shell}
Permission       :

Get-ChildItem WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters

ParamName     ParamValue
---------     ----------
PSVersion     2.0
startupscript c:\ps-test\Maintenance.ps1

Parâmetros

-AccessMode

Habilita e desabilita a configuração da sessão e determina se ela pode ser usada para sessões locais ou remotas no computador. Os valores aceitáveis para esse parâmetro são:

  • Disabled. Desabilita a configuração da sessão. Ele não pode ser usado para acesso remoto ou local no computador. Esse valor define a propriedade Enabled da configuração da sessão (WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled) como False.
  • Local. Adiciona uma entrada Network_Deny_All ao descritor de segurança da configuração da sessão. Os usuários do computador local podem usar a configuração da sessão para criar uma sessão de loopback local no mesmo computador, mas o acesso é negado aos usuários remotos.
  • Remote. Remove entradas Deny_All e Network_Deny_All dos descritores de segurança da configuração da sessão. Usuários de computadores locais e remotos podem usar a configuração da sessão para criar sessões e executar comandos nesse computador.

O valor padrão é Remoto.

Outros cmdlets podem substituir o valor desse parâmetro posteriormente. Por exemplo, o cmdlet habilita Enable-PSRemoting todas as configurações de sessão no computador e permite acesso remoto a elas, e o Disable-PSRemoting cmdlet permite apenas acesso local a todas as configurações de sessão no computador.

Esse parâmetro foi introduzido no PowerShell 3.0.

Tipo:PSSessionConfigurationAccessMode
Valores aceitos:Disabled, Local, Remote
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ApplicationBase

Especifica o caminho do arquivo de assembly (*.dll) especificado no valor do parâmetro AssemblyName .

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

-AssemblyName

Especifica o nome do assembly. Esse cmdlet cria uma configuração de sessão com base em uma classe definida em um assembly.

Insira o nome do arquivo ou o caminho completo de um arquivo de assembly .dll que define uma configuração de sessão. Se você inserir apenas o nome do arquivo, poderá inserir o caminho no valor do parâmetro ApplicationBase .

Tipo:String
Cargo:1
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ConfigurationTypeName

Especifica o tipo de configuração de sessão definida no assembly no parâmetro AssemblyName . O tipo especificado deve implementar a classe System.Management.Automation.Remoting.PSSessionConfiguration .

Esse parâmetro é necessário quando você especifica um nome de assembly.

Tipo:String
Cargo:2
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Confirm

Solicita sua confirmação antes de executar o cmdlet.

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

-Force

Suprime todos os prompts do usuário e reinicia o serviço WinRM sem avisar. Reiniciar o serviço faz a com que a alteração da configuração entre em vigor.

Para evitar uma reinicialização e suprimir o prompt de reinicialização, use o parâmetro NoServiceRestart .

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

-MaximumReceivedDataSizePerCommandMB

Especifica o limite da quantidade de dados que podem ser enviados para este computador em qualquer comando remoto único. Insira o tamanho dos dados em megabytes (MB). O padrão é 50.

Se um limite de tamanho de dados for definido no tipo de configuração especificado no parâmetro ConfigurationTypeName , o limite no tipo de configuração será usado. O valor desse parâmetro é ignorado.

Tipo:Nullable<T>[Double]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-MaximumReceivedObjectSizeMB

Especifica os limites da quantidade de dados que podem ser enviados para este computador em qualquer objeto único. Insira o tamanho dos dados em megabytes. O padrão é 10.

Se um limite de tamanho de objeto for definido no tipo de configuração especificado no parâmetro ConfigurationTypeName , o limite no tipo de configuração será usado. O valor desse parâmetro é ignorado.

Tipo:Nullable<T>[Double]
Cargo:Named
Valor padrão:10
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ModulesToImport

Especifica os módulos e snap-ins que são importados automaticamente nas sessões que usam a configuração de sessão. Digite os nomes de módulo e o snap-in.

Por padrão, apenas o módulo Microsoft.PowerShell.Core é importado para sessões, mas, a menos que os cmdlets sejam excluídos, você pode usar os Import-Module cmdlets e Add-PSSnapin para adicionar módulos e snap-ins à sessão.

Os módulos especificados neste valor de parâmetro são importados em adições aos módulos especificados no arquivo de configuração de sessão (New-PSSessionConfigurationFile). No entanto, as configurações no arquivo de configuração de sessão podem ocultar os comandos exportados por módulos ou impedir os usuários de utilizá-los.

Os módulos especificados nesse valor de parâmetro substituem a lista de módulos especificados pelo parâmetro ModulesToImport do Register-PSSessionConfiguration cmdlet.

Esse parâmetro foi introduzido no PowerShell 3.0.

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

-Name

Especifica o nome da configuração de sessão que você deseja alterar.

Você não pode usar esse parâmetro para alterar o nome da configuração de sessão.

Tipo:String
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-NoServiceRestart

Não reinicia o serviço WinRM e suprime o prompt para reiniciar o serviço.

Por padrão, quando você executa Set-PSSessionConfigurationo , é solicitado que você reinicie o serviço WinRM para tornar a nova configuração de sessão efetiva. Até que o serviço WinRM seja reiniciado, a nova configuração de sessão não será efetiva.

Para reiniciar o serviço WinRM sem avisar, use o parâmetro Force . Para reiniciar o serviço WinRM manualmente, use o Restart-Service cmdlet.

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

-Path

Especifica o caminho de um arquivo de configuração de sessão (.pssc), como um criado pelo New-PSSessionConfigurationFile cmdlet. Se você omitir o caminho, o padrão será o diretório atual.

Para obter informações sobre como modificar um arquivo de configuração de sessão, consulte o tópico de ajuda do New-PSSessionConfigurationFile cmdlet.

Esse parâmetro foi introduzido no PowerShell 3.0.

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

-PSVersion

Especifica a versão do PowerShell em sessões que usam essa configuração de sessão.

O valor desse parâmetro tem precedência sobre o valor da chave PowerShellVersion no arquivo de configuração da sessão.

Esse parâmetro foi introduzido no PowerShell 3.0.

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

-RunAsCredential

Especifica credenciais para comandos na sessão. Por padrão, os comandos são executados com as permissões do usuário atual.

Esse parâmetro foi introduzido no PowerShell 3.0.

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

-SecurityDescriptorSddl

Especifica uma cadeia de caracteres SDDL (Security Descriptor Definition Language) diferentes para a configuração.

Essa cadeia de caracteres determina as permissões que são necessárias para usar a nova configuração de sessão. Para usar uma configuração de sessão em uma sessão, os usuários devem ter pelo menos Execute(Invoke) permissão para a configuração.

Para usar o descritor de segurança padrão para a configuração, insira uma string vazia ("") ou um valor de $Null. O padrão é o SDDL raiz na WSMan: unidade.

Se o descritor de segurança for complexo, considere usar o parâmetro ShowSecurityDescriptorUI em vez deste. Não é possível usar ambos os parâmetros no mesmo comando.

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

-SessionTypeOption

Especifica opções específicas de tipo para a configuração da sessão. Insira um objeto de opções de tipo de sessão, como o objeto PSWorkflowExecutionOption que o New-PSWorkflowExecutionOption cmdlet retorna.

As opções de sessões que usam a configuração de sessão são determinadas pelos valores das opções de sessão e pelas opções de configuração de sessão. A menos que especificado, as opções definidas na sessão, como com o New-PSSessionOption cmdlet, têm precedência sobre as opções definidas na configuração da sessão. No entanto, valores de opção de sessão não podem ultrapassar os valores máximos definidos na configuração da sessão.

Esse parâmetro foi introduzido no PowerShell 3.0.

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

-ShowSecurityDescriptorUI

Quando esse parâmetro é usado, o cmdlet abre uma folha de propriedades que ajuda você a criar um novo SDDL para a configuração da sessão. A folha de propriedades aparece depois que você executa o Set-PSSessionConfiguration comando e reinicia o serviço WinRM .

Ao definir permissões para a configuração, lembre-se de que os usuários devem ter pelo menos Execute(Invoke) permissão para usar a configuração da sessão em uma sessão.

Você não pode usar o parâmetro SecurityDescriptorSDDL e esse parâmetro no mesmo comando.

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

-StartupScript

Especifica o script de inicialização para a configuração. Insira o caminho totalmente qualificado de um script do PowerShell. O script especificado é executado na nova sessão que usar a configuração de sessão.

Para excluir um script de inicialização de uma configuração de sessão, insira uma string vazia ("") ou um valor de $Null.

Você pode usar um script de inicialização para configurar ainda mais a sessão do usuário. Se o script gerar um erro, mesmo um erro não finalizado, a sessão não será criada e o New-PSSession comando falhará.

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

-ThreadApartmentState

Especifica o estado do apartamento do módulo de threading a ser usado. Os valores aceitáveis são:

  • Unknown
  • MTA
  • STA
Tipo:ApartmentState
Valores aceitos:STA, MTA, Unknown
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ThreadOptions

Especifica a configuração de opções de thread na configuração. Essa configuração define como threads são criados e usados quando um comando é executado na sessão. Os valores aceitáveis para esse parâmetro são:

  • Default
  • ReuseThread
  • UseCurrentThread
  • UseNewThread

O valor padrão é UseCurrentThread.

Para obter mais informações, consulte Enumeração PSThreadOptions.

Tipo:PSThreadOptions
Valores aceitos:Default, UseNewThread, ReuseThread, UseCurrentThread
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-TransportOption

Especifica as opções de transporte para a configuração da sessão. Insira um objeto de opções de transporte, como o objeto WSManConfigurationOption que o New-PSTransportOption cmdlet retorna.

As opções de sessões que usam a configuração de sessão são determinadas pelos valores das opções de sessão e pelas opções de configuração de sessão. A menos que especificado, as opções definidas na sessão, como com o New-PSSessionOption cmdlet, têm precedência sobre as opções definidas na configuração da sessão. No entanto, valores de opção de sessão não podem ultrapassar os valores máximos definidos na configuração da sessão.

Esse parâmetro foi introduzido no PowerShell 3.0.

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

-UseSharedProcess

Use somente um processo para hospedar todas as sessões que são iniciadas pelo mesmo usuário e usam a mesma configuração de sessão. Por padrão, cada sessão é hospedada em seu próprio processo.

Esse parâmetro foi introduzido no PowerShell 3.0.

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

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

Tipo:SwitchParameter
Aliases:wi
Cargo:Named
Valor padrão:False
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

WSManConfigLeafElement

Observações

Para executar esse cmdlet, inicie o PowerShell usando a opção Executar como administrador .

O Set-PSSessionConfiguration cmdlet não altera o nome da configuração e o provedor WSMan não dá suporte ao Rename-Item cmdlet. Para alterar o nome de uma configuração de sessão, use o Unregister-PSSessionConfiguration cmdlet para excluir a configuração e, em seguida, use o Register-PSSessionConfiguration cmdlet para criar e registrar uma nova configuração de sessão.

Você pode usar o Set-PSSessionConfiguration cmdlet para alterar as configurações padrão Microsoft.PowerShell e Microsoft.PowerShell32 de sessão. Elas não são protegidas. Para reverter para a versão original de uma configuração de sessão padrão, use o Unregister-PSSessionConfiguration cmdlet para excluir a configuração de sessão padrão e, em seguida, use o Enable-PSRemoting cmdlet para restaurá-la.

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.

Você pode usar comandos na WSMan: unidade para alterar as propriedades das configurações da sessão. No entanto, você não pode usar a unidade no PowerShell 2.0 para alterar as WSMan: propriedades de configuração de sessão introduzidas no PowerShell 3.0, como OutputBufferingMode. Os comandos do Windows PowerShell 2.0 não geram um erro, mas são ineficazes. Para alterar as propriedades introduzidas no PowerShell 3.0, use a WSMan: unidade no PowerShell 3.0 ou posterior.