Register-PSSessionConfiguration

Sintaxe

NameParameterSet (Padrão)

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

AssemblyNameParameterSet

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

SessionConfigurationFile

Register-PSSessionConfiguration
    [-Name] <String>
    -Path <String>
    [-ProcessorArchitecture <String>]
    [-RunAsCredential <PSCredential>]
    [-ThreadApartmentState <ApartmentState>]
    [-ThreadOptions <PSThreadOptions>]
    [-AccessMode <PSSessionConfigurationAccessMode>]
    [-UseSharedProcess]
    [-StartupScript <String>]
    [-MaximumReceivedDataSizePerCommandMB <Double>]
    [-MaximumReceivedObjectSizeMB <Double>]
    [-SecurityDescriptorSddl <String>]
    [-ShowSecurityDescriptorUI]
    [-Force]
    [-NoServiceRestart]
    [-TransportOption <PSTransportOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Description

Exemplos

Exemplo 1: registrar uma configuração de sessão do NewShell

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

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

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

Exemplo 3: registrar uma configuração de 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

$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

Register-PSSessionConfiguration -Name WithProfile -StartupScript Add-Profile.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:

• Desabilitada. Desabilita 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 de 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 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 permite acesso remoto a todas as configurações de sessão, o cmdlet Enable-PSSessionConfiguration habilita configurações de sessão e o cmdlet Disable-PSRemoting impede o acesso remoto a todas as configurações de sessão.

Esse parâmetro foi introduzido no PowerShell 3.0.

Propriedades do parâmetro

Conjuntos de parâmetros

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

Propriedades do parâmetro

Conjuntos de parâmetros

-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 nesse parâmetro ou no valor do parâmetro applicationbase .

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

Propriedades do parâmetro

Conjuntos de parâmetros

-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 aspectos da configuração da sessão, como expor ou ocultar determinados parâmetros de cmdlets ou definir limites de tamanho de dados e tamanho do objeto 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.

Propriedades do parâmetro

Conjuntos de parâmetros

-Confirm

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

Propriedades do parâmetro

Conjuntos de parâmetros

-Force

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

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

Propriedades do parâmetro

Conjuntos de parâmetros

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

Propriedades do parâmetro

Conjuntos de parâmetros

-MaximumReceivedObjectSizeMB

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

Propriedades do parâmetro

Conjuntos de parâmetros

-ModulesToImport

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

Por padrão, somente 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 nesse valor de parâmetro são importados em adições a módulos especificados pelo parâmetro SessionType e aqueles listados na chave ModulesToImport no arquivo de configuração de sessão (). 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.

Esse parâmetro foi introduzido no PowerShell 3.0.

Propriedades do parâmetro

Conjuntos de parâmetros

-Name

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

Propriedades do parâmetro

Conjuntos de parâmetros

-NoServiceRestart

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

Por padrão, quando você executa um comando , é solicitado que você reinicie 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 será eficaz.

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

Essa funcionalidade foi implementada no PowerShell 7.5.0-preview.4.

Propriedades do parâmetro

Conjuntos de parâmetros

-Path

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

Esse parâmetro foi introduzido no PowerShell 3.0.

Propriedades do parâmetro

Conjuntos de parâmetros

-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 esse 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 em um computador de 32 bits falham.

Propriedades do parâmetro

Conjuntos de parâmetros

-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 de sessão.

Esse parâmetro foi introduzido no PowerShell 3.0.

Propriedades do parâmetro

Conjuntos de parâmetros

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

Propriedades do parâmetro

Conjuntos de parâmetros

-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. Você não pode usar ambos os parâmetros no mesmo comando.

Se você omitir esse parâmetro, o SDDL raiz do serviço WinRM será 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.

Propriedades do parâmetro

Conjuntos de parâmetros

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

Propriedades do parâmetro

Conjuntos de parâmetros

-ShowSecurityDescriptorUI

Indica que esse cmdlet exibe uma folha de propriedades que ajuda você a criar o SDDL para a configuração da sessão. A folha de propriedades é exibida depois que você insere o comando e, em seguida, 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 permissão Executar (Invocar) para usar a configuração de sessão em uma sessão.

Você não pode usar o parâmetro SecurityDescriptorSDDL e esse parâmetro no mesmo comando.

Propriedades do parâmetro

Conjuntos de parâmetros

-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 a sessão. Se o script gerar um erro, mesmo um erro de não terminação, a sessão não será criada e o comando New-PSSession falhará.

Propriedades do parâmetro

Conjuntos de parâmetros

-ThreadApartmentState

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

• Desconhecido
• MTA
• STA

Propriedades do parâmetro

Conjuntos de parâmetros

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

• Padrão
• Reutilizar Thread
• UseCurrentThread
• UseNewThread

O valor padrão é UseCurrentThread.

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

Propriedades do parâmetro

Conjuntos de parâmetros

-TransportOption

Especifica a opção de transporte.

Esse parâmetro foi introduzido no PowerShell 3.0.

Propriedades do parâmetro

Conjuntos de parâmetros

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

Propriedades do parâmetro

Conjuntos de parâmetros

-WhatIf

Mostra o que aconteceria se o cmdlet fosse executado. O cmdlet não é executado.

Propriedades do parâmetro

Conjuntos de parâmetros

CommonParameters

Entradas

None

Saídas

WSManConfigContainerElement

Observações

Links Relacionados

• Disable-PSSessionConfiguration
• Disable-PSSessionConfiguration
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• Provedor WSMan
• sobre_Configurações_de_Sessão
• about_Session_Configuration_Files