Set-PSSessionConfiguration
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 cmdlet Set-PSSessionConfiguration
altera as propriedades das configurações de sessão no computador local.
Use o parâmetro Name para identificar a configuração de sessão que você deseja alterar. Use os outros parâmetros para especificar novos valores para as propriedades da configuração da 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 e alterar as propriedades das sessões que usam a configuração da 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 cmdlet New-PSSessionConfigurationFile
.
As configurações de sessão definem o ambiente de sessões remotas (PSSessions) que se conectam ao computador local. Cada de PSSession usa uma configuração de sessão. A configuração da sessão determina os recursos do PSSession, como os módulos disponíveis na sessão, os cmdlets que têm permissão para execução, o modo de idioma, cotas e tempos limite. O descritor de segurança da configuração de sessão determina quem pode usar a configuração de sessão para se conectar ao computador local. Para obter mais informações sobre configurações de sessão, consulte about_Session_Configurations.
Para ver as propriedades de uma configuração de sessão, use o cmdlet Get-PSSessionConfiguration
ou o Provedor WSMan. Para obter mais informações sobre o provedor WSMan, digite Get-Help WSMan
.
Exemplos
Exemplo 1: alterar o estado do thread apartment
PS C:\> Set-PSSessionConfiguration -Name "MaintenanceShell" -ThreadApartmentState STA
Esse comando altera o estado do thread apartment na configuração do MaintenanceShell para STA.
A alteração é efetiva quando você reinicia o serviço de
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 de do AdminConfig.ps1
à configuração. A alteração é efetiva quando você reinicia do WinRM.
O terceiro comando remove o script AdminConfig.ps1
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 de do WinRM
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 4: Exibir resultados de maneiras diferentes
Neste exemplo,
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 deGet-Help wsman
.
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
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 :
PS> dir 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 remotas ou locais no computador. Os valores aceitáveis para este parâmetro são:
- Desactivado. Desabilita a configuração da sessão. Ele não pode ser usado para acesso remoto ou local ao computador. Esse valor define a propriedade Enabled da configuração de sessão (
WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled
) como False. - Local. Adiciona uma entrada Network_Deny_All ao descritor de segurança da configuração de sessão. Os usuários do computador local podem usar a configuração de sessão para criar uma sessão de loopback local no mesmo computador, mas os usuários remotos têm acesso negado.
- Remoto. Remove entradas Deny_All e Network_Deny_All dos descritores de segurança da configuração da sessão. Os usuários de computadores locais e remotos podem usar a configuração de sessão para criar sessões e executar comandos neste computador.
O valor padrão é Remote.
Outros cmdlets podem substituir o valor desse parâmetro posteriormente. Por exemplo, o cmdlet Enable-PSRemoting
habilita todas as configurações de sessão no computador e permite acesso remoto a elas, e o cmdlet Disable-PSRemoting
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 assembly .dll arquivo 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 da configuração de sessão definida no assembly no parâmetro AssemblyName
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 a 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
Para impedir uma reinicialização e suprimir o prompt de reinicialização, use o parâmetro
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 MB.
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: | 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 MB.
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: | Double |
Cargo: | Named |
Valor padrão: | None |
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 para sessões que usam a configuração da sessão. Insira os nomes de módulo e snap-in.
Por padrão, somente o snap-in Microsoft.PowerShell.Core é importado para sessões, mas, a menos que os cmdlets sejam excluídos, você pode usar os cmdlets Import-Module
e Add-PSSnapin para adicionar módulos e snap-ins à sessão.
Os módulos especificados nesse valor de parâmetro são importados em adições a 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 que os usuários os usem.
Os módulos especificados nesse valor de parâmetro substituem a lista de módulos especificados usando o parâmetro ModulesToImport do cmdlet Register-PSSessionConfiguration
.
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 da 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
Por padrão, ao executar
Para reiniciar o serviço
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 cmdlet New-PSSessionConfigurationFile
. 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 cmdlet New-PSSessionConfigurationFile
.
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
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 as 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 (Linguagem de Definição de 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 de sessã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 é o SDDL raiz na unidade WSMan: .
Se o descritor de segurança for complexo, considere usar o parâmetro ShowSecurityDescriptorUI em vez deste. Você não pode 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 cmdlet New-PSWorkflowExecutionOption
retorna.
As opções de sessões que usam a configuração da sessão são determinadas pelos valores das opções de sessão e das opções de configuração de sessão. A menos que especificado, as opções definidas na sessão, como usando o cmdlet New-PSSessionOption
, têm precedência sobre as opções definidas na configuração da sessão. No entanto, os valores de opção de sessão não podem exceder 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
Indica que esse cmdlet é uma folha de propriedades que ajuda você a criar um novo SDDL para a configuração da sessão. A folha de propriedades é exibida depois que você executa o comando
Ao definir permissões para a configuração, lembre-se de que os usuários devem ter pelo menos permissão Execute(Invoke) para usar a configuração de sessão em uma sessão.
Não é possível usar o parâmetro
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 usa a configuração da 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 comando New-PSSession
falhará.
Tipo: | String |
Cargo: | Named |
Valor padrão: | None |
Obrigatório: | False |
Aceitar a entrada de pipeline: | False |
Aceitar caracteres curinga: | False |
-ThreadApartmentState
Especifica a configuração de estado do apartamento para os threads na sessão. Os valores aceitáveis para esse parâmetro são: STA, MTA e Unknown. O valor padrão é Desconhecido.
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 os threads são criados e usados quando um comando é executado na sessão. Os valores aceitáveis para este parâmetro são:
- Inadimplência
- ReuseThread
- UseCurrentThread
- UseNewThread
O valor padrão é UseCurrentThread.
Para obter mais informações, consulte de 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
As opções de sessões que usam a configuração da sessão são determinadas pelos valores das opções de sessão e das opções de configuração de sessão. A menos que especificado, as opções definidas na sessão, como usando o cmdlet New-PSSessionOption
, têm precedência sobre as opções definidas na configuração da sessão. No entanto, os valores de opção de sessão não podem exceder 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 apenas um processo para hospedar todas as sessões iniciadas pelo mesmo usuário e usar 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
Não é possível redirecionar a entrada para este cmdlet.
Saídas
Observações
Para executar esse cmdlet, inicie o PowerShell usando a opção Executar como administrador.
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ê pode usar o cmdlet Set-PSSessionConfiguration
para alterar as configurações de sessão padrão do Microsoft.PowerShell e do Microsoft.PowerShell32. Eles não estão protegidos. Para reverter para a 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.
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.
Você pode usar comandos no WSMan: unidade para alterar as propriedades das configurações de sessão. No entanto, não é possível usar a unidade WSMan: no PowerShell 2.0 para alterar as 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 unidade WSMan: no PowerShell 3.0.
Links Relacionados
- Disable-PSSessionConfiguration
- Enable-PSSessionConfiguration
- Get-PSSessionConfiguration
- New-PSSessionConfigurationFile
- New-PSSessionOption
- New-PSTransportOption
- New-PSWorkflowExecutionOption
- Register-PSSessionConfiguration
- Test-PSSessionConfigurationFile
- Unregister-PSSessionConfiguration
- Provedor WSMan
- about_Session_Configurations
- about_Session_Configuration_Files