Register-PSSessionConfiguration
创建并注册新的会话配置。
语法
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 中引入的。
类型: | PSSessionConfigurationAccessMode |
接受的值: | Disabled, Local, Remote |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-ApplicationBase
指定 AssemblyName 参数的值中指定的程序集文件 (*.dll
) 的路径。 当 AssemblyName 参数的值不包含路径时,请使用此参数。 默认为当前目录。
类型: | String |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-AssemblyName
指定定义配置类型的程序集文件 (*.dll) 的名称。 可以在此参数或 ApplicationBase 参数的值中指定 .dll 文件的路径。
如果指定了 ConfigurationTypeName 参数,则此参数是必需。
类型: | String |
Position: | 1 |
默认值: | None |
必需: | True |
接受管道输入: | False |
接受通配符: | False |
-ConfigurationTypeName
指定用于此配置的 Microsoft .NET Framework 类型的完全限定名称。 指定的类型必须实现 System.Management.Automation.Remoting.PSSessionConfiguration 类。
若要指定实现配置类型的程序集文件(*.dll
),请指定 AssemblyName 和 ApplicationBase 参数。
通过创建类型,可以控制会话配置的更多方面,例如公开或隐藏 cmdlet 的某些参数,或设置用户无法替代的数据大小和对象大小限制。
如果省略此参数,则 DefaultRemotePowerShellConfiguration 类将用于会话配置。
类型: | String |
Position: | 2 |
默认值: | None |
必需: | True |
接受管道输入: | False |
接受通配符: | False |
-Confirm
提示你在运行 cmdlet 之前进行确认。
类型: | SwitchParameter |
别名: | cf |
Position: | Named |
默认值: | False |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-Force
禁止显示所有用户提示,并且重新启动 WinRM 服务而不显示提示。 重新启动服务可使配置更改生效。
若要阻止重启并禁止显示重启提示,请指定 NoServiceRestart 参数。
类型: | SwitchParameter |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-MaximumReceivedDataSizePerCommandMB
指定在任何单个远程命令中可以发送给该计算机的数据量的限制。 输入数据大小(以兆字节 (MB) 为单位)。 默认值为 50 MB。
如果在 ConfigurationTypeName 参数中指定的配置类型中定义了数据大小限制,则使用配置类型的限制,并忽略此参数的值。
类型: | Nullable<T>[Double] |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-MaximumReceivedObjectSizeMB
指定在任何单个对象中可以发送给该计算机的数据量的限制。 输入数据大小(以兆字节为单位)。 默认值为 10 MB。
如果在 ConfigurationTypeName 参数中指定的配置类型中定义了对象大小限制,则使用配置类型的限制,并忽略此参数的值。
类型: | Nullable<T>[Double] |
Position: | Named |
默认值: | 10 |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-ModulesToImport
指定自动导入使用该会话配置的会话的模块。
默认情况下,仅 Microsoft.PowerShell.Core 导入会话。 除非排除了 cmdlet,否则可以使用 Import-Module
将模块添加到会话。
除了由 SessionType 参数指定的模块以及在会话配置文件 (New-PSSessionConfigurationFile
) 的 ModulesToImport 键中列出的模块之外,还将导入此参数值中指定的模块。 但是,会话配置文件中的设置可以隐藏模块所导出的命令或阻止用户使用它们。
此参数是在 PowerShell 3.0 中引入的。
类型: | Object[] |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-Name
指定会话配置的名称。 此参数是必需的。
类型: | String |
Position: | 0 |
默认值: | None |
必需: | True |
接受管道输入: | True |
接受通配符: | False |
-NoServiceRestart
此参数的目的是防止重启 WinRM 服务。 此功能尚未实现。
此功能是在 PowerShell 7.5.0-preview.4 中实现的。
类型: | SwitchParameter |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-Path
指定会话配置文件 (.pssc) 的路径和文件名,如通过 New-PSSessionConfigurationFile
创建。 如果省略路径,则默认路径为当前目录。
此参数是在 PowerShell 3.0 中引入的。
类型: | String |
Position: | Named |
默认值: | None |
必需: | True |
接受管道输入: | False |
接受通配符: | False |
-ProcessorArchitecture
确定在使用此会话配置的会话中启动 32 位版本还是 64 位版本的 PowerShell 进程。 此参数的可接受的值是:x86(32 位)和 AMD64(64 位)。 默认值由托管该会话配置的计算机的处理器体系结构确定。
可使用此参数在 64 位计算机上创建 32 位会话。 尝试在 32 位计算机上创建 64 位进程将失败。
类型: | String |
别名: | PA |
接受的值: | x86, amd64 |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-PSVersion
在使用此会话配置的会话中指定 PowerShell 的版本。
此参数的值优先于会话配置文件中 PowerShellVersion 键的值。
此参数是在 PowerShell 3.0 中引入的。
类型: | Version |
别名: | PowerShellVersion |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-RunAsCredential
指定会话中命令的凭据。 默认情况下,在当前用户授权下运行命令。
此参数是在 PowerShell 3.0 中引入的。
类型: | PSCredential |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-SecurityDescriptorSddl
指定用于配置的安全描述符定义语言 (SDDL) 字符串。
此字符串确定使用新的会话配置所需的权限。 若要使用会话中的会话配置,用户必须至少具有对该配置的执行(调用)权限。
如果安全描述符较复杂,请考虑使用 ShowSecurityDescriptorUI 参数,而不是此参数。 不能在同一命令中使用这两个参数。
如果省略此参数,则将 WinRM 服务的根 SDDL 用于此配置。
若要查看或更改根 SDDL,请使用 WSMan 提供程序。 例如,Get-Item wsman:\localhost\service\rootSDDL
。 有关 WSMan 提供程序的详细信息,请键入 Get-Help wsman
。
类型: | String |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-SessionTypeOption
为会话配置指定特定于类型的选项。 输入会话类型选项对象,例如 PSWorkflowExecutionOption 对象,它由 New-PSWorkflowExecutionOption
cmdlet 返回。
使用会话配置的会话选项由会话选项和会话配置选项的值确定。 除非指定,否则会话中设置的选项(如使用 New-PSSessionOption
cmdlet)优先于会话配置中设置的选项。 但是,会话选项值不能超过会话配置中设置的最大值。
此参数是在 PowerShell 3.0 中引入的。
类型: | PSSessionTypeOption |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-ShowSecurityDescriptorUI
指示此 cmdlet 显示帮助你创建会话配置的 SDDL 的属性表。 在输入 Register-PSSessionConfiguration
命令并重新启动 WinRM 服务后,将显示该属性表。
当设置配置的权限时,请记住用户必须至少具有能够使用会话中的会话配置的执行(调用)权限。
不能在同一命令中使用 SecurityDescriptorSDDL 参数和此参数。
类型: | SwitchParameter |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-StartupScript
指定到 PowerShell 脚本的完全限定的路径。 指定的脚本在使用会话配置的新会话中运行。
可使用脚本进一步配置会话。 如果脚本生成错误,即使是非终止错误,也不会创建会话,并且 New-PSSession
命令会失败。
类型: | String |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-ThreadApartmentState
指定要使用的线程模块的单元状态。 可接受的值:
- Unknown
- MTA
- STA
类型: | ApartmentState |
接受的值: | STA, MTA, Unknown |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-ThreadOptions
指定在会话中运行命令时如何创建和使用线程。 此参数的可接受值为:
- 默认
- ReuseThread
- UseCurrentThread
- UseNewThread
默认值为 UseCurrentThread。
有关详细信息,请参阅 PSThreadOptions 枚举。
类型: | PSThreadOptions |
接受的值: | Default, UseNewThread, ReuseThread, UseCurrentThread |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-TransportOption
指定传输选项。
此参数是在 PowerShell 3.0 中引入的。
类型: | PSTransportOption |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-UseSharedProcess
仅使用一个进程来托管由同一用户发起且使用相同会话配置的所有会话。 默认情况下,每个会话都托管在其自身进程中。
此参数是在 PowerShell 3.0 中引入的。
类型: | SwitchParameter |
Position: | Named |
默认值: | None |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
-WhatIf
显示运行该 cmdlet 时会发生什么情况。 cmdlet 未运行。
类型: | SwitchParameter |
别名: | wi |
Position: | Named |
默认值: | False |
必需: | False |
接受管道输入: | False |
接受通配符: | False |
输入
None
不能通过管道将对象传递给此 cmdlet。
输出
备注
此 cmdlet 仅在 Windows 平台上可用。
若要运行此 cmdlet,必须使用“以管理员身份运行”选项启动 PowerShell。
此 cmdlet 将生成表示 Web Services for Management (WS-Management) 插件配置的 XML,并将该 XML 发送到 WS-Management,后者将在本地计算机上注册该插件 (New-Item wsman:\localhost\plugin
)。
会话配置对象的属性会根据为会话配置设置的选项以及这些选项的值而有所不同。 此外,使用会话配置文件的会话配置还具有其他属性。