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 會產生物件，其中包含所有選項的預設值。 因為每個屬性都可以編輯，因此您可以使用產生的物件做為範本，併為企業建立標準選項物件。

您也可以將 SessionOption 物件儲存在喜好設定變數中$PSSessionOption。 此變數的值會為會話選項建立新的預設值。 當會話未設定任何會話選項，且優先於會話組態中設定的選項時，它們就會有效，但是您可以在建立會話的 Cmdlet 中指定會話選項或 SessionOption 物件來覆寫這些選項。 如需喜好設定變數的詳細資訊 $PSSessionOption ，請參閱 about_Preference_Variables。

當您在建立 會話的 Cmdlet 中使用 SessionOption 物件時，會話選項值會優先於喜好設定變數和會話組態中 $PSSessionOption 設定之會話的預設值。 不過，它們不會優先於會話設定中設定的最大值、配額或限制。 如需工作階段設定的詳細資訊，請參閱 about_Session_Configurations。

範例

範例 1：建立預設會話選項

此命令會建立 具有預設值的 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：建立喜好設定變數

此命令會 $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-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。

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

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

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

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

參數

-ApplicationArguments

指定 傳送至遠端會話的 PrimitiveDictionary 。 遠程會話中的命令和腳本，包括會話組態中的啟動腳本，可以在自動變數的 $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 會話組態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 開始，如果您省略此參數，預設值為 209715200 bytes （或 200MB）。

Type:Int32
Position:Named
Default value:209715200
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 物件的 OutputBufferingMode 值為 None。 或的值BlockDrop會覆寫會話組態中設定的輸出緩衝模式傳輸選項。 此參數可接受的值為：

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

會話組態對象的屬性會隨著會話組態和這些選項的值所設定的選項而有所不同。 此外，使用會話組態檔的會話組態也有其他屬性。