Compartilhar via


Register-PSSessionConfiguration

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

Sintaxe

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

Esse 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 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, tal como as que limitam a quantidade de dados que a sessão pode receber remotamente em um único objeto ou o comando. O descritor de segurança da configuração da sessão determina quais usuários têm permissão para usar a configuração da sessão.

Você pode definir os elementos de configuração por meio de 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 do NewShell

Neste exemplo, registramos a configuração da sessão do 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 do 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 de não encerramento, o New-PSSession comando falhará.

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

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

A $sessionParams variável é uma tabela de hash que contém todos os valores dos parâmetros. Essa tabela de hash é passada para o cmdlet usando 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 está armazenado em um diretório da unidade WSMan:. Get-ChildItem (alias dir) exibe os itens no WSMan:\LocalHost\PlugIn 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 o 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 locais ou remotas no computador. Os valores aceitáveis para esse 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 o acesso a usuários remotos.
  • Remoto. Permite que os usuários locais e remotos usem a configuração da sessão para criar sessões e executar comandos nesse computador.

O valor padrão é Remoto.

Outros cmdlets podem substituir o valor desse parâmetro posteriormente. Por exemplo, o Enable-PSRemoting cmdlet permite o acesso remoto a todas as configurações de sessão, o cmdlet habilita as Enable-PSSessionConfiguration 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.

Tipo:PSSessionConfigurationAccessMode
Valores aceitos:Disabled, Local, Remote
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 nesse parâmetro ou no valor do parâmetro ApplicationBase .

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

Tipo:String
Cargo:1
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 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 de 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.

Tipo:String
Cargo:2
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Confirm

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

Tipo:SwitchParameter
Aliases:cf
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Force

Suprime todos os prompts do usuário e reinicia o serviço WinRM sem avisar. Reiniciar o serviço faz a com que a alteração da configuração entre em vigor.

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

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 valor 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.

Tipo:Nullable<T>[Double]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

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

Tipo:Nullable<T>[Double]
Cargo:Named
Valor padrão:10
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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, 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 aos módulos especificados pelo parâmetro SessionType e aos listados na chave ModulesToImport no arquivo de configuração de sessão (New-PSSessionConfigurationFile). No entanto, as configurações no arquivo de configuração de sessão podem ocultar os comandos exportados por módulos ou impedir os usuários de utilizá-los.

Esse parâmetro foi introduzido no PowerShell 3.0.

Tipo:Object[]
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Name

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

Tipo:String
Cargo:0
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:True
Aceitar caracteres curinga:False

-NoServiceRestart

A intenção desse parâmetro é impedir a reinicialização do serviço WinRM . Essa funcionalidade ainda não foi implementada.

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

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-Path

Especifica o caminho e o nome de arquivo de um 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.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:True
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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 esse parâmetro são: x86 (32 bits) e AMD64 (64 bits). O valor padrão é determinado pela arquitetura de 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. Tentativas de criar um processo de 64 bits em um computador de 32 bits falharão.

Tipo:String
Aliases:PA
Valores aceitos:x86, amd64
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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.

Tipo:Version
Aliases:PowerShellVersion
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga: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.

Tipo:PSCredential
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-SecurityDescriptorSddl

Especifica uma cadeia de caracteres Security Descriptor Definition Language (SDDL) para a configuração.

Essa cadeia de caracteres determina as permissões que são 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 os dois 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 a raiz SDDL, use o provedor de WSMan. Por exemplo, Get-Item wsman:\localhost\service\rootSDDL. Para obter mais informações sobre o provedor WSMan, digite Get-Help wsman.

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-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 New-PSWorkflowExecutionOption cmdlet retorna.

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

Tipo:PSSessionTypeOption
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-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 aparece depois que você insere o Register-PSSessionConfiguration comando 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 de sessão em uma sessão.

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

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-StartupScript

Especifica o caminho totalmente qualificado de um script do PowerShell. O script especificado é executado na nova sessão que usar a configuração de sessão.

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

Tipo:String
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ThreadApartmentState

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

  • Desconhecido
  • MTA
  • STA
Tipo:ApartmentState
Valores aceitos:STA, MTA, Unknown
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-ThreadOptions

Especifica como os threads são criados e usados quando um comando é executado na sessão. Os valores aceitáveis para esse parâmetro são:

  • Padrão
  • Reutilizar Thread
  • UseCurrentThread
  • UseNewThread

O valor padrão é UseCurrentThread.

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

Tipo:PSThreadOptions
Valores aceitos:Default, UseNewThread, ReuseThread, UseCurrentThread
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-TransportOption

Especifica a opção de transporte.

Esse parâmetro foi introduzido no PowerShell 3.0.

Tipo:PSTransportOption
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-UseSharedProcess

Use somente um processo para hospedar todas as sessões que são iniciadas pelo mesmo usuário e usam 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.

Tipo:SwitchParameter
Cargo:Named
Valor padrão:None
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

-WhatIf

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

Tipo:SwitchParameter
Aliases:wi
Cargo:Named
Valor padrão:False
Obrigatório:False
Aceitar a entrada de pipeline:False
Aceitar caracteres curinga:False

Entradas

None

Você não pode canalizar objetos para esse cmdlet.

Saídas

WSManConfigContainerElement

Observações

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

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

Esse cmdlet gera XML que representa uma configuração de plug-in do WS-Management (Web Services for 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 de acordo 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.