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>] Description
New-PSSessionOption Cmdlet 會建立物件，其中包含使用者管理會話的進階選項（PSSession）。 您可以使用 物件做為 cmdlet SessionOption 參數的值，這些 Cmdlet 會建立 PSSession，例如 New-PSSession、Enter-PSSession 和 Invoke-Command。
如果沒有參數，New-PSSessionOption 會產生物件，其中包含所有選項的預設值。 因為所有屬性都可以編輯，因此您可以使用產生的物件做為範本，併為您的企業建立標準選項物件。
您也可以將會話選項物件儲存在 $PSSessionOption 喜好設定變數中。 此變數的值會為會話選項建立新的預設值。 當會話未設定任何會話選項，且優先於會話組態中設定的選項時，它們就會生效，但是您可以在建立會話的 Cmdlet 中指定工作階段選項或會話選項物件來覆寫這些選項。 如需 $PSSessionOption 喜好設定變數的詳細資訊，請參閱 about_Preference_Variables。
當您在建立會話的 Cmdlet 中使用會話選項物件時，會話選項值會優先於在$PSSessionOption喜好設定變數和會話組態中設定之會話的預設值。 不過，它們不會優先於會話設定中設定的最大值、配額或限制。 如需工作階段組態的詳細資訊，請參閱 about_Session_Configurations。
範例
範例 1：建立預設會話選項
此命令會建立具有所有預設值的工作階段選項物件。
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 參數的值是具有 NoEncryption 和 NoCompression 參數 New-PSSessionOption 命令。
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：建立喜好設定變數
此命令會建立 $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：讓自變數可供遠程會話使用
此範例示範如何使用 New-PSSessionOption Cmdlet 的 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 建立會話選項物件時，它會自動將 ApplicationArgument s 值中的哈希表轉換成基本字典，以便將數據可靠地傳輸至遠端會話。
New-PSSession Cmdlet 會在 Server01 計算機上啟動作業階段。 它會使用 SessionOption 參數，將選項包含在 $teamOption 變數中。
Invoke-Command Cmdlet 示範遠端工作中的命令可以使用 $team 變數中的數據。 數據會出現在 $PSSenderInfo 自動變數的 ApplicationArguments 屬性中。
最後一個 Invoke-Command 會示範如何使用數據。
參數
-ApplicationArguments
指定傳送至遠端會話的基本字典。 遠程會話中的命令和腳本，包括會話組態中的啟動腳本，可以在 $PSSenderInfo 自動變數的 ApplicationArguments 屬性中找到此字典。 您可以使用此參數將資料傳送至遠端工作階段。
如需詳細資訊，請參閱 about_Hash_Tables、about_Session_Configurations和 about_Automatic_Variables。
| 類型: | PSPrimitiveDictionary |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-CancelTimeout
決定 PowerShell 等待取消作業完成的時間長度（CTRL+C），再結束。 以毫秒為單位輸入值。
默認值為 60000 （一分鐘）。 值為 0 （零） 表示沒有逾時;命令會無限期地繼續。
| 類型: | Int32 |
| 別名: | CancelTimeoutMSec |
| Position: | Named |
| 預設值: | 60000 |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-Culture
指定要用於工作階段的文化特性。 以 <languagecode2>-<country/regioncode2> 格式輸入文化特性名稱（例如 ja-JP）、包含 CultureInfo 物件的變數，或取得 CultureInfo 物件的命令。
默認值為 $Null，而操作系統中設定的文化特性則用於會話。
| 類型: | CultureInfo |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-IdleTimeout
判斷如果遠端電腦未收到來自本機計算機的任何通訊，會話會保持開啟的時間長度。 這包括活動訊號訊號。 當間隔到期時，會話就會關閉。
如果您想要中斷連線並重新連線到會話，閑置逾時值非常重要。 只有當工作階段沒有逾時時，您才能重新連線。
以毫秒為單位輸入值。 最小值為 60000 （1 分鐘）。 最大值是會話組態的 MaxIdleTimeoutms 屬性值。 預設值 -1 不會設定閑置逾時。
會話會使用會話選項中設定的閑置逾時，如果有的話。 如果未設定 （-1），會話會使用會話組態的 IdleTimeoutMs 屬性或 WSMan 殼層逾時值 （WSMan:\<ComputerName>\Shell\IdleTimeout），無論最短者。
如果會話選項中設定的閑置逾時超過會話組態的 MaxIdleTimeoutMs 屬性的值，則建立會話的命令會失敗。
默認 Microsoft.PowerShell 工作階段設定的 IdleTimeoutMs 值為 7200000 毫秒（2 小時）。 其 MaxIdleTimeoutMs 值為2147483647毫秒（>24 天）。 WSMan 殼層閒置逾時 （WSMan:\<ComputerName>\Shell\IdleTimeout） 的預設值為 7200000 毫秒（2 小時）。
從會話中斷連線或重新連線到會話時，會話的閑置逾時值也可以變更。 如需詳細資訊，請參閱 Disconnect-PSSession 和 Connect-PSSession。
在 Windows PowerShell 2.0 中，IdleTimeout 參數的預設值為 240000 （4 分鐘）。
| 類型: | Int32 |
| 別名: | IdleTimeoutMSec |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | 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 中引進的。
| 類型: | SwitchParameter |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-MaxConnectionRetryCount
指定當目前嘗試因網路問題而失敗時，PowerShell 嘗試連線到目標計算機的次數。 預設值為 5。
已針對 PowerShell 5.0 版新增此參數。
| 類型: | Int32 |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-MaximumReceivedDataSizePerCommand
指定本機電腦可以在單一命令中從遠端電腦接收的最大位元組數目。 以位元組為單位輸入值。 根據預設，沒有數據大小限制。
此選項的設計目的是保護用戶端電腦上的資源。
| 類型: | Int32 |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-MaximumReceivedObjectSize
指定本機電腦可以從遠端電腦接收的物件大小上限。 此選項的設計目的是保護用戶端電腦上的資源。 以位元組為單位輸入值。
在 Windows PowerShell 2.0 中，如果您省略此參數，則沒有任何物件大小限制。 從 Windows PowerShell 3.0 開始，如果您省略此參數，預設值為 200 MB。
| 類型: | Int32 |
| Position: | Named |
| 預設值: | 200 MB |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-MaximumRedirection
判斷 PowerShell 在連線失敗之前，將連線重新導向至替代統一資源識別碼 （URI） 的次數。 預設值為 5。 值為 0 （零） 會防止所有重新導向。
只有在建立會話的命令中使用 AllowRedirection 參數時，才會在會話中使用此選項。
| 類型: | Int32 |
| Position: | Named |
| 預設值: | 5 |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-NoCompression
關閉會話中的封包壓縮。 壓縮會使用更多的處理器週期，但它會加快傳送速率。
| 類型: | SwitchParameter |
| Position: | Named |
| 預設值: | False |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-NoEncryption
關閉數據加密。
| 類型: | SwitchParameter |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-NoMachineProfile
防止載入使用者的 Windows 使用者設定檔。 因此，會話可能會更快建立，但使用者特定的登錄設定、環境變數等專案和憑證無法在會話中使用。
| 類型: | SwitchParameter |
| Position: | Named |
| 預設值: | False |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-OpenTimeout
決定客戶端電腦等候建立會話連線的時間長度。 當間隔到期時，建立連線的命令會失敗。 以毫秒為單位輸入值。
默認值為180000 （3分鐘）。 值為 0 （零） 表示沒有逾時;命令會無限期地繼續。
| 類型: | Int32 |
| 別名: | OpenTimeoutMSec |
| Position: | Named |
| 預設值: | 180000 (3 minutes) |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-OperationTimeout
決定會話中任何作業可以執行的時間上限。 當間隔到期時，作業會失敗。 以毫秒為單位輸入值。
默認值為180000 （3分鐘）。 值為 0 （零） 表示沒有逾時;作業會無限期地繼續。
| 類型: | Int32 |
| 別名: | OperationTimeoutMSec |
| Position: | Named |
| 預設值: | 180000 (3 minutes) |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-OutputBufferingMode
決定當輸出緩衝區已滿時，命令輸出在中斷連線的會話中管理的方式。
如果未在工作階段或工作階段組態中設定輸出緩衝模式，則預設值為 [封鎖]。 使用者也可以在中斷會話連線時變更輸出緩衝模式。
如果您省略此參數，會話選項物件的 OutputBufferingMode 值為 None。 Block 或 Drop 的值會覆寫會話組態中設定的輸出緩衝模式傳輸選項。 此參數可接受的值為：
- 塊。 當輸出緩衝區已滿時，執行會暫停，直到緩衝區清除為止。
- 落。 當輸出緩衝區已滿時，執行會繼續。 儲存新輸出時，會捨棄最舊的輸出。
- 沒有。 未指定輸出緩衝模式。
如需輸出緩衝模式傳輸選項的詳細資訊，請參閱 New-PSTransportOption。
此參數是在 Windows PowerShell 3.0 中引進的。
| 類型: | OutputBufferingMode |
| 接受的值: | None, Drop, Block |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-ProxyAccessType
決定用來解析主機名的機制。 此參數可接受的值為：
- IEConfig
- WinHttpConfig
- AutoDetect
- NoProxyServer
- 沒有
預設值為 None。
如需此參數值的相關信息，請參閱 ProxyAccessType 列舉。
| 類型: | ProxyAccessType |
| 接受的值: | None, IEConfig, WinHttpConfig, AutoDetect, NoProxyServer |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-ProxyAuthentication
指定用於 Proxy 解析的驗證方法。 此參數可接受的值為：Basic、Digest和 Negotiate。 預設值為 Negotiate。
如需此參數值的詳細資訊，請參閱 AuthenticationMechanism 列舉。
| 類型: | AuthenticationMechanism |
| 接受的值: | Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos |
| Position: | Named |
| 預設值: | Negotiate |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-ProxyCredential
指定要用於 Proxy 驗證的認證。 輸入變數，其中包含 PSCredential 物件或取得 PSCredential 物件的命令，例如 Get-Credential 命令。 如果未設定此選項，則不會指定任何認證。
| 類型: | PSCredential |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-SkipCACheck
指定當它透過 HTTPS 連線時，用戶端不會驗證伺服器證書是由受信任的證書頒發機構單位 （CA） 簽署。
只有在使用其他機制信任遠端計算機時，才使用此選項，例如當遠端計算機是實體安全與隔離的網路一部分，或是遠端電腦在 WinRM 設定中列為受信任主機時。
| 類型: | SwitchParameter |
| Position: | Named |
| 預設值: | False |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-SkipCNCheck
指定伺服器的憑證一般名稱 （CN） 不需要符合伺服器的主機名。 此選項僅適用於使用 HTTPS 通訊協定的遠端作業。
只對受信任的電腦使用此選項。
| 類型: | SwitchParameter |
| Position: | Named |
| 預設值: | False |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-SkipRevocationCheck
不會驗證伺服器證書的撤銷狀態。
| 類型: | SwitchParameter |
| Position: | Named |
| 預設值: | False |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-UICulture
指定要用於會話的UI文化特性。
有效值包括：
-
<languagecode2>-<country/regioncode2>格式的文化特性名稱，例如ja-JP - 包含 CultureInfo 物件的變數
- 取得 CultureInfo 物件的命令，例如
Get-Culture
預設值為 $null，而當工作階段建立於工作階段時，作業系統中設定的 UI 文化特性則為 。
| 類型: | CultureInfo |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
-UseUTF16
指出此 Cmdlet 會以 UTF16 格式編碼要求，而不是 UTF8 格式。
| 類型: | SwitchParameter |
| Position: | Named |
| 預設值: | None |
| 必要: | False |
| 接受管線輸入: | False |
| 接受萬用字元: | False |
輸入
None
您無法使用管線將輸入傳送至此 Cmdlet。
輸出
備註
如果命令中未使用 SessionOption 參數來建立 PSSession，會話選項會由設定 $PSSessionOption 喜好設定變數的屬性值來決定。 如需 $PSSessionOption 變數的詳細資訊，請參閱 about_Preference_Variables。
會話組態對象的屬性會隨著會話組態和這些選項的值所設定的選項而有所不同。 此外，使用會話組態檔的會話組態也有其他屬性。