Register-PSSessionConfiguration

模块:

Microsoft.PowerShell.Core

创建并注册新的会话配置。

语法

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

说明

此 cmdlet 仅在 Windows 平台上可用。

Register-PSSessionConfiguration cmdlet 可在本地计算机上创建并注册新的会话配置。 这是一个高级 cmdlet，可用于为远程用户创建自定义会话。

每个 PowerShell 会话 (PSSession) 使用一项会话配置，也称为“终结点”。 当用户创建连接到计算机的会话时，可以选择一个会话配置，或使用在启用 PowerShell 远程处理时注册的默认会话配置。 用户还可以设置 $PSSessionConfigurationName 首选项变量，它指定在当前会话中创建的远程会话的默认配置。

会话配置可定义远程会话的环境。 此配置可以确定会话中可使用哪些命令和语言元素，它可以包含用于保护计算机的设置，如用于限制单个对象或命令中会话可以远程接收的数据量的设置。 会话配置的安全描述符确定哪些用户有权限使用会话配置。

通过使用可实现新的配置类的程序集以及在会话中运行的脚本，可以定义配置的元素。 从 PowerShell 3.0 开始，还可以使用会话配置文件来定义会话配置。

有关会话配置的信息，请参阅 about_Session_Configurations。 有关会话配置文件的信息，请参阅 about_Session_Configuration_Files。

示例

示例 1：注册 NewShell 会话配置

此示例中将注册 NewShell 会话配置。 AssemblyName 和 ApplicationBase 参数指定 MyShell.dll 文件的位置，此文件可指定会话配置中的 cmdlet 和提供程序。 ConfigurationTypeName 参数指定要从程序集中使用的配置类。

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

若要使用此配置，请键入 New-PSSession -ConfigurationName newshell。

示例 2：注册 MaintenanceShell 会话配置

此示例将在本地计算机上注册 MaintenanceShell 会话配置。 StartupScript 参数指定 Maintenance.ps1 脚本。

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

用户使用 New-PSSession 命令并选择 MaintenanceShell 配置时，Maintenance.ps1 脚本将在新的会话中运行。 该脚本可以配置会话。 包括导入模块和设置会话的执行策略。 如果脚本生成任何错误（包括非终止错误），则 New-PSSession 命令失败。

示例 3：注册会话配置

此示例将注册 AdminShell 会话配置。

$sessionParams 变量是包含所有参数值的哈希表。 此哈希表通过 PowerShell splatting 传递到 cmdlet。 Register-PSSessionConfiguration 命令使用 SecurityDescritorSDDL 参数来指定 $sddl 变量的值中的 SDDL，使用 MaximumReceivedObjectSizeMB 参数来增加对象大小限制。 它还使用 StartupScript 参数来指定用于配置会话的脚本。

$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

示例 4：返回配置容器元素

此示例演示如何注册 MaintenanceShell 配置。 Register-PSSessionConfiguration 返回存储在 $s 变量中的 WSManConfigContainerElement 对象。 Format-List 显示返回的对象的所有属性。 PSPath 属性显示该对象存储在 WSMan: 驱动器的目录中。 Get-ChildItem（别名 dir）显示 WSMan:\LocalHost\PlugIn 路径中的项。 这些项包括新的 MaintenanceShell 配置和 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}

示例 5：使用启动脚本注册会话配置

此示例中将创建并注册 WithProfile 会话配置。 StartupScript 参数指示 PowerShell 为使用该会话配置的任何会话运行指定的脚本。

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

该脚本包含单个命令，该命令使用点 (.) 来获得来源，以在会话的当前作用域中运行用户的 CurrentUserAllHosts 配置文件。

有关配置文件的详细信息，请参阅 about_Profiles。 有关使用点 (.) 来获得来源的详细信息，请参阅 about_Scopes。

参数

-AccessMode

启用和禁用会话配置，并确定它是否可以用于计算机上的远程或本地会话。 此参数的可接受值为：

• 已禁用。 禁用会话配置。 它不能用于对计算机的远程或本地访问。
• 本地。 允许本地计算机用户使用会话配置在同一计算机上创建本地 loopback 会话，但拒绝对远程用户的访问。
• 很少发生。 允许本地和远程用户使用会话配置创建会话并在此计算机上运行命令。

