Register-PSSessionConfiguration

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>]

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

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

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.

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.

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.