Set-PSSessionConfiguration

模块:

Microsoft.PowerShell.Core

更改已注册会话配置的属性。

语法

PowerShell

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

PowerShell

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

PowerShell

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 平台上可用。

Set-PSSessionConfiguration cmdlet 更改本地计算机上的会话配置的属性。

使用 Name 参数标识要更改的会话配置。 使用其他参数为会话配置的属性指定新值。 若要从配置中删除属性值并使用默认值，请输入空字符串（""）或相应参数的 $Null 值。

从 PowerShell 3.0 开始，可以使用会话配置文件来定义会话配置。 此功能提供了一种简单且可发现的方法，用于设置和更改使用会话配置的会话的属性。 若要指定会话配置文件，请使用 Set-PSSessionConfiguration的 Path 参数。 有关会话配置文件的信息，请参阅 about_Session_Configuration_Files。 有关如何创建和修改会话配置文件的信息，请参阅 New-PSSessionConfigurationFile cmdlet。

会话配置定义连接到本地计算机的远程会话（PSSessions）的环境。 PSSession 每个 都使用会话配置。 会话配置确定 PSSession的功能，例如会话中可用的模块、允许运行的 cmdlet、语言模式、配额和超时。 会话配置的安全描述符确定谁可以使用会话配置连接到本地计算机。 有关会话配置的详细信息，请参阅 about_Session_Configurations。

若要查看会话配置的属性，请使用 Get-PSSessionConfiguration cmdlet 或 WSMan 提供程序。 有关 WSMan 提供程序的详细信息，请键入 Get-Help WSMan。

示例

示例 1：创建和更改会话配置

此示例演示如何从配置中添加和删除启动脚本。

第一个命令创建 AdminShell 配置。 第二个命令将 AdminConfig.ps1 脚本添加到配置。 在重启 winRM 时，更改有效。 第三个命令从配置中删除 AdminConfig.ps1 脚本。

PowerShell

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 服务 之前，更改才有效。

PowerShell

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。

PowerShell

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。 禁用会话配置。 它不能用于对计算机的远程或本地访问。 此值将会话配置 （WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled） Enabled 属性设置为 False。
• Local。 将 Network_Deny_All 条目添加到会话配置的安全描述符。 本地计算机的用户可以使用会话配置在同一台计算机上创建本地环回会话，但远程用户被拒绝访问。
• Remote。 从会话配置的安全描述符中删除 Deny_All 和 Network_Deny_All 条目。 本地和远程计算机的用户可以使用会话配置在此计算机上创建会话和运行命令。

默认值为远程 。

其他 cmdlet 稍后可以替代此参数的值。 例如，Enable-PSRemoting cmdlet 在计算机上启用所有会话配置并允许远程访问它们，Disable-PSRemoting cmdlet 仅允许对计算机上的所有会话配置进行本地访问。

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

类型:	PSSessionConfigurationAccessMode
接受的值:	Disabled, Local, Remote
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ApplicationBase

指定在 AssemblyName 参数的值中指定的程序集文件 （*.dll） 的路径。

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-AssemblyName

指定程序集名称。 此 cmdlet 基于程序集中定义的类创建会话配置。

输入定义会话配置的程序集 .dll 文件的文件名或完整路径。 如果仅输入文件名，则可以在 ApplicationBase 参数的值中输入路径。

类型:	String
Position:	1
默认值:	None
必需:	True
接受管道输入:	False
接受通配符:	False

-ConfigurationTypeName

指定 AssemblyName 参数中程序集中定义的会话配置的类型。 指定的类型必须实现 System.Management.Automation.Remoting.PSSessionConfiguration 类。

指定程序集名称时，此参数是必需的。

类型:	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。

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

类型:	Nullable<T>[Double]
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-MaximumReceivedObjectSizeMB

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

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

类型:	Nullable<T>[Double]
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ModulesToImport

指定自动导入到使用会话配置的会话中的模块和管理单元。 输入模块和管理单元名称。