默认值为 Remote。

其他 cmdlet 稍后可以替代此参数的值。 例如，Enable-PSRemoting cmdlet 允许远程访问所有会话配置，Enable-PSSessionConfiguration cmdlet 启用会话配置，Disable-PSRemoting cmdlet 阻止远程访问所有会话配置。

此参数是在 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

指定在 AssemblyName 参数的值中指定的程序集文件 (*.dll) 的路径。 如果 AssemblyName 参数的值不包括路径，则使用此参数。 默认为当前目录。

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

-AssemblyName

指定定义配置类型的程序集文件 (*.dll) 的名称。 可以在此参数或 ApplicationBase 参数的值中指定 .dll 文件的路径。

如果指定了 ConfigurationTypeName 参数，则此参数是必需。

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

-ConfigurationTypeName

指定用于此配置的 Microsoft .NET Framework 类型的完全限定的名称。 指定的类型必须实现 System.Management.Automation.Remoting.PSSessionConfiguration 类。

若要指定可实现配置类型的程序集文件 (*.dll)，请指定 AssemblyName 和 ApplicationBase 参数。

创建可让你控制会话配置的更多方面的类型，如公开或隐藏 cmdlet 的某些参数，或设置用户无法重写的数据大小和对象大小的限制。

如果省略此参数，则 DefaultRemotePowerShellConfiguration 类将用于会话配置。

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

-Confirm

提示你在运行 cmdlet 之前进行确认。

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

-Force

禁止显示所有用户提示，并且重新启动 WinRM 服务而不显示提示。 重新启动服务可使配置更改生效。

若要阻止重启并禁止显示重启提示，请指定 NoServiceRestart 参数。

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

-MaximumReceivedDataSizePerCommandMB

指定在任何单个远程命令中可以发送给该计算机的数据量的限制。 输入数据大小（以兆字节 (MB) 为单位）。 默认值为 50 MB。

如果 ConfigurationTypeName 参数中指定的配置类型定义了数据大小限制，则使用该配置类型中的限制，而忽略此参数的值。

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

-MaximumReceivedObjectSizeMB

指定在任何单个对象中可以发送给该计算机的数据量的限制。 输入数据大小（以兆字节为单位）。 默认值为 10 MB。

如果 ConfigurationTypeName 参数中指定的配置类型定义了对象大小限制，则使用该配置类型中的限制，而忽略此参数的值。

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

-ModulesToImport

指定自动导入使用该会话配置的会话的模块。

默认情况下，仅 Microsoft.PowerShell.Core 导入会话。 除非排除了 cmdlet，否则可以使用 Import-Module 将模块添加到会话。

除了由 SessionType 参数指定的模块以及在会话配置文件 (New-PSSessionConfigurationFile) 的 ModulesToImport 键中列出的模块之外，还将导入此参数值中指定的模块。 但是，会话配置文件中的设置可以隐藏模块所导出的命令或阻止用户使用它们。

此参数是在 PowerShell 3.0 中引入的。

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

-Name

指定会话配置的名称。 此参数是必需的。

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

-NoServiceRestart

不重新启动 WinRM 服务，并且禁止提示重新启动该服务。

默认情况下，当你运行 Register-PSSessionConfiguration 命令时，系统会提示你重新启动 WinRM 服务以使新的会话配置生效。 在重新启动 WinRM 服务之前，新的会话配置不会生效。

若要在无提示的情况下重启 WinRM 服务，请指定 Force 参数。 若要手动重新启动 WinRM 服务，请使用 Restart-Service cmdlet。

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

-Path

指定会话配置文件 (.pssc) 的路径和文件名，如通过 New-PSSessionConfigurationFile 创建。 如果省略路径，则默认路径为当前目录。

此参数是在 PowerShell 3.0 中引入的。

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

-ProcessorArchitecture

确定在使用此会话配置的会话中启动 32 位版本还是 64 位版本的 PowerShell 进程。 此参数的可接受的值是：x86（32 位）和 AMD64（64 位）。 默认值由托管该会话配置的计算机的处理器体系结构确定。

可使用此参数在 64 位计算机上创建 32 位会话。 尝试在 32 位计算机上创建 64 位进程将失败。

