Register-PSSessionConfiguration

Artigo
10/30/2009

Cria e registra uma nova configuração de sessão.

Sintaxe

Register-PSSessionConfiguration [-AssemblyName] <string> [-ConfigurationTypeName] <string> [-ApplicationBase <string>] [-Name] <string> [-Force] [-MaximumReceivedDataSizePerCommandMB <double>] [-MaximumReceivedObjectSizeMB <double>] [-NoServiceRestart] [-ProcessorArchitecture <string>] [-SecurityDescriptorSDDL <string>] [-ShowSecurityDescriptorUI] [-StartupScript <string>] [-ThreadApartmentState {<STA> | <MTA> | <Unknown>}] [-ThreadOptions {<Default> | <UseNewThread> | <ReuseThread> | <UseCurrentThread>}] [-Confirm] [-WhatIf] [<CommonParameters>]

Descrição

O cmdlet Register-PSSessionConfiguration cria e registra uma nova configuração de sessão 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.

Todas as sessões remotas do Windows PowerShell usam uma configuração de sessão. Quando os usuários criam uma sessão que se conecta ao computador, eles podem selecionar uma configuração ou usar as configurações padrão que são registradas quando você habilita a comunicação remota do Windows PowerShell. Os usuários também podem definir uma variável de preferência $PSSessionConfigurationName, que especifica uma configuração padrão para as sessões criadas na sessão atual.

A configuração de sessão define o ambiente da sessão. Você poderá definir a configuração usando um assembly que implementa uma nova classe de configuração e usando um script que é executado na sessão. A configuração pode determinar os comandos que estão disponíveis na sessão e incluir configurações que protegem o computador, como aquelas que limitam a quantidade de dados que a sessão pode receber remotamente em um único objeto ou comando. Você também pode especificar um descritor de segurança que determina as permissões necessárias a serem usadas na configuração.

Parâmetros

-ApplicationBase <string>

Especifica o caminho do arquivo de assembly (*.dll) que é especificado no valor do parâmetro AssemblyName. Use esse parâmetro quando o valor do parâmetro AssemblyName não incluir um caminho. O padrão é o diretório atual.

Necessário?	false
Posição?	named
Valor padrão	Diretório atual
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-AssemblyName <string>

Especifica o nome de um arquivo de assembly (*.dll) em que o tipo de configuração é definido. Você pode especificar o caminho do arquivo .dll neste parâmetro ou no valor do parâmetro ApplicationBase.

Esse parâmetro é necessário quando o parâmetro ConfigurationTypeName é especificado.

Necessário?	true
Posição?	2
Valor padrão	Nenhum
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ConfigurationTypeName <string>

Especifica o nome totalmente qualificado do tipo do Microsoft .NET Framework que é usado para esta configuração. O tipo que você especifica deve implementar a classe System.Management.Automation.Remoting.PSSessionConfiguration.

Para especificar o arquivo de assembly (.dll) que implementa o tipo de configuração, use os parâmetros AssemblyName e AssemblyBase.

A criação de um tipo permite que você controle mais aspectos da configuração de sessão, como a exposição ou ocultação de certos parâmetros de cmdlets, ou a configuração de limites de tamanho dos dados e objetos que os usuários não podem substituir.

Se você omitir esse parâmetro, a classe DefaultRemotePowerShellConfiguration será usada para a configuração de sessão.

Necessário?	true
Posição?	3
Valor padrão	System.Management.Automation.Remoting.PSSessionConfiguration
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-Force

Suprime todos os avisos de usuários 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>

Limita a 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>

Limita a 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 um nome para a configuração de sessão. Esse parâmetro é obrigatório.

Necessário?	true
Posição?	1
Valor padrão	Nenhum
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 Register-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	False
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ProcessorArchitecture <string>

Especifica uma arquitetura de processador para a configuração. Esse valor determina se uma versão de 32 bits ou de 64 bits do processo que hospeda o Windows PowerShell será iniciada quando a configuração for usada. Os valores válidos são: x86, AMD64 e IA64.

O padrão é determinado pela arquitetura de processador do computador que hospeda a configuração de sessão.

Necessário?	false
Posição?	named
Valor padrão	A arquitetura de processador do computador host.
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) 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.

Se o descritor de segurança for complexo, considere usar o parâmetro ShowSecurityDescriptorUI em vez desse parâmetro. Você não pode usar ambos os parâmetros no mesmo comando.

Se você omitir esse parâmetro, a raiz SDDL do serviço WinRM será usada para a configuração. Para exibir ou alterar a raiz SDDL, use o provedor de WS-Management. Por exemplo "Get-Item wsman:\localhost\service\rootSDDL". Para obter mais informações sobre o provedor de WS-Management, digite "Get-Help wsman".

Necessário?	false
Posição?	named
Valor padrão	O valor da raiz SDDL
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ShowSecurityDescriptorUI

Exibe uma folha de propriedades que o ajuda a criar o SDDL para a configuração de sessão. A folha de propriedades é exibida depois que você digita o comando Register-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>

Especifica 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.

Você pode usar o script fazer outras configurações na sessão. 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>

Determina o 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	Desconhecido
Aceitar entrada do pipeline?	false
Aceitar caracteres curinga?	false

-ThreadOptions <PSThreadOptions>

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	UseCurrentThread
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.WSManConfigContainerElement

Observações

Para executar esse cmdlet no Windows Vista, no Windows Server 2008 e em versões mais recentes do Windows, inicie o Windows PowerShell com a opção "Executar como administrador".

Esse cmdlet gera o XML que representa uma configuração do plug-in WS-Management (Web Services for Management) e envia o XML ao WS-Management, que registra o plug-in no computador local ("new-item wsman:\localhost\plugin").

