New-PSSessionOption
建立包含 PSSession 之進階選項的物件。
Syntax
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>]
Description
New-PSSessionOption Cmdlet 會建立物件,其中包含使用者管理的會話進階選項, (PSSession) 。 您可以使用 對象作為建立 PSSession 之 Cmdlet 的 SessionOption 參數值,例如 New-PSSession、Enter-PSSession 和 Invoke-Command。
在沒有參數的情況下,New-PSSessionOption 會產生包含所有選項之預設值的物件。 因為所有屬性都可以編輯,所以您可以使用產生的物件作為範本,然後為您的企業建立標準選項物件。
您也可以將會話選項物件儲存在喜好設定變數中 $PSSessionOption
。 此變數的值會替工作階段選項建立新的預設值。 在沒有為工作階段設定任何工作階段選項時,它們就會生效,而且它們的優先順序高於在工作階段設定中設定的選項,但是您可以透過在建立工作階段的 Cmdlet 中,指定工作階段選項或工作階段選項物件來覆寫它們。 如需喜好設定變數的詳細資訊 $PSSessionOption
,請參閱 about_Preference_Variables。
當您在建立工作階段的 Cmdlet 中使用工作階段選項物件時,工作階段選項值的優先順序高於在 $PSSessionOption 喜好設定變數和工作階段設定中設定的工作階段預設值。 不過,它們的優先順序不會高於工作階段設定中設定的最大值、配額或限制。 如需會話設定的詳細資訊,請參閱 about_Session_Configurations。
範例
範例 1:Create 預設工作階段選項
此命令會建立具有所有預設值的工作階段選項物件。
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:使用會話選項物件設定會話
此範例說明如何使用工作階段選項物件設定工作階段。
$pso = New-PSSessionOption -Culture "fr-fr" -MaximumReceivedObjectSize 10MB
New-PSSession -ComputerName Server01 -SessionOption $pso
第一個命令會建立新的工作階段選項物件,並將它儲存在變數的值中 $pso
。 第二個命令會 New-PSSession
使用 Cmdlet 在 Server01 遠端電腦上建立工作階段。 命令會使用 變數值 $pso
中的會話選項物件做為命令 的 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:修改會話選項物件
此範例示範您可以修改工作階段選項物件。 所有屬性皆具有讀取/寫入值。
$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 屬性的會話選項物件。 命令會將產生的會話物件儲存在變數中 $skipCN
。
第二個命令會 New-PSSession
使用 Cmdlet 在遠端電腦上建立新的工作階段。 $skipCN
Check 變數會用於 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
會話選項物件。 建立會話選項物件時 New-PSSessionOption
,它會自動將 ApplicationArguments 參數值中的哈希表轉換成基本字典,以便可靠地將數據傳輸到遠端會話。
Cmdlet New-PSSession
會在 Server01 計算機上啟動作業階段。 它會使用 SessionOption 參數在變數中包含 $teamOption
選項。
Cmdlet Invoke-Command
示範變數中的數據 $team
可供遠端會話中的命令使用。 數據會出現在自動變數的 ApplicationArguments 屬性中 $PSSenderInfo
。
最後 Invoke-Command
顯示如何使用數據。
參數
-ApplicationArguments
指定傳送至遠端工作階段的基本字典。 遠程會話中的命令和文稿,包括會話設定中的啟動腳本,可以在自動變數的 $PSSenderInfo
ApplicationArguments 屬性中找到此字典。 您可以使用此參數將資料傳送至遠端工作階段。
如需詳細資訊,請參閱 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殼層逾時值 (WSMan:\<ComputerName>\Shell\IdleTimeout
) ,以最短為最短。
如果工作階段選項中設定的閒置逾時超出工作階段設定之 MaxIdleTimeoutMs 屬性的值,建立工作階段的命令會失敗。
默認 Microsoft.PowerShell 會話設定的 IdleTimeoutMs 值為 72000000 毫秒, (2 小時) 。 其 MaxIdleTimeoutMs 值2147483647毫秒, (>24 天) 。 WSMan 殼層閒置逾時 () 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
在服務主體名稱中包含埠號碼, (SPN) 用於 Kerberos 驗證,例如 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 MB。
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
決定工作階段中任何操作可以執行的最長時間。 當間隔時間過期時,操作就會失敗 輸入以毫秒為單位的值。
預設值為 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。 使用者也可以在中斷連線工作階段時變更輸出緩衝處理模式。
如果您省略此參數,會話選項物件的 OutputBufferingMode 值為 None。 Block 或 Drop 的值會覆寫工作階段設定中所設定的輸出緩衝模式傳輸選項。 此參數可接受的值為:
- 區塊。 當輸出緩衝區已滿時,會暫停執行直到清除緩衝區為止。
- Drop: 當輸出緩衝區已滿時,會繼續執行。 儲存新的輸出時,會捨棄最舊的輸出。
- 無。 未指定輸出緩衝模式。
如需輸出緩衝模式傳輸選項的詳細資訊,請參閱 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。
如需此參數值的相關信息,請參閱 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
指定用於 Proxy 解析的驗證方法。 此參數可接受的值為: 基本、 摘要和 交涉。 預設值為 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
指定要用於 Proxy 驗證的認證。 輸入包含 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。
輸出
備註
如果在命令中未使用 SessionOption 參數來建立 PSSession,則如果已設定會話選項,則會話選項是由喜好設定變數的 $PSSessionOption
屬性值所決定。 如需變數的詳細資訊 $PSSessionOption
,請參閱 about_Preference_Variables。
工作階段設定物件的屬性取決於工作階段設定所設定的選項,以及這些選項的值。 此外,使用工作階段設定檔的工作階段設定會有額外的屬性。