共用方式為

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 。 此變數的值會替工作階段選項建立新的預設值。 在沒有為工作階段設定任何工作階段選項時，它們就會生效，而且它們的優先順序高於在工作階段設定中設定的選項，但是您可以透過在建立工作階段的 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-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。

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

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

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

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

參數

-ApplicationArguments

指定傳送至遠端工作階段的基本字典。 遠程會話中的命令和文稿，包括會話設定中的啟動腳本，可以在自動變數的 $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 會話設定的 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。

輸出

PSSessionOption

備註

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

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