Set-PSSessionConfiguration

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

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

Syntax

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 cadeia de caracteres 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 executar, o modo de idioma, cotas e tempos limites. 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 de 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 é efetiva quando você reiniciar 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 AdminShell . O segundo comando adiciona o AdminConfig.ps1 script à configuração. A alteração é efetiva quando você reiniciar 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 é efetiva até que o serviço WinRM é 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 altera o script de inicialização na configuração da sessão 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 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 aos usuários remotos é negado.
  • 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 é Remote.

Outros cmdlets podem substituir o valor desse parâmetro posteriormente. Por exemplo, o Enable-PSRemoting cmdlet habilita 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.

Type:PSSessionConfigurationAccessMode
Accepted values:Disabled, Local, Remote
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ApplicationBase

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

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

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

Type:String
Position:2
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Confirm

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

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters: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 impedir uma reinicialização e suprimir o prompt de reinicialização, use o parâmetro NoServiceRestart .

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

-MaximumReceivedDataSizePerCommandMB

Especifica o limite na quantidade de dados que podem ser enviados para este computador em qualquer comando remoto. 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.

Type:Nullable<T>[Double]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumReceivedObjectSizeMB

Especifica os limites da quantidade de dados que podem ser enviados para este computador em qualquer objeto. 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.

Type:Nullable<T>[Double]
Position:Named
Default value:10
Required:False
Accept pipeline input:False
Accept wildcard characters: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, somente 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 da 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.

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

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters: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 , você será solicitado a reiniciar 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 é efetiva.

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

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

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

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

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

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 retornado New-PSWorkflowExecutionOption pelo cmdlet.

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.

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

-ShowSecurityDescriptorUI

Quando esse parâmetro é usado, o cmdlet abre uma folha de propriedades que ajuda a criar um novo SDDL para a configuração da sessão. A folha de propriedades aparece depois de executar o Set-PSSessionConfiguration comando e, em seguida, reinicie 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 de sessão em uma sessão.

Não é possível usar o parâmetro SecurityDescriptorSDDL e esse parâmetro no mesmo comando.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 cadeia de caracteres 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 de não encerramento, a sessão não será criada e o New-PSSession comando falhará.

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

-ThreadApartmentState

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

  • Unknown
  • MTA
  • STA
Type:ApartmentState
Accepted values:STA, MTA, Unknown
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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.

Type:PSThreadOptions
Accepted values:Default, UseNewThread, ReuseThread, UseCurrentThread
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters: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 retornado pelo New-PSTransportOption cmdlet.

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.

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

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

-WhatIf

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

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

Entradas

None

Não é possível 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 oferece 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 de sessão. No entanto, você não pode usar a unidade no PowerShell 2.0 para alterar as propriedades de configuração de WSMan: sessão que sã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.