Register-PSSessionConfiguration

模块:

Microsoft.PowerShell.Core Module

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

语法

NameParameterSet (默认值)

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

说明

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 变量的值和 MaximumReceivedObjectSizeMB 参数中指定 SDDL 以增加对象大小限制。 它还使用 StartupScript 参数来指定配置会话的脚本。

$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

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

此示例演示如何注册 MaintenanceShell 配置。 Register-PSSessionConfiguration 返回存储在 变量中的 $s 对象。 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

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

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

默认值为 Remote。

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

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

参数属性

类型:	PSSessionConfigurationAccessMode
默认值:	None
接受的值:	Disabled, Local, Remote
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-ApplicationBase

指定程序集文件（*.dll）的路径，该路径是在 AssemblyName 参数的值中指定的。 当 AssemblyName 参数的值不包含路径时，请使用此参数。 默认为当前目录。

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

NameParameterSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

AssemblyNameParameterSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-AssemblyName

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

指定 ConfigurationTypeName 参数时，此参数是必需的。

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

AssemblyNameParameterSet

Position:	1
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-ConfigurationTypeName

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

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

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

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

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

AssemblyNameParameterSet

Position:	2
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-Confirm

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

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False
别名:	cf

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-Force

取消所有用户提示并重启 WinRM 服务，而无需提示。 重启服务会使配置更改生效。

若要防止重启并取消重启提示，请指定 NoServiceRestart 参数。

参数属性

类型:	SwitchParameter
默认值:	None
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-MaximumReceivedDataSizePerCommandMB

指定可在任何单个远程命令中发送到此计算机的数据量的限制。 输入数据大小（MB）。 默认值为 50 MB。

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

参数属性

类型:	Double
默认值:	50
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-MaximumReceivedObjectSizeMB

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

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

参数属性

类型:	Double
默认值:	10
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-ModulesToImport

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

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

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

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

参数属性

类型:	Object[]
默认值:	None
支持通配符:	False
不显示:	False

参数集

NameParameterSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

AssemblyNameParameterSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-Name

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

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

(All)

Position:	0
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	True
来自剩余参数的值:	False

-NoServiceRestart

不重启 WinRM 服务，并禁止提示重启服务。

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

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

参数属性

类型:	SwitchParameter
默认值:	None
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-Path

指定会话配置文件（.pssc）的路径和文件名，例如由 New-PSSessionConfigurationFile创建的配置文件。 如果省略路径，则默认值为当前目录。

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

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

SessionConfigurationFile

Position:	Named
必需:	True
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-ProcessorArchitecture

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

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

参数属性

类型:	String
默认值:	None
接受的值:	x86, amd64
支持通配符:	False
不显示:	False
别名:	公共广播系统

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-PSVersion

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

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

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

参数属性

类型:	Version
默认值:	None
支持通配符:	False
不显示:	False
别名:	PowerShellVersion

参数集

NameParameterSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

AssemblyNameParameterSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-RunAsCredential

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

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

参数属性

类型:	PSCredential
默认值:	None
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-SecurityDescriptorSddl

指定配置的安全描述符定义语言（SDDL）字符串。

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

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

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

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-SessionType

指定使用会话配置创建的会话类型。 此参数的可接受值为：

• 空白。 默认情况下，不会向会话添加任何模块。 使用此 cmdlet 的参数将模块、函数、脚本和其他功能添加到会话。
• 违约。 将 Microsoft.PowerShell.Core 添加到会话。 此模块包括 Import-Module cmdlet，除非显式禁止 cmdlet，否则用户可以使用该 cmdlet 导入其他模块。
• RestrictedRemoteServer。 仅包括以下 cmdlet：Exit-PSSession、Get-Command、Get-FormatData、Get-Help、Measure-Object、Out-Default和 Select-Object。 使用脚本或程序集或会话配置文件中的密钥将模块、函数、脚本和其他功能添加到会话。

默认值为 Default。

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

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

参数属性

类型:	PSSessionType
默认值:	None
接受的值:	DefaultRemoteShell, Workflow
支持通配符:	False
不显示:	False

参数集

NameParameterSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-SessionTypeOption

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

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

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

参数属性

类型:	PSSessionTypeOption
默认值:	None
支持通配符:	False
不显示:	False

参数集

NameParameterSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

AssemblyNameParameterSet

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-ShowSecurityDescriptorUI

指示此 cmdlet 显示一个属性表，可帮助你为会话配置创建 SDDL。 输入 Register-PSSessionConfiguration 命令后，将显示属性表，然后重启 WinRM 服务。

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

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

参数属性

类型:	SwitchParameter
默认值:	None
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-StartupScript

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

可以使用脚本来额外配置会话。 如果脚本生成错误，即使是非终止错误，也不会创建会话，并且 New-PSSession 命令失败。

参数属性

类型:	String
默认值:	None
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-ThreadApartmentState

指定会话中线程的公寓状态。 此参数的可接受值为：STA、MTA 和 Unknown。 默认值为 Unknown。

参数属性

类型:	ApartmentState
默认值:	None
接受的值:	STA, MTA, Unknown
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-ThreadOptions

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

• 违约
• 重用线程
• 使用当前线程
• 使用新线程

默认值 UseCurrentThread。

有关详细信息，请参阅 PSThreadOptions 枚举。

参数属性

类型:	PSThreadOptions
默认值:	None
接受的值:	Default, UseNewThread, ReuseThread, UseCurrentThread
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-TransportOption

指定传输选项。

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

参数属性

类型:	PSTransportOption
默认值:	None
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-UseSharedProcess

仅使用一个进程来托管由同一用户启动的所有会话，并使用同一会话配置。 默认情况下，每个会话托管在其自己的进程中。

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

参数属性

类型:	SwitchParameter
默认值:	None
支持通配符:	False
不显示:	False

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

-WhatIf

显示 cmdlet 运行时会发生什么情况。 命令脚本未运行。

参数属性

类型:	SwitchParameter
默认值:	False
支持通配符:	False
不显示:	False
别名:	无线

参数集

(All)

Position:	Named
必需:	False
来自管道的值:	False
来自管道的值（按属性名称）:	False
来自剩余参数的值:	False

CommonParameters

此 cmdlet 支持通用参数：-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 有关详细信息，请参阅 about_CommonParameters。

输入

None

不能通过管道将输入传递给此 cmdlet。

输出

WSManConfigContainerElement

备注

若要运行此 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
• New-PSSessionOption
• Register-PSSessionConfiguration
• Set-PSSessionConfiguration
• Test-PSSessionConfigurationFile
• Unregister-PSSessionConfiguration
• WSMan 提供程序
• about_Session_Configurations
• about_Session_Configuration_Files