New-PSSessionOption
创建一个包含 PSSession 高级选项的对象。
语法
New-PSSessionOption
[-MaximumRedirection <Int32>]
[-NoCompression]
[-NoMachineProfile]
[-Culture <CultureInfo>]
[-UICulture <CultureInfo>]
[-MaximumReceivedDataSizePerCommand <Int32>]
[-MaximumReceivedObjectSize <Int32>]
[-OutputBufferingMode <OutputBufferingMode>]
[-MaxConnectionRetryCount <Int32>]
[-ApplicationArguments <PSPrimitiveDictionary>]
[-OpenTimeout <Int32>]
[-CancelTimeout <Int32>]
[-IdleTimeout <Int32>]
[-ProxyAccessType <ProxyAccessType>]
[-ProxyAuthentication <AuthenticationMechanism>]
[-ProxyCredential <PSCredential>]
[-SkipCACheck]
[-SkipCNCheck]
[-SkipRevocationCheck]
[-OperationTimeout <Int32>]
[-NoEncryption]
[-UseUTF16]
[-IncludePortInSPN]
[<CommonParameters>]
说明
cmdlet New-PSSessionOption
创建一个 对象,该对象包含用户管理的会话 (PSSession) 的高级选项。 可以使用 对象作为创建 PSSession 的 cmdlet 的 SessionOption 参数的值,例如 New-PSSession
、 Enter-PSSession
和 Invoke-Command
。
如果没有参数, New-PSSessionOption
则会生成一个对象,该对象包含所有选项的默认值。 由于可以编辑每个属性,因此可以使用生成的对象作为模板,并为企业创建标准选项对象。
还可以将 SessionOption 对象保存在首选项变量中 $PSSessionOption
。 会话选项的新的默认值由此变量的值建立。 如果未为会话设置会话选项,并且它们优先于会话配置中设置的选项,则它们有效,但你可以通过在创建会话的 cmdlet 中指定会话选项或 SessionOption 对象来替代它们。 有关首选项变量的详细信息 $PSSessionOption
,请参阅 about_Preference_Variables。
在创建会话的 cmdlet 中使用 SessionOption 对象时,会话选项值优先于首选项变量和会话配置中 $PSSessionOption
设置的会话的默认值。 但是,它们不优先于在会话配置中设置的最大值、配额或限制。 有关会话配置的详细信息,请参阅 about_Session_Configurations。
示例
示例 1:Create默认会话选项
此命令使用默认值创建 SessionOption 对象。
New-PSSessionOption
MaximumConnectionRedirectionCount : 5
NoCompression : False
NoMachineProfile : False
ProxyAccessType : IEConfig
ProxyAuthentication : Negotiate
ProxyCredential :
SkipCACheck : False
SkipCNCheck : False
SkipRevocationCheck : False
OperationTimeout : 00:03:00
NoEncryption : False
UseUTF16 : False
Culture :
UICulture :
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize :
ApplicationArguments :
OpenTimeout : 00:03:00
CancelTimeout : 00:01:00
IdleTimeout : 00:04:00
示例 2:使用会话选项对象配置会话
此示例演示如何使用 SessionOption 对象配置会话。
$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $pso
第一个命令创建新的 SessionOption 对象,并将其保存在 变量的值 $pso
中。 第二个命令使用 New-PSSession
cmdlet 在 Server01 远程计算机上创建会话。 命令使用变量值$pso
中的 SessionOption 对象作为命令的 SessionOption 参数的值。
示例 3:启动交互式会话
此命令使用 Enter-PSSession
cmdlet 启动与 Server01 计算机的交互式会话。
Enter-PSSession -ComputerName Server01 -SessionOption (New-PSSessionOption -NoEncryption -NoCompression)
SessionOption 参数的值是具有 New-PSSessionOption
NoEncryption 和 NoCompression 参数的命令。
命令 New-PSSessionOption
括在括号中,以确保它在命令之前 Enter-PSSession
运行。
示例 4:修改会话选项对象
此示例演示如何修改 SessionOption 对象。 所有属性都具有读/写值。
$a = New-PSSessionOption
$a.OpenTimeout
Days : 0
Hours : 0
Minutes : 3
Seconds : 0
Milliseconds : 0
Ticks : 1800000000
TotalDays : 0.00208333333333333
TotalHours : 0.05
TotalMinutes : 3
TotalSeconds : 180
TotalMilliseconds : 180000
$a.UICulture = (Get-UICulture)
$a.OpenTimeout = (New-Timespan -Minutes 4)
$a.MaximumConnectionRedirectionCount = 1
$a
MaximumConnectionRedirectionCount : 1
NoCompression : False
NoMachineProfile : False
ProxyAccessType : IEConfig
ProxyAuthentication : Negotiate
ProxyCredential :
SkipCACheck : False
SkipCNCheck : False
SkipRevocationCheck : False
OperationTimeout : 00:03:00
NoEncryption : False
UseUTF16 : False
Culture :
UICulture : en-US
MaximumReceivedDataSizePerCommand :
MaximumReceivedObjectSize :
ApplicationArguments :
OpenTimeout : 00:04:00
CancelTimeout : 00:01:00
IdleTimeout : 00:04:00
使用此方法为你的企业创建标准会话对象,然后针对特定用途创建该对象的自定义版本。
示例 5:Create首选项变量
此命令创建首选项 $PSSessionOption
变量。
$PSSessionOption = New-PSSessionOption -OpenTimeOut 120000
$PSSessionOption
在会话中设置首选项变量时,它会为使用 New-PSSession
、 Enter-PSSession
和 Invoke-Command
cmdlet 创建的会话中的选项建立默认值。
若要使变量 $PSSessionOption
在所有会话中可用,请将其添加到 PowerShell 会话和 PowerShell 配置文件。
有关首选项变量的详细信息 $PSSessionOption
,请参阅 about_Preference_Variables。
有关配置文件的详细信息,请参阅 about_Profiles。
示例 6:满足远程会话配置的要求
此示例显示了如何使用 SessionOption 对象来满足远程会话配置的要求。
$skipCN = New-PSSessionOption -SkipCNCheck
New-PSSession -ComputerName 171.09.21.207 -UseSSL -Credential Domain01\User01 -SessionOption $SkipCN
第一个命令使用 New-PSSessionOption
cmdlet 创建具有 SkipCNCheck 属性的 SessionOption 对象。 命令将生成的会话对象保存在 变量中 $skipCN
。
第二个命令使用 New-PSSession
cmdlet 在远程计算机上创建新会话。 检查 $skipCN
变量在 SessionOption 参数的值中使用。
由于计算机由其 IP 地址标识, 因此 ComputerName 参数的值与用于安全套接字层 (SSL) 的证书中的任何公用名称都不匹配。 因此,SkipCNCheck 选项是必需的。
示例 7:使参数可用于远程会话
此示例演示如何使用 cmdlet 的 New-PSSessionOption
ApplicationArguments 参数使其他数据可供远程会话使用。
$team = @{Team="IT"; Use="Testing"}
$TeamOption = New-PSSessionOption -ApplicationArguments $team
$s = New-PSSession -ComputerName Server01 -SessionOption $TeamOption
Invoke-Command -Session $s {$PSSenderInfo.ApplicationArguments}
Name Value
---- -----
Team IT
Use Testing
PSVersionTable {CLRVersion, BuildVersion, PSVersion, WSManStackVersion...}
Invoke-Command -Session $s {
if ($PSSenderInfo.ApplicationArguments.Use -ne "Testing") {
.\logFiles.ps1
}
else {
"Just testing."
}
}
Just testing.
第一个命令创建包含两个键的哈希表: Team 和 Use。 命令将哈希表保存在 变量中 $team
。 有关哈希表的详细信息,请参阅 about_Hash_Tables。
接下来,New-PSSessionOption
cmdlet 使用 ApplicationArguments 参数创建保存在 变量中的 $team
SessionOption 对象。 创建会话选项对象时 New-PSSessionOption
,它会自动将 ApplicationArguments 参数值中的哈希表转换为 PrimitiveDictionary ,以便将数据可靠地传输到远程会话。
cmdlet 在 New-PSSession
Server01 计算机上启动会话。 它使用 SessionOption 参数在变量中包含 $teamOption
选项。
cmdlet Invoke-Command
演示变量中的数据 $team
可用于远程会话中的命令。 数据显示在自动变量的 ApplicationArguments 属性中 $PSSenderInfo
。
最后一个 Invoke-Command
演示了数据的使用方式。
参数
-ApplicationArguments
指定发送到远程会话的 PrimitiveDictionary 。 远程会话中的命令和脚本(包括会话配置中的启动脚本)可以在自动变量的 ApplicationArguments 属性中找到 $PSSenderInfo
此字典。 你可以使用此参数来将数据发送到远程会话。
有关详细信息,请参阅 about_Hash_Tables、 about_Session_Configurations和 about_Automatic_Variables。
Type: | PSPrimitiveDictionary |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-CancelTimeout
确定 PowerShell 在结束取消操作之前 (CTRL+C) 等待多长时间。 输入一个值(以毫秒为单位)。
默认值为 60000
(一分钟) 。 (零) 值 0
表示没有超时;该命令将无限期地继续。
Type: | Int32 |
Aliases: | CancelTimeoutMSec |
Position: | Named |
Default value: | 60000 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Culture
指定要用于会话的区域性。 以 (格式输入区域性名称 <languagecode2>-<country/regioncode2>
,例如 ja-JP
) 、包含 CultureInfo 对象的变量或获取 CultureInfo 对象的命令。
默认值 $Null
为 ,在会话中使用操作系统中设置的区域性。
Type: | CultureInfo |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-IdleTimeout
确定如果远程计算机未收到来自本地计算机的任何通信,会话保持打开状态的时间。 这包括检测信号。 当时间间隔已过时,该会话将关闭。
如果要断开连接并重新连接到会话,空闲超时值非常重要。 仅当该会话未超时时,才可以重新连接。
输入一个值(以毫秒为单位)。 最小值为 60000
(1 分钟) 。 最大值为会话配置的 MaxIdleTimeoutms 属性值。 默认值 -1
不设置空闲超时。
会话使用会话选项中设置的空闲超时(如果有)。 如果未 () -1
设置,则会话将使用会话配置的 IdleTimeoutMs 属性的值或 WSMan shell 超时值 (WSMan:\<ComputerName>\Shell\IdleTimeout
) ,以最短者为准。
如果会话选项中设置的空闲超时超过会话配置的 MaxIdleTimeoutMs 属性的值,则用于创建会话的命令将失败。
默认 Microsoft.PowerShell 会话配置的 7200000
IdleTimeoutMs 值为毫秒 (2 小时) 。 其 MaxIdleTimeoutMs 值为 2147483647
毫秒 (>24 天) 。 WSMan shell 空闲超时 (WSMan:\<ComputerName>\Shell\IdleTimeout
) 的默认值为 7200000
毫秒 (2 小时) 。
从会话断开连接或重新连接到会话时,还可以更改会话的空闲超时值。 有关详细信息,请参阅 Disconnect-PSSession
和 Connect-PSSession
。
在 Windows PowerShell 2.0 中,IdleTimeout 参数的默认值为 240000
(4 分钟) 。
Type: | Int32 |
Aliases: | IdleTimeoutMSec |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-IncludePortInSPN
在用于 Kerberos 身份验证的服务主体名称 (SPN) 中包含端口号, HTTP://<ComputerName>:5985
例如 。 此选项允许客户端使用非默认 SPN 对使用 Kerberos 身份验证的远程计算机进行身份验证。
该选项旨在用于为在不同的用户帐户下运行的支持 Kerberos 身份验证的多个服务的企业。 例如,允许 Kerberos 身份验证的 IIS 应用程序可能要求将默认 SPN 注册到不同于计算机帐户的用户帐户。 在这种情况下,PowerShell 远程处理无法使用 Kerberos 进行身份验证,因为它需要注册到计算机帐户的 SPN。 若要解决此问题,管理员可以创建注册到不同用户帐户的不同 SPN(例如使用 Setspn.exe
),并通过在 SPN 中包含端口号来区分它们。
有关详细信息,请参阅 Setspn 概述。
已在 Windows PowerShell 3.0 中引入了此参数。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaxConnectionRetryCount
指定如果当前尝试因网络问题而失败,PowerShell 尝试与目标计算机建立连接的次数。 默认值为 5
。
为 PowerShell 版本 5.0 添加了此参数。
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumReceivedDataSizePerCommand
指定本地计算机在单个命令中可从远程计算机接收到的最大字节数。 输入一个值(以字节为单位)。 默认情况下,没有数据大小限制。
此选项专门用于保护客户端计算机上的资源。
Type: | Int32 |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumReceivedObjectSize
指定本地计算机可从远程计算机接收到的最大对象大小。 此选项专门用于保护客户端计算机上的资源。 输入一个值(以字节为单位)。
在 Windows PowerShell 2.0 中,如果省略此参数,则没有对象大小限制。 从 Windows PowerShell 3.0 开始,如果省略此参数,默认值为 200
。
Type: | Int32 |
Position: | Named |
Default value: | 200 MB |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumRedirection
确定 PowerShell 在连接失败之前将连接重定向到备用统一资源标识符 (URI) 的次数。 默认值为 5
。 值为 0
(零) 会阻止所有重定向。
仅当在创建会话的命令中使用 AllowRedirection 参数时,才会在会话中使用此选项。
Type: | Int32 |
Position: | Named |
Default value: | 5 |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NoCompression
关闭会话中的数据包压缩。 压缩会占用更多的处理器周期,但可以提高传输速度。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NoEncryption
关闭数据加密。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-NoMachineProfile
阻止加载用户的 Windows 用户配置文件。 这样做可以加快创建会话的速度,但不能在该会话使用特定于用户的注册表设置、环境变量等项以及证书。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OpenTimeout
确定客户端计算机等待建立会话连接的时长。 当时间间隔到期时,用于建立该连接的命令将失败。 输入一个值(以毫秒为单位)。
默认值为 180000
(3 分钟) 。 (零) 值 0
表示没有超时;该命令将无限期地继续。
Type: | Int32 |
Aliases: | OpenTimeoutMSec |
Position: | Named |
Default value: | 180000 (3 minutes) |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OperationTimeout
确定 WinRM 在启动连接超时之前等待实时连接进行正面连接测试的最长时间。有关 WinRM 的详细信息,请参阅 Windows 远程管理文档。
OperationTimeout不会 对远程会话中运行的命令或进程施加时间限制,并且 不会影响 其他远程处理协议(如 SSH)。
默认值为 180000
(3 分钟) 。 (零) 值 0
表示没有超时。
Type: | Int32 |
Aliases: | OperationTimeoutMSec |
Position: | Named |
Default value: | 180000 (3 minutes) |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-OutputBufferingMode
当输出缓冲区时已满时,确定如何在断开连接的会话中管理命令输出。
如果未在会话或会话配置中设置输出缓冲模式,则默认值为 Block
。 用户还可以在断开会话连接时更改输出缓冲模式。
如果省略此参数,则 SessionOption 对象的 None
OutputBufferingMode 的值为 。 或 的值Block
Drop
将替代会话配置中设置的输出缓冲模式传输选项。 此参数的可接受值为:
Block
. 当输出缓冲区已满时,将挂起执行,直到清除此缓冲区。Drop
. 当输出缓冲区已满时,执行将继续。 由于已保存新的输出,因此将丢弃最早的输出。None
. 未指定任何输出缓冲模式。
有关输出缓冲模式传输选项的详细信息,请参阅 New-PSTransportOption
。
已在 Windows PowerShell 3.0 中引入了此参数。
Type: | OutputBufferingMode |
Accepted values: | None, Drop, Block |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyAccessType
确定用于解析主机名的机制。 此参数的可接受值为:
IEConfig
WinHttpConfig
AutoDetect
NoProxyServer
None
默认值为 None
。
有关此参数的值的信息,请参阅 ProxyAccessType 枚举。
Type: | ProxyAccessType |
Accepted values: | None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyAuthentication
指定用于代理解析的身份验证方法。 此参数的可接受值为:
Basic
Digest
Negotiate
默认值为 Negotiate
。
有关此参数的值的详细信息,请参阅 AuthenticationMechanism 枚举。
Type: | AuthenticationMechanism |
Accepted values: | Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos |
Position: | Named |
Default value: | Negotiate |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ProxyCredential
指定用于代理身份验证的凭据。 输入包含 PSCredential 对象的变量或获取 PSCredential 对象的命令,例如 Get-Credential
命令。 如果未设置此选项,则不指定任何凭据。
Type: | PSCredential |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipCACheck
指定通过 HTTPS 进行连接时,客户端不会验证服务器证书是否由受信任的证书颁发机构 (CA) 签名。
仅当远程计算机通过其他机制受信任(例如远程计算机所属的网络在物理上是安全的并已隔离,或者远程计算机在 WinRM 配置中列为受信任主机)时才使用此选项。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipCNCheck
指定服务器的 CN) (证书公用名不必与服务器的主机名匹配。 仅在使用 HTTPS 协议的远程操作中使用此选项。
仅将此选项用于受信任的计算机。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SkipRevocationCheck
不验证服务器证书的吊销状态。
Type: | SwitchParameter |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UICulture
指定用于会话的 UI 区域性。
有效值包括:
- 格式的
<languagecode2>-<country/regioncode2>
区域性名称,例如ja-JP
- 包含 CultureInfo 对象的变量
- 获取 CultureInfo 对象的命令,例如
Get-Culture
默认值为 $null
,以及创建会话时在操作系统中设置的 UI 区域性。
Type: | CultureInfo |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseUTF16
指示此 cmdlet 以 UTF16 格式而不是 UTF8 格式对请求进行编码。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
输入
None
不能通过管道将输入传递给此 cmdlet。
输出
备注
如果在创建 PSSession 的命令中未使用 SessionOption 参数,则会话选项由首选项变量的$PSSessionOption
属性值确定(如果已设置)。 有关变量 $PSSessionOption
的详细信息,请参阅 about_Preference_Variables。
会话配置对象的属性会根据为会话配置设置的选项以及这些选项的值而有所不同。 此外,使用会话配置文件的会话配置还具有其他属性。