New-PSSessionOption

參考

模組:: Microsoft.PowerShell.Core

建立包含 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

Cmdlet New-PSSessionOption 會建立物件，其中包含使用者管理的會話進階選項 (PSSession) 。您可以使用物件做為建立 PSSession 之 Cmdlet 的 SessionOption 參數值，例如 New-PSSession、 Enter-PSSession和 Invoke-Command。

如果沒有參數， New-PSSessionOption 會產生物件，其中包含所有選項的預設值。因為可以編輯每個屬性，所以您可以使用產生的物件做為範本，併為您的企業建立標準選項物件。

您也可以在$PSSessionOption喜好設定變數中儲存 SessionOption 物件。此變數的值會替工作階段選項建立新的預設值。當會話未設定任何會話選項且優先順序高於會話組態中設定的選項時，您可以藉由在建立會話的 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 Check 變數用於 SessionOption 參數的值。

由於計算機是由其IP位址識別， 所以 ComputerName 參數的值與用於安全套接字層 (SSL) 憑證中的任何通用名稱不符。因此，需要 SkipCNCheck 選項。

範例 7：讓自變數可供遠程會話使用

此範例示範如何使用 Cmdlet 的 New-PSSessionOptionApplicationArguments 參數，讓其他數據可供遠程會話使用。

$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。

接下來，使用 ApplicationArguments 參數的 New-PSSessionOption Cmdlet 會建立儲存在變數中的 $teamSessionOption 物件。建立會話選項物件時 New-PSSessionOption ，它會將 ApplicationArguments 參數值中的哈希表自動轉換成 PrimitiveDictionary ，以便將數據可靠地傳輸至遠端會話。

Cmdlet 會在 New-PSSession Server01 計算機上啟動作業階段。它會使用 SessionOption 參數，在變數中包含 $teamOption 選項。

Cmdlet Invoke-Command 示範變數中的數據 $team 可供遠端會話中的命令使用。數據會出現在自動變數的 $PSSenderInfoApplicationArguments 屬性中。

最後 Invoke-Command 顯示如何使用數據。

參數

-ApplicationArguments

指定傳送至遠端會話的 PrimitiveDictionary 。遠程會話中的命令和腳本，包括會話組態中的啟動腳本，可以在自動變數的 $PSSenderInfoApplicationArguments 屬性中找到此字典。您可以使用此參數將資料傳送至遠端工作階段。

如需詳細資訊，請參閱 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 會話組態7200000的 IdleTimeoutMs 值為毫秒 (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

包含用於 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 物件的 NoneOutputBufferingMode 值為。或 Drop 的值Block會覆寫會話組態中所設定的輸出緩衝模式傳輸選項。此參數可接受的值為：

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

指定用於 Proxy 解析的驗證方法。此參數可接受的值為：

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

指定要用於 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。

輸出

PSSessionOption

備註

如果未在命令中使用 SessionOption 參數來建立 PSSession，則會話選項是由喜好設定變數的 $PSSessionOption 屬性值所決定。如果已設定，工作階段選項。如需變數的詳細資訊 $PSSessionOption ，請參閱 about_Preference_Variables。

工作階段設定物件的屬性取決於工作階段設定所設定的選項，以及這些選項的值。此外，使用工作階段設定檔的工作階段設定會有額外的屬性。

共用方式為

New-PSSessionOption

Syntax

Description

範例

範例 1：Create 預設工作階段選項

範例 2：使用會話選項物件設定會話

範例 3：啟動互動式會話

範例 4：修改會話選項物件

範例 5：Create 喜好設定變數

範例 6：滿足遠端會話設定的需求

範例 7：讓自變數可供遠程會話使用

參數

-ApplicationArguments

-CancelTimeout

-Culture

-IdleTimeout

-IncludePortInSPN

-MaxConnectionRetryCount

-MaximumReceivedDataSizePerCommand

-MaximumReceivedObjectSize

-MaximumRedirection

-NoCompression

-NoEncryption

-NoMachineProfile

-OpenTimeout

-OperationTimeout

-OutputBufferingMode

-ProxyAccessType

-ProxyAuthentication

-ProxyCredential

-SkipCACheck

-SkipCNCheck

-SkipRevocationCheck

-UICulture

-UseUTF16

輸入

輸出

備註

其他資源

共用方式為

New-PSSessionOption

Syntax

Description

範例

範例 1：Create 預設工作階段選項

範例 2：使用會話選項物件設定會話

範例 3：啟動互動式會話

範例 4：修改會話選項物件

範例 5：Create 喜好設定變數

範例 6：滿足遠端會話設定的需求

範例 7：讓自變數可供遠程會話使用

參數

-ApplicationArguments

-CancelTimeout

-Culture

-IdleTimeout

-IncludePortInSPN

-MaxConnectionRetryCount

-MaximumReceivedDataSizePerCommand

-MaximumReceivedObjectSize

-MaximumRedirection

-NoCompression

-NoEncryption

-NoMachineProfile

-OpenTimeout

-OperationTimeout

-OutputBufferingMode

-ProxyAccessType

-ProxyAuthentication

-ProxyCredential

-SkipCACheck

-SkipCNCheck

-SkipRevocationCheck

-UICulture

-UseUTF16

輸入

輸出

備註

相關連結

其他資源