Set-PSSessionConfiguration

Artigo
10/30/2009

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

Compartilhar via