Register-PSSessionConfiguration

Sintaxe

NameParameterSet (Predefinição)

Register-PSSessionConfiguration
    [-Name] <String>
    [-ProcessorArchitecture <String>]
    [-SessionType <PSSessionType>]
    [-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 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;FA;SA;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:

• 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 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 dos parâmetros

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 dos parâmetros

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 dos parâmetros

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 o AssemblyName e parâmetros de 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.

Propriedades dos parâmetros

Conjuntos de parâmetros

-Confirm

Solicita confirmação antes de executar o cmdlet.

Propriedades dos parâmetros

Conjuntos de parâmetros

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

Propriedades dos parâmetros

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 dos parâmetros

Conjuntos de parâmetros

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

Propriedades dos parâmetros

Conjuntos de parâmetros

-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 da sessão (). 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.

Propriedades dos parâmetros

Conjuntos de parâmetros

-Name

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

Propriedades dos parâmetros

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 Register-PSSessionConfiguration, 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 será efetiva.

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

Propriedades dos parâmetros

Conjuntos de parâmetros

-Path

Especifica o caminho e o nome do 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 dos parâmetros

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

Propriedades dos parâmetros

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

Esse parâmetro foi introduzido no PowerShell 3.0.

Propriedades dos parâmetros

Conjuntos de parâmetros

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

Propriedades dos parâmetros

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. 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 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 dos parâmetros

Conjuntos de parâmetros

-SessionType

Especifica o tipo de sessão que é criado usando a configuração da sessão. Os valores aceitáveis para este parâmetro são:

• Vazio. Nenhum módulo é adicionado à sessão por padrão. Use os parâmetros desse cmdlet para adicionar módulos, funções, scripts e outros recursos à sessão.
• Predefinição. Adiciona Microsoft.PowerShell.Core à sessão. Este módulo inclui o cmdlet Import-Module que os usuários podem usar para importar outros módulos, a menos que você proíba explicitamente o cmdlet.
• RestrictedRemoteServer. Inclui apenas os seguintes cmdlets: Exit-PSSession, Get-Command, Get-FormatData, Get-Help, Measure-Object, Out-Defaulte Select-Object. Use um script ou assembly, ou as chaves no arquivo de configuração da sessão, para adicionar módulos, funções, scripts e outros recursos à sessão.

O valor padrão é Default.

O valor desse parâmetro tem precedência sobre o valor da chave SessionType no arquivo de configuração da sessão.

Esse parâmetro foi introduzido no PowerShell 3.0.

Propriedades dos parâmetros

Conjuntos de parâmetros

-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 cmdlet New-PSWorkflowExecutionOption 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 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 dos parâmetros

Conjuntos de parâmetros

-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 introduzir o 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 SecurityDescriptorSDDL parâmetro e este parâmetro no mesmo comando.

Propriedades dos parâmetros

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 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 comando New-PSSession falhará.

Propriedades dos parâmetros

Conjuntos de parâmetros

-ThreadApartmentState

Especifica o estado do apartamento dos threads na sessão. Os valores aceitáveis para este parâmetro são: STA, MTA e Unknown. O valor padrão é Unknown.

Propriedades dos parâmetros

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:

• Predefinido
• ReuseThread
• UseCurrentThread
• UseNewThread

O valor padrão é UseCurrentThread.

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

Propriedades dos parâmetros

Conjuntos de parâmetros

-TransportOption

Especifica a opção de transporte.

Esse parâmetro foi introduzido no PowerShell 3.0.

Propriedades dos parâmetros

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 dos parâmetros

Conjuntos de parâmetros

-WhatIf

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

Propriedades dos parâmetros

Conjuntos de parâmetros

CommonParameters

Entradas

None

Saídas

WSManConfigContainerElement

Notas

Ligações Relacionadas

• Desativar-ConfiguraçãoDaSessãoPS
• Configurar e Ativar Sessão PS
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile (Novo ficheiro de configuração de sessão PSSession)
• Nova-OpçãoDeSessãoPS
• Register-PSSessionConfiguration
• Set-PSSessionConfiguration
• Testar-FicheiroDeConfiguraçãoDaSessãoPS
• Unregister-PSSessionConfiguration
• Provedor WSMan
• sobre_Configurações_de_Sessão
• sobre_Ficheiros_de_Configuracao_da_Sessao