Type:	String
Aliases:	PA
Accepted values:	x86, amd64
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-PSVersion

在使用此会话配置的会话中指定 PowerShell 的版本。

此参数的值优先于会话配置文件中 PowerShellVersion 键的值。

此参数是在 PowerShell 3.0 中引入的。

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

-RunAsCredential

指定会话中命令的凭据。 默认情况下，在当前用户授权下运行命令。

此参数是在 PowerShell 3.0 中引入的。

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

-SecurityDescriptorSddl

指定用于配置的安全描述符定义语言 (SDDL) 字符串。

此字符串确定使用新的会话配置所需的权限。 若要使用会话中的会话配置，用户必须至少具有对该配置的执行（调用）权限。

如果安全描述符较复杂，请考虑使用 ShowSecurityDescriptorUI 参数，而不是此参数。 不能在同一命令中同时使用这两个参数。

如果省略此参数，则将 WinRM 服务的根 SDDL 用于此配置。 若要查看或更改根 SDDL，请使用 WSMan 提供程序。 例如，Get-Item wsman:\localhost\service\rootSDDL。 有关 WSMan 提供程序的详细信息，请键入 Get-Help wsman。

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

-SessionTypeOption

为会话配置指定特定于类型的选项。 输入会话类型选项对象，例如 PSWorkflowExecutionOption 对象，它由 New-PSWorkflowExecutionOption cmdlet 返回。

使用会话配置的会话选项由会话选项和会话配置选项的值确定。 除非指定，否则会话中设置的选项（如使用 New-PSSessionOption cmdlet）优先于会话配置中设置的选项。 但是，会话选项的值不能超过在会话配置中设置的最大值。

此参数是在 PowerShell 3.0 中引入的。

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

-ShowSecurityDescriptorUI

指示此 cmdlet 显示帮助你创建会话配置的 SDDL 的属性表。 在输入 Register-PSSessionConfiguration 命令并重新启动 WinRM 服务后，将显示该属性表。

当设置配置的权限时，请记住用户必须至少具有能够使用会话中的会话配置的执行（调用）权限。

不能在同一命令中同时使用 SecurityDescriptorSDDL 参数和此参数。

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

-StartupScript

指定到 PowerShell 脚本的完全限定的路径。 指定的脚本在使用会话配置的新会话中运行。

可使用脚本进一步配置会话。 如果脚本生成错误（即使是非终止错误），也不会创建会话，并且 New-PSSession 命令失败。

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

-ThreadApartmentState

指定要使用的线程模块的单元状态。 可接受的值：

• Unknown
• MTA
• STA

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

-ThreadOptions

指定在会话中运行命令时如何创建和使用线程。 此参数的可接受值为：

• 默认
• ReuseThread
• UseCurrentThread
• UseNewThread

默认值为 UseCurrentThread。

有关详细信息，请参阅 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

指定传输选项。

此参数是在 PowerShell 3.0 中引入的。

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

-UseSharedProcess

仅使用一个进程来托管由同一用户发起且使用相同会话配置的所有会话。 默认情况下，每个会话都托管在其自身进程中。

此参数是在 PowerShell 3.0 中引入的。

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

-WhatIf

显示运行该 cmdlet 时会发生什么情况。 cmdlet 未运行。

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

输入

None

不能通过管道将对象传递给此 cmdlet。

输出

WSManConfigContainerElement

备注

此 cmdlet 仅在 Windows 平台上可用。

若要运行此 cmdlet，必须使用“以管理员身份运行”选项启动 PowerShell。

此 cmdlet 将生成表示 Web Services for Management (WS-Management) 插件配置的 XML，并将该 XML 发送到 WS-Management，后者将在本地计算机上注册该插件 (New-Item wsman:\localhost\plugin)。

会话配置对象的属性会根据为会话配置设置的选项以及这些选项的值而有所不同。 此外，使用会话配置文件的会话配置还具有其他属性。

相关链接

• Disable-PSSessionConfiguration
• Enable-PSSessionConfiguration
• Get-PSSessionConfiguration
• New-PSSessionConfigurationFile
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• WSMan 提供程序
• about_Session_Configurations
• about_Session_Configuration_Files