Exemplo 1

C:\PS>register-pssessionConfiguration -name NewShell -applicationBase c:\MyShells\ -assemblyName MyShell.dll -configurationTypeName MyClass

Descrição
-----------
Esse comando registra a configuração de sessão NewShell. Ele usa os parâmetros ApplicationName e ApplicationBase para especificar o local do arquivo MyShell.dll, que especifica os cmdlets e provedores na configuração de sessão. Ele usa também o parâmetro ConfigurationTypeName para especificar uma nova classe que faz outras configurações na sessão.

Para usar essa configuração, os usuários digitariam "new-pssession -configurationname newshell".

Exemplo 2

C:\PS>register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1

Descrição
-----------
Esse comando registra a configuração MaintenanceShell no computador local. O comando usa o parâmetro StartupScript para especificar o script Maintenance.ps1.

Quando um usuário utiliza um comando New-PSSession e seleciona a configuração MaintenanceShell, o script Maintenance.ps1 é executado na nova sessão. O script pode configurar a sessão, inclusive importar módulos, adicionando snap-ins do Windows PowerShell e definindo a diretiva de execução para a sessão. Se o script gerar quaisquer erros, inclusive erros de não-encerramento, o comando New-PSSession falhará.

Exemplo 3

C:\PS>$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FA;SA;GWGX;;WD)"

C:\PS> register-pssessionconfiguration -name AdminShell -securityDescriptorSDDL $sddl -maximumReceivedObjectSizeMB 20 -startupScript c:\scripts\AdminShell.ps1

Descrição
-----------
Este exemplo registra a configuração de sessão AdminShell. 

O primeiro comando salva um SDDL personalizado na variável $sddl. 

O segundo comando registra o novo shell. O comando usa o parâmetro SecurityDescritorSDDL para especificar o SDDL no valor da variável $sddl e o parâmetro MaximumReceivedObjectSizeMB para aumentar o limite de tamanho de objeto. Ele usa também o parâmetro StartupScript para especificar um script que configura a sessão.

Como uma alternativa ao uso do parâmetro SecurityDescriptorSDDL, você poderá usar o parâmetro ShowSecurityDescriptorUI, que exibe uma folha de propriedades que você pode usar para definir permissões para a configuração de sessão. Quando você clicar em "OK" na folha de propriedades, a ferramenta gerará um SDDL para a configuração de sessão.

Exemplo 4

C:\PS>$s = register-pssessionConfiguration -name MaintenanceShell -startupScript c:\ps-test\Maintenance.ps1

C:\PS> $s

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

Name                      Type                 Keys
----                      ----                 ----
MaintenanceShell          Container            {Name=MaintenanceShell}


C:\PS> $s.getType().fullname
TypeName: Microsoft.WSMan.Management.WSManConfigContainerElement


C:\PS> $s | format-list -property *

PSPath            : Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell
PSParentPath      : Microsoft.WSMan.Management\WSMan::localhost\Plugin
PSChildName       : MaintenanceShell
PSDrive           : WSMan
PSProvider        : Microsoft.WSMan.Management\WSMan
PSIsContainer     : True
Keys              : {Name=MaintenanceShell}
Name              : MaintenanceShell
TypeNameOfElement : Container


C:\PS> dir wsman:\localhost\plugin

Name                      Type                 Keys
----                      ----                 ----
MaintenanceShell          Container            {Name=MaintenanceShell}
microsoft.powershell      Container            {Name=microsoft.powershell}
microsoft.powershell32    Container            {Name=microsoft.powershell32}

Descrição
-----------
Este exemplo mostra que um comando Register-PSSessionConfiguration retorna um WSManConfigContainerElement. Mostra também como localizar os elementos de contêiner na unidade WSMan:.

O primeiro comando usa o cmdlet Register-PSSessionConfiguration para registrar a configuração MaintenanceShell. Ele salva o objeto que o cmdlet retorna na variável $s.

O segundo comando exibe o conteúdo da variável $s. 

O terceiro comando usa o método GetType e sua propriedade FullName para exibir o nome de tipo do objeto que Register-PSSessionConfiguration retorna.

O quarto comando usa o cmdlet Format-List para exibir todas as propriedades do objeto que Register-PSSessionConfiguration retorna em uma lista. A propriedade PSPath mostra que o objeto é armazenado em um diretório da unidade WSMan:.

O quinto comando usa o cmdlet Get-ChildItem para exibir os itens no caminho WSMan:\LocalHost\PlugIn. Eles incluem a nova configuração MaintenanceShell e as duas configurações padrão que vêm com o Windows PowerShell.

Exemplo 5

C:\PS>register-pssessionconfiguration -name WithProfile -startupScript add-profile.ps1

# Add-Profile.ps1

. c:\users\admin01\documents\windowspowershell\profile.ps1

Descrição
-----------
Esse comando cria e registra a configuração de sessão WithProfile no computador local. O comando usa o parâmetro StartupScript para orientar o Windows PowerShell a executar o script especificado em qualquer sessão que use a configuração de sessão.

O conteúdo do script especificado, Add-Profile.ps1, também é exibido. O script contém um único comando que usa dot sourcing para executar o perfil CurrentUserAllHosts do usuário no escopo atual da sessão.

Para obter mais informações sobre perfis, consulte about_Profiles. Para obter mais informações sobre dot sourcing, consulte about_Scopes.

Consulte também

Conceitos

about_Session_Configurations
Disable-PSSessionConfiguration
Enable-PSSessionConfiguration
Get-PSSessionConfiguration
Set-PSSessionConfiguration
Unregister-PSSessionConfiguration
WSMan Provider

Compartilhar via