Set-PSSessionConfiguration
更改已注册会话配置的属性。
语法
Set-PSSessionConfiguration
[-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>]
Set-PSSessionConfiguration
[-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>]
Set-PSSessionConfiguration
[-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 平台上可用。
cmdlet Set-PSSessionConfiguration
更改本地计算机上会话配置的属性。
使用 Name 参数标识要更改的会话配置。 使用其他参数为会话配置的属性指定新值。 若要从配置中删除属性值并使用默认值,请为相应的参数输入空字符串 (""
) 或 值 $Null
。
从 PowerShell 3.0 开始,可以使用会话配置文件来定义会话配置。 此功能提供了一种简单且易于发现的方法,可用于设置和更改使用会话配置的会话的属性。 若要指定会话配置文件,请使用 的 Set-PSSessionConfiguration
Path 参数。 有关会话配置文件的信息,请参阅 about_Session_Configuration_Files。 有关如何创建和修改会话配置文件的信息,请参阅 New-PSSessionConfigurationFile
cmdlet。
会话配置 (连接到本地计算机的 PSSession) 定义远程会话的环境。 每个 PSSession 都使用会话配置。 会话配置确定 PSSession 的功能,例如会话中可用的模块、允许运行的 cmdlet、语言模式、配额和超时。 会话配置的安全描述符确定谁可以使用会话配置连接到本地计算机。 有关会话配置的详细信息,请参阅 about_Session_Configurations。
若要查看会话配置的属性,请使用 Get-PSSessionConfiguration
cmdlet 或 WSMan 提供程序。 有关 WSMan 提供程序的详细信息,请键入 Get-Help WSMan
。
示例
示例 1:Create和更改会话配置
此示例演示如何在配置中添加和删除启动脚本。
第一个命令创建 AdminShell 配置。 第二个命令将 AdminConfig.ps1
脚本添加到配置。 重启 WinRM 时,更改将生效。
第三个命令从 AdminConfig.ps1
配置中删除脚本。
Register-PSSessionConfiguration -Name "AdminShell" -AssemblyName "C:\Shells\AdminShell.dll" -ConfigurationTypeName "AdminClass"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript "AdminConfig.ps1"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript $Null
示例 2:显示结果
此示例将 MaximumReceivedObjectSizeMB 属性的值增加到 20
。 此命令还会提示重启 WinRM 服务。 在 重新启动 WinRM 服务之前,更改不会生效。
Set-PSSessionConfiguration -Name "IncObj" -MaximumReceivedObjectSizeMB 20
WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\IncObj\InitializationParameters
ParamName ParamValue
--------- ----------
psmaximumreceivedobjectsizemb 20
"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run the command "restart-service winrm"?
[Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): y
示例 3:以不同方式显示结果
在此示例中, Set-PSSessionConfiguration
将 MaintenanceShell 会话配置中的启动脚本更改为 Maintenance.ps1
。 输出显示更改并提示重启 WinRM 服务。 响应 (y
是) 。
Get-PSSessionConfiguration
获取 MaintenanceShell 会话配置。 管道运算符 (|
) 将命令 Format-List
的结果发送到 ,这会在列表中显示配置对象的所有属性。 接下来,使用 WSMan 提供程序查看 MaintenanceShell 配置的初始化参数。 Get-ChildItem
获取 MaintenanceShell 插件的 InitializationParameters 节点中的子项。 有关 WSMan 提供程序的详细信息,请键入 Get-Help wsman
。
Set-PSSessionConfiguration -Name "MaintenanceShell" -StartupScript "C:\ps-test\Maintenance.ps1"
WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell\InitializationParameters
ParamName ParamValue
--------- ----------
startupscript c:\ps-test\Mainte...
"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run
the command "restart-service winrm"?
[Y] Yes [N] No [S] Suspend [?] Help (default is "Y"): y
Get-PSSessionConfiguration MaintenanceShell | Format-List -Property *
xmlns : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration
Name : MaintenanceShell
Filename : %windir%\system32\pwrshplugin.dll
SDKVersion : 1
XmlRenderingType : text
lang : en-US
PSVersion : 2.0
startupscript : c:\ps-test\Maintenance.ps1
ResourceUri : http://schemas.microsoft.com/powershell/MaintenanceShell
SupportsOptions : true
ExactMatch : true
Capability : {Shell}
Permission :
Get-ChildItem WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters
ParamName ParamValue
--------- ----------
PSVersion 2.0
startupscript c:\ps-test\Maintenance.ps1
参数
-AccessMode
启用和禁用会话配置,并确定它是否可以用于计算机上的远程或本地会话。 此参数的可接受值为:
Disabled
. 禁用会话配置。 它不能用于对计算机的远程或本地访问。 此值将会话配置的 Enabled 属性 (WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled
) 设置为False
。Local
. 将 Network_Deny_All 条目添加到会话配置的安全描述符。 本地计算机的用户可以使用会话配置在同一台计算机上创建本地环回会话,但远程用户被拒绝访问。Remote
. 从会话配置的安全描述符中删除 Deny_All 和 Network_Deny_All 条目。 本地和远程计算机的用户都可以使用会话配置来创建会话,并在此计算机上运行命令。
默认值为 Remote。
其他 cmdlet 稍后可以替代此参数的值。 例如, Enable-PSRemoting
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
) 的路径。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-AssemblyName
指定程序集名称。 此 cmdlet 基于程序集中定义的类创建会话配置。
输入定义会话配置的程序集 .dll
文件的文件名或完整路径。 如果只输入文件名,则可以在 ApplicationBase 参数的值中输入路径。
Type: | String |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ConfigurationTypeName
指定在 AssemblyName 参数的程序集中定义的会话配置的类型。 指定的类型必须实现 System.Management.Automation.Remoting.PSSessionConfiguration 类。
在指定程序集名称时需要此参数。
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
。
如果在 ConfigurationTypeName 参数中指定的配置类型中定义了数据大小限制,则使用配置类型中的限制。 此参数的值将被忽略。
Type: | Nullable<T>[Double] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumReceivedObjectSizeMB
指定任何单个对象中可发送到此计算机的数据量的限制。
输入数据大小(以 MB 为单位)。 默认为 10
。
如果在 ConfigurationTypeName 参数中指定的配置类型中定义了对象大小限制,则使用配置类型中的限制。 此参数的值将被忽略。
Type: | Nullable<T>[Double] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ModulesToImport
指定自动导入使用该会话配置的会话的模块和管理单元。 输入模块和管理单元名称。
默认情况下,仅 Microsoft.PowerShell.Core 模块导入会话,但除非排除 cmdlet,否则可以使用 Import-Module
和 Add-PSSnapin
cmdlet 将模块和管理单元添加到会话。
除会话配置文件中指定的模块外,此参数值中指定的模块还会导入 (New-PSSessionConfigurationFile
) 。 但是,会话配置文件中的设置可以隐藏模块所导出的命令或阻止用户使用它们。
此参数值中指定的模块会将指定的模块列表替换为 cmdlet 的 Register-PSSessionConfiguration
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 服务,并取消提示重启服务。
默认情况下,运行 Set-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
会话配置文件的路径,例如 cmdlet New-PSSessionConfigurationFile
创建的会话配置文件的路径。 如果省略路径,则默认路径为当前目录。
有关如何修改会话配置文件的信息,请参阅 cmdlet 的 New-PSSessionConfigurationFile
帮助主题。
此参数是在 PowerShell 3.0 中引入的。
Type: | String |
Position: | Named |
Default value: | None |
Required: | True |
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) 字符串。
此字符串确定使用新的会话配置所需的权限。 若要在会话中使用会话配置,用户必须至少 Execute(Invoke)
具有配置权限。
若要对配置使用默认安全描述符,请输入空字符串 (""
) 或值 $Null
。 默认值为驱动器中的 WSMan:
根 SDDL。
如果安全描述符很复杂,请考虑使用 ShowSecurityDescriptorUI 参数而不是此参数。 不能在同一命令中同时使用这两个参数。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionTypeOption
为会话配置指定特定于类型的选项。 输入会话类型选项对象,例如 cmdlet 返回的 New-PSWorkflowExecutionOption
PSWorkflowExecutionOption 对象。
使用会话配置的会话选项由会话选项和会话配置选项的值确定。 除非指定,否则会话中设置的选项(例如使用 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。 运行 Set-PSSessionConfiguration
命令并重启 WinRM 服务后,将显示属性表。
设置对配置的权限时,请记住,用户必须至少 Execute(Invoke)
具有在会话中使用会话配置的权限。
不能在同一命令中使用 SecurityDescriptorSDDL 参数和此参数。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-StartupScript
指定配置的启动脚本。 输入 PowerShell 脚本的完全限定路径。 指定的脚本在使用会话配置的新会话中运行。
若要从会话配置中删除启动脚本,请输入空字符串 (""
) 或值 $Null
。
可以使用启动脚本进一步配置用户会话。 如果脚本生成错误,甚至是非终止错误,则不会创建会话, 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
指定配置中的线程选项设置。 此设置定义在会话中执行命令时如何创建和使用线程。 此参数的可接受值为:
Default
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
指定会话配置的传输选项。 输入传输选项对象,例如 cmdlet 返回的 New-PSTransportOption
WSManConfigurationOption 对象。
使用会话配置的会话选项由会话选项和会话配置选项的值确定。 除非指定,否则会话中设置的选项(例如使用 New-PSSessionOption
cmdlet)优先于会话配置中设置的选项。 但是,会话选项的值不能超过在会话配置中设置的最大值。
此参数是在 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。
输出
备注
此 cmdlet 仅在 Windows 平台上可用。
若要运行此 cmdlet,请使用“ 以管理员身份运行” 选项启动 PowerShell。
cmdlet Set-PSSessionConfiguration
不会更改配置名称, 并且 WSMan 提供程序不支持 cmdlet Rename-Item
。 若要更改会话配置的名称,请使用 Unregister-PSSessionConfiguration
cmdlet 删除配置, Register-PSSessionConfiguration
然后使用 cmdlet 创建和注册新的会话配置。
可以使用 Set-PSSessionConfiguration
cmdlet 更改默认 Microsoft.PowerShell
和 Microsoft.PowerShell32
会话配置。 这些会话配置不受保护。 若要还原默认会话配置的原始版本,请使用 Unregister-PSSessionConfiguration
cmdlet 删除默认会话配置,Enable-PSRemoting
然后使用 cmdlet 还原它。
会话配置对象的属性会根据为会话配置设置的选项以及这些选项的值而有所不同。 此外,使用会话配置文件的会话配置还具有其他属性。
可以使用驱动器中的 WSMan:
命令更改会话配置的属性。
但是,不能使用 WSMan:
PowerShell 2.0 中的驱动器更改 PowerShell 3.0 中引入的会话配置属性,例如 OutputBufferingMode。 Windows PowerShell 2.0 命令不会生成错误,但它们是无效的。 若要更改 PowerShell 3.0 中引入的属性,请使用 WSMan:
PowerShell 3.0 或更高版本中的 驱动器。
相关链接
- Disable-PSSessionConfiguration
- Enable-PSSessionConfiguration
- Get-PSSessionConfiguration
- New-PSSessionConfigurationFile
- New-PSSessionOption
- New-PSTransportOption
- Register-PSSessionConfiguration
- Test-PSSessionConfigurationFile
- Unregister-PSSessionConfiguration
- WSMan 提供程序
- about_Session_Configurations
- about_Session_Configuration_Files