Set-PSSessionConfiguration
Altera as propriedades de uma configuração de sessão registrada.
Sintaxe
Set-PSSessionConfiguration [-AssemblyName] <string> [-ConfigurationTypeName] <string> [-Name] <string> [-ApplicationBase <string>] [-Force] [-MaximumReceivedDataSizePerCommandMB <double>] [-MaximumReceivedObjectSizeMB <double>] [-NoServiceRestart] [-SecurityDescriptorSDDL <string>] [-ShowSecurityDescriptorUI] [-StartupScript <string>] [-ThreadApartmentState {<STA> | <MTA> | <Unknown>}] [-ThreadOptions {<Default> | <UseNewThread> | <ReuseThread> | <UseCurrentThread>}] [-Confirm] [-WhatIf] [<CommonParameters>]
Descrição
O cmdlet Set-PSSessionConfiguration altera as propriedades das configurações de sessão registradas no computador local. Esse é um cmdlet avançado, projetado para ser usado pelos administradores de sistema para gerenciar as configurações de sessão personalizadas para seus usuários.
Use o parâmetro Name para identificar a configuraçã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), digite uma cadeia de caracteres vazia ("") ou um valor $null para o parâmetro correspondente.
Para ver as propriedades de uma configuração de sessão, use o cmdlet Get-PSSessionConfiguration ou o Provedor de WS-Management. Para obter mais informações sobre o Provedor de WS-Management, digite "Get-Help wsman".
Parâmetros
-ApplicationBase <string>
Altera o caminho do arquivo de assembly (*.dll) que é especificado no valor do parâmetro AssemblyName.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-AssemblyName <string>
Especifica um arquivo de assembly diferente para a configuração. Insira o caminho (opcional) e nome de um arquivo de assembly (.dll) que define o tipo de configuração.
Se você inserir somente o nome, poderá inserir o caminho no valor do parâmetro ApplicationBase.
Necessário? |
true |
Posição? |
2 |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-ConfigurationTypeName <string>
Especifica um arquivo tipo diferente para a configuração. O tipo que você especifica deve implementar a classe System.Management.Automation.Remoting.PSSessionConfiguration.
Se você inserir "$null" ou uma cadeia de caracteres vazia, a classe DefaultRemotePowerShellConfiguration será usada para a configuração de sessão.
Necessário? |
true |
Posição? |
3 |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Force
Suprime todos os avisos de usuário e reinicia o serviço WinRM sem aviso. A reinicialização do serviço torna efetiva a alteração da configuração.
Para impedir a reinicialização e suprimir o aviso de reinicialização, use o parâmetro NoServiceRestart.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-MaximumReceivedDataSizePerCommandMB <double>
Altera o limite na quantidade de dados que podem ser enviados a este computador em qualquer comando remoto individual. Insira o tamanho dos dados em megabytes (MB). O padrão é 50 MB.
Se um limite de tamanho dos dados for definido no tipo de configuração que é especificado no parâmetro ConfigurationTypeName, o limite no tipo de configuração será usado e o valor desse parâmetro será ignorado.
Necessário? |
false |
Posição? |
named |
Valor padrão |
50 |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-MaximumReceivedObjectSizeMB <double>
Altera o limite na quantidade de dados que podem ser enviados a este computador em qualquer objeto individual. Insira o tamanho dos dados em megabytes (MB). O padrão é 10 MB.
Se um limite de tamanho de objeto for definido no tipo de configuração que é especificado no parâmetro ConfigurationTypeName, o limite no tipo de configuração será usado e o valor desse parâmetro será ignorado.
Necessário? |
false |
Posição? |
named |
Valor padrão |
10 |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Name <string>
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.
Necessário? |
true |
Posição? |
1 |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-NoServiceRestart
Não reinicia o serviço WinRM e suprime o aviso para reiniciar o serviço.
Por padrão, quando você digita um comando Set-PSSessionConfiguration, é solicitado para reiniciar o serviço WinRM para tornar a nova configuração de sessão efetiva. Até o serviço WinRM ser reiniciado, a nova configuração de sessão não estará em vigor.
Para reiniciar o serviço WinRM sem aviso, use o parâmetro Force. Para reiniciar o serviço WinRM manualmente, use o cmdlet Restart-Service.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-SecurityDescriptorSDDL <string>
Especifica uma cadeia de caracteres SDDL (Linguagem de Definição do Descritor de Segurança) diferente para a configuração.
Essa cadeia de caracteres determina as permissões necessárias para usar a nova configuração de sessão. Para usar uma configuração em uma sessão, os usuários devem ter pelo menos a permissão "Executar(Invocar)" 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 é a raiz SDDL na unidade WSMan:.
Se o descritor de segurança for complexo, considere usar o parâmetro ShowSecurityDescriptorUI em vez dele. Você não pode usar ambos os parâmetros no mesmo comando.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-ShowSecurityDescriptorUI
Exibe uma folha de propriedades que o ajuda a criar um novo SDDL para a configuração de sessão. A folha de propriedades é exibida depois que você digita o comando Set-PSSessionConfiguration e reinicia o serviço WinRM.
Ao definir as permissões para a configuração, lembre-se de que os usuários devem ter pelo menos a permissão "Executar(Invocar)" para usar a configuração em uma sessão.
Você não pode usar esse parâmetro e o parâmetro SecurityDescriptorSDDL no mesmo comando.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-StartupScript <string>
Adiciona ou altera o script de inicialização da configuração. Insira o caminho totalmente qualificado para um script do Windows PowerShell. O script especificado é executado na nova sessão que usa 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 $null.
Você pode usar um script de inicialização fazer outras configurações na sessão do usuário. Se o script gerar um erro (até mesmo um erro de não-encerramento), a sessão não será criada e o comando New-PSSession do usuário falhará.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-ThreadApartmentState <ApartmentState>
Altera a configuração de estado apartment dos threads na sessão. Os valores válido são: STA, MTA e Unknown. O padrão é Unknown.
Necessário? |
false |
Posição? |
named |
Valor padrão |
ApartmentState.Unknown |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-ThreadOptions <PSThreadOptions>
Altera a configuração de opções de thread na configuração. Essa configuração define como os threads são criados e usados quando um comando é executado na sessão. Os valores válidos são: Default, ReuseThread, UseCurrentThread e UseNewThread. O padrão é UseCurrentThread.
Necessário? |
false |
Posição? |
named |
Valor padrão |
PSThreadOptions.UserCurrentThread |
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-Confirm
Solicita confirmação antes da execução do comando.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
-WhatIf
Descreve o que aconteceria se você executasse o comando, sem executá-lo de fato.
Necessário? |
false |
Posição? |
named |
Valor padrão |
|
Aceitar entrada do pipeline? |
false |
Aceitar caracteres curinga? |
false |
<CommonParameters>
Esse cmdlet oferece suporte aos parâmetros comuns: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer e -OutVariable. Para obter mais informações, consulte about_Commonparameters.
Entradas e saídas
O tipo de entrada é o tipo dos objetos que você pode canalizar para o cmdlet. O tipo de retorno é o tipo dos objetos que o cmdlet retorna.
Entradas |
Nenhum Você não pode canalizar a entrada para este cmdlet. |
Saídas |
Microsoft.WSMan.Management.WSManConfigLeafElement |
Observações
Para executar esse cmdlet no Windows Vista, no Windows Server 2008 e em versões mais recentes do Windows, abra o Windows PowerShell com a opção "Executar como administrador".
O cmdlet Set-PSSessionConfiguration não altera o nome de configuração e o provedor de WS-Management não dá suporte ao cmdlet Rename-Item. Para alterar o nome de uma configuração, use o cmdlet Unregister-PSSessionConfiguration para excluir a configuração e, em seguida, use o cmdlet Register-PSSessionConfiguration para criar e registrar uma nova configuração de sessão.
Você poderá usar o cmdlet Set-PSSessionConfiguration para alterar as configurações de sessão padrão Microsoft.PowerShell e Microsoft.PowerShell32. Elas não são protegidas. Para reverter à versão original de uma configuração de sessão padrão, use o cmdlet Unregister-PSSessionConfiguration para excluir a configuração de sessão padrão e, em seguida, use o cmdlet Enable-PSRemoting para restaurá-la.
Exemplo 1
C:\PS>set-pssessionconfiguration -name MaintenanceShell -threadApartmentState STA
Descrição
-----------
Esse comando altera o estado apartment do thread na configuração MaintenanceShell para STA. A alteração entra em vigor quando você reinicia o serviço WinRM.
Exemplo 2
C:\PS>register-pssessionconfiguration -name AdminShell -assemblyName c:\shells\AdminShell.dll -configurationType AdminClass
C:\PS> set-pssessionconfiguration -name AdminShell -startupScript AdminConfig.ps1
C:\PS> set-pssessionconfiguration -name AdminShell -startupScript $null
Descrição
-----------
Este exemplo mostra como criar e, em seguida, alterar uma configuração de sessão.
O primeiro comando usa o cmdlet Register-PSSessionConfiguration para criar a configuração AdminShell.
O segundo comando usa o cmdlet Set-PSSessionConfiguration para adicionar o script AdminConfig.ps1 à configuração. A alteração entra em vigor quando você reinicia o WinRM.
O terceiro comando remove o script AdminConfig.ps1 da configuração. Ele usa o cmdlet Set-PSSessionConfiguration com um valor $null para o parâmetro StartupScript.
Exemplo 3
C:\PS>Set-PSSessionConfiguration -name foo -MaximumReceivedObjectSizeMB 20
WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\foo\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
Descrição
-----------
Este exemplo mostra a saída de exemplo do cmdlet Set-PSSessionConfiguration.
O comando Set-PSSessionConfiguration neste exemplo aumenta o valor da propriedade MaximumReceivedObjectSizeMB para 20.
O comando Set-PSSessionConfiguration retorna um objeto Microsoft.WSMan.Management.WSManConfigLeafElement que mostra o nome do parâmetro e o novo valor.
Ele também solicita o reinício do serviço WinRM. A alteração de Set-PSSessionConfiguration não entra em vigor até o serviço WinRM ser reiniciado.
Exemplo 4
C:\PS>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
C:\PS> get-pssessionConfiguration maintenanceshell | format-list -property *
xmlns : https://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 : https://schemas.microsoft.com/powershell/MaintenanceShell
SupportsOptions : true
ExactMatch : true
Capability : {Shell}
Permission :
C:\PS> dir wsman:\localhost\plugin\MaintenanceShell\InitializationParameters
ParamName ParamValue
--------- ----------
PSVersion 2.0
startupscript c:\ps-test\Maintenance.ps1
Descrição
-----------
Esse comando mostra diferentes modos de exibir os resultados de um comando Set-PSSessionConfiguration.
O primeiro comando usa o cmdlet Set-PSSessionConfiguration para alterar o script de inicialização na configuração MaintenanceShell para Maintenance.ps1. A saída desse comando mostra a alteração e solicita que você reinicie o serviço WinRM. A resposta é "y" (sim).
O segundo comando usa o cmdlet Get-PSSessionConfiguration para obter a configuração de sessão MaintenanceShell. O comando usa um operador de pipeline (|) para enviar os resultados do comando para o cmdlet Format-List, que exibe todas as propriedades do objeto de configuração de sessão em uma lista.
O terceiro comando usa o provedor de WS-Management para exibir os parâmetros de inicialização para a configuração MaintenanceShell. O comando usa o cmdlet Get-ChildItem (alias = dir) para obter os itens filho no nó InitializationParameters para o plug-in MaintenanceShell.
Para obter mais informações sobre o provedor de WS-Management, digite "get-help wsman".
Consulte também
Conceitos
about_Session_Configurations
Disable-PSSessionConfiguration
Enable-PSSessionConfiguration
Get-PSSessionConfiguration
Register-PSSessionConfiguration
Unregister-PSSessionConfiguration
WSMan Provider