默认情况下，仅将 Microsoft.PowerShell.Core 模块导入到会话中，但除非排除该 cmdlet，否则可以使用 Import-Module 和 Add-PSSnapin cmdlet 将模块和管理单元添加到会话中。

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

此参数值中指定的模块会将指定的模块列表替换为 Register-PSSessionConfiguration cmdlet 的 ModulesToImport 参数。

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

类型:	Object[]
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Name

指定要更改的会话配置的名称。

不能使用此参数更改会话配置的名称。

类型:	String
Position:	0
默认值:	None
必需:	True
接受管道输入:	True
接受通配符:	False

-NoServiceRestart

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

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

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

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-Path

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

有关如何修改会话配置文件的信息，请参阅 New-PSSessionConfigurationFile cmdlet 的帮助主题。

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

类型:	String
Position:	Named
默认值:	None
必需:	True
接受管道输入:	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）字符串。

此字符串确定使用新会话配置所需的权限。 若要在会话中使用会话配置，用户必须至少具有配置 Execute(Invoke) 权限。

若要对配置使用默认安全描述符，请输入空字符串（""）或 $Null值。 默认值为 WSMan: 驱动器中的根 SDDL。

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

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-SessionTypeOption

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

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

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

类型:	PSSessionTypeOption
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ShowSecurityDescriptorUI

使用此参数时，cmdlet 将打开一个属性表，帮助为会话配置创建新的 SDDL。 运行 Set-PSSessionConfiguration 命令后，将显示属性表，然后重启 WinRM 服务。

设置配置权限时，请记住，用户必须至少具有 Execute(Invoke) 权限才能在会话中使用会话配置。

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

类型:	SwitchParameter
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-StartupScript

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

若要从会话配置中删除启动脚本，请输入空字符串（""）或 $Null值。

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

类型:	String
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ThreadApartmentState

指定要使用的线程模块的公寓状态。 可接受的值为：

• Unknown
• MTA
• STA

类型:	ApartmentState
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-ThreadOptions

指定配置中的线程选项设置。 此设置定义在会话中执行命令时如何创建和使用线程。 此参数的可接受值为：

• Default
• ReuseThread
• UseCurrentThread
• UseNewThread

默认值为 UseCurrentThread。

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

类型:	PSThreadOptions
接受的值:	Default, UseNewThread, ReuseThread, UseCurrentThread
Position:	Named
默认值:	None
必需:	False
接受管道输入:	False
接受通配符:	False

-TransportOption

指定会话配置的传输选项。 输入传输选项对象，例如 New-PSTransportOption cmdlet 返回的 WSManConfigurationOption 对象。

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

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

输出

WSManConfigLeafElement

备注

此 cmdlet 仅在 Windows 平台上可用。

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

Set-PSSessionConfiguration cmdlet 不会更改配置名称，WSMan 提供程序不支持 Rename-Item cmdlet。 若要更改会话配置的名称，请使用 Unregister-PSSessionConfiguration cmdlet 删除配置，然后使用 Register-PSSessionConfiguration cmdlet 创建和注册新的会话配置。

可以使用 Set-PSSessionConfiguration cmdlet 更改默认 Microsoft.PowerShell 和 Microsoft.PowerShell32 会话配置。 它们不受保护。 若要还原到默认会话配置的原始版本，请使用 Unregister-PSSessionConfiguration cmdlet 删除默认会话配置，然后使用 Enable-PSRemoting cmdlet 还原它。

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

可以使用 WSMan: 驱动器中的命令来更改会话配置的属性。 但是，不能在 PowerShell 2.0 中使用 WSMan: 驱动器更改 PowerShell 3.0 中引入的会话配置属性，例如 OutputBufferingMode。 Windows PowerShell 2.0 命令不会生成错误，但它们无效。 若要更改 PowerShell 3.0 中引入的属性，请使用 PowerShell 3.0 或更高版本中的 WSMan: 驱动器。

相关链接

• 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