Register-PSSessionConfiguration

Referência

Módulo:: Microsoft.PowerShell.Core

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

Syntax

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-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>]

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-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>]

Register-PSSessionConfiguration
        [-ProcessorArchitecture <String>]
        [-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

Este cmdlet só está disponível na plataforma Windows.

O Register-PSSessionConfiguration cmdlet cria e registra uma nova configuração de sessão no computador local. Este é um cmdlet avançado que você pode usar para criar sessões personalizadas para usuários remotos.

Cada sessão do PowerShell (PSSession) usa uma configuração de sessão, também conhecida como ponto de extremidade. Quando os usuários criam uma sessão que se conecta ao computador, eles podem selecionar uma configuração de sessão ou usar a configuração de sessão padrão que é registrada quando você habilita a comunicação remota do PowerShell. Os usuários também podem definir a variável de preferência $PSSessionConfigurationName, que especifica uma configuração padrão para sessões remotas criadas na sessão atual.

A configuração da sessão define o ambiente para a sessão remota. A configuração pode determinar quais comandos e elementos de idioma estão disponíveis na sessão e pode 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. O descritor de segurança da configuração de sessão determina quais usuários têm permissão para usar a configuração de sessão.

Você pode definir os elementos de configuração usando um assembly que implementa uma nova classe de configuração e usando um script que é executado na sessão. A partir do PowerShell 3.0, você também pode usar um arquivo de configuração de sessão para definir a configuração da sessão.

Para obter informações sobre configurações de sessão, consulte about_Session_Configurations. Para obter informações sobre arquivos de configuração de sessão, consulte about_Session_Configuration_Files.

Exemplos

Exemplo 1: Registrar uma configuração de sessão NewShell

Neste exemplo, registramos a configuração de sessão NewShell . Os parâmetros AssemblyName e ApplicationBase especificam o local do arquivo MyShell.dll , que especifica os cmdlets e provedores na configuração da sessão. O parâmetro ConfigurationTypeName especifica a classe de configuração a ser usada no assembly.

$sessionConfiguration = @{
    Name='NewShell'
    ApplicationBase='c:\MyShells\'
    AssemblyName='MyShell.dll'
    ConfigurationTypeName='MyClass'
}
Register-PSSessionConfiguration @sessionConfiguration

Para usar essa configuração, digite New-PSSession -ConfigurationName newshell.

Exemplo 2: Registrar uma configuração de sessão do MaintenanceShell

Este exemplo registra a configuração da sessão MaintenanceShell no computador local. O parâmetro StartupScript especifica o Maintenance.ps1 script.

Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1

Quando um usuário usa um New-PSSession comando e seleciona a configuração do MaintenanceShell , o Maintenance.ps1 script é executado na nova sessão. O script pode configurar a sessão. Isso inclui importar módulos e definir a política de execução para a sessão. Se o script gerar erros, incluindo erros não terminativos, o New-PSSession comando falhará.

Exemplo 3: Registrar uma configuração de sessão

Este exemplo registra a configuração da sessão AdminShell .

A variável $sessionParams é uma tabela hash que contém todos os valores dos parâmetros. Esta tabela hash é transmitida ao cmdlet com o splatting do PowerShell. O Register-PSSessionConfiguration comando usa o parâmetro SecurityDescritorSDDL para especificar o SDDL no valor da variável e o parâmetro MaximumReceivedObjectSizeMB para aumentar o limite de $sddl tamanho do objeto. Ele também usa o parâmetro StartupScript para especificar um script que configura a sessão.

$sddl = "O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;FA;GA;;;WD)(AU;FASA;GWGX;;;WD)"
$sessionParams = @{
    Name="AdminShell"
    SecurityDescriptorSDDL=$sddl
    MaximumReceivedObjectSizeMB=20
    StartupScript="C:\scripts\AdminShell.ps1"
}
Register-PSSessionConfiguration @sessionParams

Exemplo 4: Retornar um elemento de contêiner de configuração

Este exemplo mostra como registrar a configuração do MaintenanceShell . Register-PSSessionConfiguration retorna um objeto WSManConfigContainerElement armazenado na $s variável. Format-List Exibe todas as propriedades do objeto retornado. A propriedade PSPath mostra que o objeto é armazenado em um diretório da unidade WSMan:. Get-ChildItem (pseudónimo dir) Exibe os WSMan:\LocalHost\PlugIn itens no caminho. Isso inclui a nova configuração do MaintenanceShell e as duas configurações padrão que vêm com o PowerShell.

$s = Register-PSSessionConfiguration -Name MaintenanceShell -StartupScript C:\ps-test\Maintenance.ps1
$s | Format-List -Property *
dir WSMan:\LocalHost\Plugin

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

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

Exemplo 5: Registrar uma configuração de sessão com um script de inicialização

Neste exemplo, criamos e registramos a configuração da sessão WithProfile . O parâmetro StartupScript direciona o PowerShell para executar o script especificado para qualquer sessão que use a configuração da sessão.

Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.ps1

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 o dot sourcing, consulte about_Scopes.

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:

Desativado. Desativa a configuração da sessão. Ele não pode ser usado para acesso remoto ou local ao computador.
Local. Permite que os usuários do computador local usem a configuração da sessão para criar uma sessão de loopback local no mesmo computador, mas nega acesso a usuários remotos.
Remoto. Permite que usuários locais e remotos usem a configuração da 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 Enable-PSRemoting cmdlet permite acesso remoto a todas as configurações de sessão, o Enable-PSSessionConfiguration cmdlet habilita configurações de sessão e o cmdlet impede o Disable-PSRemoting acesso remoto a todas as configurações de sessão.

Esse parâmetro foi introduzido no PowerShell 3.0.

Type:	PSSessionConfigurationAccessMode
Accepted values:	Disabled, Local, Remote
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ApplicationBase

Especifica o caminho do arquivo de assembly (*.dll) 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.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-AssemblyName

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

Esse parâmetro é necessário quando você especifica o parâmetro ConfigurationTypeName .

Type:	String
Position:	1
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ConfigurationTypeName

Especifica o nome totalmente qualificado do tipo Microsoft .NET Framework usado para essa configuração. O tipo especificado deve implementar a classe System.Management.Automation.Remoting.PSSessionConfiguration .

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

A criação de um tipo permite controlar mais aspetos da configuração da sessão, como expor ou ocultar determinados parâmetros de cmdlets ou definir limites de tamanho de dados e de objetos que os usuários não podem substituir.

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

Type:	String
Position:	2
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-Confirm

Solicita a sua confirmação antes de executar o cmdlet.

Type:	SwitchParameter
Aliases:	cf
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Force

Suprime todos os prompts do usuário e reinicia o serviço WinRM sem avisar. Reiniciar o serviço torna a alteração de configuração efetiva.

Para impedir uma reinicialização e suprimir o prompt de reinicialização, especifique o parâmetro NoServiceRestart .

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumReceivedDataSizePerCommandMB

Especifica um limite para a 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 e o valor desse parâmetro será ignorado.

Type:	Nullable<T>[Double]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-MaximumReceivedObjectSizeMB

Especifica um limite para a quantidade de dados que podem ser enviados para este computador em qualquer objeto. 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 e o valor desse parâmetro será ignorado.

Type:	Nullable<T>[Double]
Position:	Named
Default value:	10
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ModulesToImport

Especifica os módulos que são importados automaticamente para sessões que usam a configuração de sessão.

Por padrão, apenas Microsoft.PowerShell.Core é importado para sessões. A menos que os cmdlets sejam excluídos, você pode usar Import-Module para adicionar módulos à sessão.

Os módulos especificados neste valor de parâmetro são importados em adições aos módulos especificados pelo parâmetro SessionType e aqueles listados na chave ModulesToImport no arquivo de configuração de sessão (New-PSSessionConfigurationFile). No entanto, as configurações no arquivo de configuração da sessão podem ocultar os comandos exportados pelos módulos ou impedir que os usuários os utilizem.

Esse parâmetro foi introduzido no PowerShell 3.0.

Type:	Object[]
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Name

Especifica um nome para a configuração da sessão. Este parâmetro é obrigatório.

Type:	String
Position:	0
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-NoServiceRestart

Não reinicia o serviço WinRM e suprime o prompt para reiniciar o serviço.

Por padrão, quando você executa um Register-PSSessionConfiguration comando, você é solicitado a reiniciar o serviço WinRM para tornar a nova configuração de sessão eficaz. Até que o serviço WinRM seja reiniciado, a nova configuração de sessão não é eficaz.

Para reiniciar o serviço WinRM sem solicitar, especifique o parâmetro Force . Para reiniciar o serviço WinRM manualmente, use o Restart-Service cmdlet.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Path

Especifica o caminho e o nome do arquivo de configuração de sessão (.pssc), como um criado pelo New-PSSessionConfigurationFile. Se você omitir o caminho, o padrão será o diretório atual.

Esse parâmetro foi introduzido no PowerShell 3.0.

Type:	String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ProcessorArchitecture

Determina se uma versão de 32 bits ou 64 bits do processo do PowerShell é iniciada em sessões que usam essa configuração de sessão. Os valores aceitáveis para este parâmetro são: x86 (32 bits) e AMD64 (64 bits). O valor padrão é determinado pela arquitetura do processador do computador que hospeda a configuração da sessão.

Você pode usar esse parâmetro para criar uma sessão de 32 bits em um computador de 64 bits. As tentativas de criar um processo de 64 bits num computador de 32 bits falham.

Type:	String
Aliases:	PA
Accepted values:	x86, amd64
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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 PowerShellVersion no arquivo de configuração da sessão.

Esse parâmetro foi introduzido no PowerShell 3.0.

Type:	Version
Aliases:	PowerShellVersion
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-RunAsCredential

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

Type:	PSCredential
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SecurityDescriptorSddl

Especifica uma cadeia de caracteres SDDL (Security Descriptor Definition Language) 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.

Se o descritor de segurança for complexo, considere usar o parâmetro ShowSecurityDescriptorUI em vez desse parâmetro. Não é possível usar os dois parâmetros no mesmo comando.

Se você omitir esse parâmetro, o SDDL raiz para o serviço WinRM é usado para essa configuração. Para exibir ou alterar o SDDL raiz, use o provedor WSMan. Por exemplo, Get-Item wsman:\localhost\service\rootSDDL. Para obter mais informações sobre o provedor WSMan, digite Get-Help wsman.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-SessionTypeOption

Especifica opções específicas do 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 New-PSWorkflowExecutionOption cmdlet retorna.

As opções de sessões que usam a configuração de sessão são determinadas pelos valores de opções de sessão e opções de configuração de sessão. A menos que especificado, as opções definidas na sessão, como usando o New-PSSessionOption cmdlet, 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.

Type:	PSSessionTypeOption
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ShowSecurityDescriptorUI

Indica que esse cmdlet exibe uma folha de propriedades que ajuda a criar o SDDL para a configuração da sessão. A folha de propriedades aparece depois de inserir o Register-PSSessionConfiguration comando e, em seguida, reinicie 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 da sessão em uma sessão.

Não é possível usar o parâmetro SecurityDescriptorSDDL e esse parâmetro no mesmo comando.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-StartupScript

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

Você pode usar o script para configurar adicionalmente a sessão. Se o script gerar um erro, mesmo um erro de não encerramento, a sessão não será criada e o New-PSSession comando falhará.

Type:	String
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ThreadApartmentState

Especifica o estado do apartamento do módulo de threading a ser usado. Os valores aceitáveis são:

Desconhecido
MTA
STA

Type:	ApartmentState
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-ThreadOptions

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

Predefinido
ReuseThread
UseCurrentThread
UseNewThread

O valor padrão é UseCurrentThread.

Para obter mais informações, consulte Enumeração PSThreadOptions.

Type:	PSThreadOptions
Accepted values:	Default, UseNewThread, ReuseThread, UseCurrentThread
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-TransportOption

Especifica a opção de transporte.

Esse parâmetro foi introduzido no PowerShell 3.0.

Type:	PSTransportOption
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	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.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-WhatIf

Apresenta o que aconteceria mediante a execução do cmdlet. O cmdlet não é executado.

Type:	SwitchParameter
Aliases:	wi
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

Entradas

None

Não é possível canalizar objetos para este cmdlet.

Saídas

WSManConfigContainerElement

Notas

Este cmdlet só está disponível em plataformas Windows.

Para executar esse cmdlet, você deve iniciar o PowerShell usando a opção Executar como administrador .

Este cmdlet gera XML que representa uma configuração de plug-in do Web Services for Management (WS-Management) e envia o XML para o WS-Management, que registra o plug-in no computador local (New-Item wsman:\localhost\plugin).

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.

Register-PSSessionConfiguration

Syntax

Description

Exemplos

Exemplo 1: Registrar uma configuração de sessão NewShell

Exemplo 2: Registrar uma configuração de sessão do MaintenanceShell

Exemplo 3: Registrar uma configuração de sessão

Exemplo 4: Retornar um elemento de contêiner de configuração

Exemplo 5: Registrar uma configuração de sessão com um script de inicialização

Parâmetros

-AccessMode

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-ProcessorArchitecture

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

Entradas

Saídas

Notas

Comentários

Recursos adicionais

Register-PSSessionConfiguration

Syntax

Description

Exemplos

Exemplo 1: Registrar uma configuração de sessão NewShell

Exemplo 2: Registrar uma configuração de sessão do MaintenanceShell

Exemplo 3: Registrar uma configuração de sessão

Exemplo 4: Retornar um elemento de contêiner de configuração

Exemplo 5: Registrar uma configuração de sessão com um script de inicialização

Parâmetros

-AccessMode

-ApplicationBase

-AssemblyName

-ConfigurationTypeName

-Confirm

-Force

-MaximumReceivedDataSizePerCommandMB

-MaximumReceivedObjectSizeMB

-ModulesToImport

-Name

-NoServiceRestart

-Path

-ProcessorArchitecture

-PSVersion

-RunAsCredential

-SecurityDescriptorSddl

-SessionTypeOption

-ShowSecurityDescriptorUI

-StartupScript

-ThreadApartmentState

-ThreadOptions

-TransportOption

-UseSharedProcess

-WhatIf

Entradas

Saídas

Notas

Ligações Relacionadas

Comentários

Recursos adicionais