Set-PSSessionConfiguration

變更註冊會話設定的屬性。

語法

NameParameterSet (預設值)

Set-PSSessionConfiguration
    [-Name] <String>
    [-ApplicationBase <String>]
    [-RunAsCredential <PSCredential>]
    [-ThreadApartmentState <ApartmentState>]
    [-ThreadOptions <PSThreadOptions>]
    [-AccessMode <PSSessionConfigurationAccessMode>]
    [-UseSharedProcess]
    [-StartupScript <String>]
    [-MaximumReceivedDataSizePerCommandMB <Double>]
    [-MaximumReceivedObjectSizeMB <Double>]
    [-SecurityDescriptorSddl <String>]
    [-ShowSecurityDescriptorUI]
    [-Force]
    [-NoServiceRestart]
    [-PSVersion <Version>]
    [-SessionTypeOption <PSSessionTypeOption>]
    [-TransportOption <PSTransportOption>]
    [-ModulesToImport <Object[]>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

AssemblyNameParameterSet

Set-PSSessionConfiguration
    [-Name] <String>
    [-AssemblyName] <String>
    [-ConfigurationTypeName] <String>
    [-ApplicationBase <String>]
    [-RunAsCredential <PSCredential>]
    [-ThreadApartmentState <ApartmentState>]
    [-ThreadOptions <PSThreadOptions>]
    [-AccessMode <PSSessionConfigurationAccessMode>]
    [-UseSharedProcess]
    [-StartupScript <String>]
    [-MaximumReceivedDataSizePerCommandMB <Double>]
    [-MaximumReceivedObjectSizeMB <Double>]
    [-SecurityDescriptorSddl <String>]
    [-ShowSecurityDescriptorUI]
    [-Force]
    [-NoServiceRestart]
    [-PSVersion <Version>]
    [-SessionTypeOption <PSSessionTypeOption>]
    [-TransportOption <PSTransportOption>]
    [-ModulesToImport <Object[]>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

SessionConfigurationFile

Set-PSSessionConfiguration
    [-Name] <String>
    -Path <String>
    [-RunAsCredential <PSCredential>]
    [-ThreadApartmentState <ApartmentState>]
    [-ThreadOptions <PSThreadOptions>]
    [-AccessMode <PSSessionConfigurationAccessMode>]
    [-UseSharedProcess]
    [-StartupScript <String>]
    [-MaximumReceivedDataSizePerCommandMB <Double>]
    [-MaximumReceivedObjectSizeMB <Double>]
    [-SecurityDescriptorSddl <String>]
    [-ShowSecurityDescriptorUI]
    [-Force]
    [-NoServiceRestart]
    [-TransportOption <PSTransportOption>]
    [-WhatIf]
    [-Confirm]
    [<CommonParameters>]

Description

此 Cmdlet 只能在 Windows 平臺上使用。

該 Set-PSSessionConfiguration cmdlet 會改變本地電腦上會話設定的屬性。

使用 Name 參數來識別你想更改的 session 設定。 使用其他參數來指定會話設定屬性的新值。 若要從設定中刪除屬性值並使用預設值,請輸入空字串("")或對應參數的值 $null 。

從 PowerShell 3.0 開始,你可以使用會話設定檔來定義會話設定。 此功能提供一種簡單且可發現的方法,用於設定與變更使用會話設定的會話屬性。 若要指定會話設定檔,請使用 Path 參數。Set-PSSessionConfiguration 關於會話設定檔的資訊,請參見 about_Session_Configuration_Files。 關於如何建立及修改會話設定檔的資訊,請參閱 cmdlet。New-PSSessionConfigurationFile

會話設定定義了連接至本地電腦的遠端會話(PSSessions)環境。 每個 PSSession 都會使用會話設定。 會話設定決定了 PSSession 的功能,例如會話中可用的模組、允許執行的 cmdlet、語言模式、配額與逾時。 會話設定的安全描述符決定誰可以使用該會話設定連接本地電腦。 如需工作階段組態的詳細資訊,請參閱 about_Session_Configurations。

要查看會話設定的屬性,請使用 Get-PSSessionConfiguration cmdlet 或 WSMan Provider。 欲了解更多關於WSMan Provider的資訊,請輸入 Get-Help WSMan。

範例

範例 1:建立並變更會話設定

這個範例展示了如何從設定中新增或移除啟動腳本。

第一個指令會建立 AdminShell 設定。 第二個指令則將 AdminConfig.ps1 腳本加入設定中。 這個變更在重新啟動 WinRM 時生效。 第三個指令會將腳本從設定中移除 AdminConfig.ps1 。

Register-PSSessionConfiguration -Name "AdminShell" -AssemblyName "C:\Shells\AdminShell.dll" -ConfigurationTypeName "AdminClass"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript "AdminConfig.ps1"
Set-PSSessionConfiguration -Name "AdminShell" -StartupScript $null

範例 2:顯示結果

此範例將 MaximumReceivedObjectSizeMB 屬性的值提升至 20。 這個指令也會提示你重新啟動 WinRM 服務。 此變更在 WinRM 服務重新啟動後才會生效。

Set-PSSessionConfiguration -Name "IncObj" -MaximumReceivedObjectSizeMB 20
WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\IncObj\InitializationParameters

ParamName                       ParamValue
---------                       ----------
psmaximumreceivedobjectsizemb   20

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run the command "Restart-Service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

範例 3:顯示結果以不同方式呈現

在此範例中, Set-PSSessionConfiguration 將 MaintenanceShell 會話設定中的啟動腳本改為 Maintenance.ps1。 輸出會顯示變更並提示你重新啟動 WinRM 服務。 答案是 y (是的)。

Get-PSSessionConfiguration 取得 MaintenanceShell 會話配置。 管線運算子(|)會將指令的結果傳送到 Format-List,該指令會以清單形式顯示該組態物件的所有屬性。 接著,使用 WSMan 提供者,我們查看 MaintenanceShell 配置的初始化參數。 Get-ChildItem取得 MaintenanceShell 外掛的 InitializationParameters 節點中的子項目。 欲了解更多WSMan供應商資訊,請輸入 Get-Help WSMan。

Set-PSSessionConfiguration -Name "MaintenanceShell" -StartupScript "C:\ps-test\Maintenance.ps1"
WSManConfig: Microsoft.WSMan.Management\WSMan::localhost\Plugin\MaintenanceShell\InitializationParameters

ParamName            ParamValue
---------            ----------
startupscript        C:\ps-test\Mainte...

"Restart WinRM service"
WinRM service need to be restarted to make the changes effective. Do you want to run
the command "Restart-Service winrm"?
[Y] Yes  [N] No  [S] Suspend  [?] Help (default is "Y"): y

Get-PSSessionConfiguration MaintenanceShell | Format-List -Property *
xmlns            : http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration
Name             : MaintenanceShell
Filename         : %windir%\system32\pwrshplugin.dll
SDKVersion       : 1
XmlRenderingType : text
lang             : en-US
PSVersion        : 2.0
startupscript    : C:\ps-test\Maintenance.ps1
ResourceUri      : http://schemas.microsoft.com/powershell/MaintenanceShell
SupportsOptions  : true
ExactMatch       : true
Capability       : {Shell}
Permission       :
Get-ChildItem WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters
ParamName     ParamValue
---------     ----------
PSVersion     2.0
startupscript C:\ps-test\Maintenance.ps1

參數

-AccessMode

啟用與停用會話設定,並判斷該設定是否可用於電腦上的遠端或本地會話。 此參數可接受的值為:

  • Disabled。 停用會話設定。 它無法用於遠端或本地存取電腦。 此值將會話設定WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled的 Enabled 屬性()設定為 False。
  • Local。 為會話設定的安全描述符新增 Network_Deny_All 條目。 本地電腦的使用者可以使用會話設定在同一台電腦上建立本地迴圈會話,但遠端使用者則被拒絕存取。
  • Remote。 移除會話組態安全描述符中的 Deny_All 條目與 Network_Deny_All 條目。 本地及遠端電腦的使用者可使用會話設定建立會話並在該電腦上執行指令。

預設值為 遠端。

其他指令小程式之後可以覆寫此參數的值。 例如, Enable-PSRemoting cmdlet 啟用電腦上的所有會話設定並允許遠端存取,而 Disable-PSRemoting cmdlet 則僅允許本地存取電腦上所有會話設定。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:PSSessionConfigurationAccessMode
預設值:None
接受的值:Disabled, Local, Remote
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-ApplicationBase

指定組合檔(*.dll)的路徑,該路徑由 AssemblyName 參數的值設定。

參數屬性

類型:String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

NameParameterSet
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False
AssemblyNameParameterSet
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-AssemblyName

指定組裝名稱。 此 cmdlet 會根據在組件中定義的類別建立一個會話配置。

輸入定義會話設定的組合檔案 .dll 的檔名或完整路徑。 如果你只輸入檔名,可以在 ApplicationBase 參數的值中輸入路徑。

參數屬性

類型:String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

AssemblyNameParameterSet
Position:1
必要:True
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-ConfigurationTypeName

在 AssemblyName 參數中指定會話組態的類型。 你指定的類型必須實作 System.Management.Automation.Remoting.PSSessionConfiguration 類別。

這個參數在指定組裝名稱時是必須的。

參數屬性

類型:String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

AssemblyNameParameterSet
Position:2
必要:True
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-Confirm

在執行 Cmdlet 之前,提示您進行確認。

參數屬性

類型:SwitchParameter
預設值:False
支援萬用字元:False
不要顯示:False
別名:參見

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-Force

會抑制所有使用者提示,並在不提示的情況下重新啟動 WinRM 服務。 重新啟動服務後,設定變更才會有效。

為了防止重新啟動並抑制重新啟動提示,請使用 NoServiceRestart 參數。

參數屬性

類型:SwitchParameter
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-MaximumReceivedDataSizePerCommandMB

規定任何單一遠端指令可傳送至此電腦的資料量限制。 輸入資料大小(MB)。 預設值為 50。

若在 ConfigurationTypeName 參數中指定的組態類型中定義了資料大小限制,則會使用該組態類型的限制。 這個參數的值會被忽略。

參數屬性

類型:

Nullable<T>[Double]

預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-MaximumReceivedObjectSizeMB

規定任何單一物件中可傳送至此電腦的資料量限制。 輸入資料大小(以兆位元組為單位)。 預設值為 10。

若在 ConfigurationTypeName 參數中指定的配置類型中定義了物件大小限制,則會使用該配置類型的限制。 這個參數的值會被忽略。

參數屬性

類型:

Nullable<T>[Double]

預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-ModulesToImport

指定自動匯入會話組態的模組和嵌入式管理單元。 輸入模組和 snap-in 名稱。

預設情況下,只有 Microsoft。PowerShell.Core 模組會匯入會話中,但除非 cmdlet 被排除,否則你可以使用 Import-Module 和 Add-PSSnapin cmdlet 將模組和 snap-in 加入到會話中。

此參數值中指定的模組會被匯入到會話設定檔()New-PSSessionConfigurationFile中指定的模組之外。 然而,會話設定檔中的設定可能會隱藏模組匯出的指令,或阻止使用者使用這些指令。

此參數值中指定的模組會以 cmdlet 的 Register-PSSessionConfigurationModulesToImport 參數取代指定的模組清單。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:

Object[]

預設值:None
支援萬用字元:False
不要顯示:False

參數集

NameParameterSet
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False
AssemblyNameParameterSet
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-Name

指定你想更改的會話設定名稱。

你不能用這個參數來更改會話設定的名稱。

參數屬性

類型:String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:0
必要:True
來自管線的值:False
來自管線按屬性名稱的值:True
來自剩餘引數的值:False

-NoServiceRestart

不會重新啟動 WinRM 服務,並抑制重新啟動服務的提示。

預設情況下,當你執行 Set-PSSessionConfiguration時,會被提示重新啟動 WinRM 服務,以使新的會話設定有效。 在 WinRM 服務重新啟動之前,新的會話設定無法生效。

若要在不提示的情況下重新啟動 WinRM 服務,請使用 Force 參數。 若要手動重新啟動 WinRM 服務,請使用 Restart-Service cmdlet。

參數屬性

類型:SwitchParameter
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-Path

指定會話設定檔(.pssc如由 cmdlet 建立 New-PSSessionConfigurationFile 的)路徑。 如果你省略路徑,預設就是目前的目錄。

如需如何修改會話設定檔,請參閱 cmdlet 的說明主題 New-PSSessionConfigurationFile 。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

SessionConfigurationFile
Position:Named
必要:True
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-PSVersion

指定使用此會話設定的 PowerShell 版本。

此參數的值優先於會話設定檔中 PowerShellVersion 鍵值。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:Version
預設值:None
支援萬用字元:False
不要顯示:False
別名:PowerShellVersion

參數集

NameParameterSet
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False
AssemblyNameParameterSet
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-RunAsCredential

指定會話中指令的憑證。 預設情況下,指令執行時會保留當前使用者的權限。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:PSCredential
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-SecurityDescriptorSddl

指定配置所需的不同安全描述符定義語言(SDDL)字串。

此字串決定使用新會話設定所需的權限。 要在會話中使用會話設定,使用者至少必須擁有 Execute(Invoke) 該設定的權限。

若要使用預設的安全描述符,請輸入空字串("")或值。$null 預設是硬碟裡 WSMan: 的根 SDDL。

如果安全描述符很複雜,可以考慮使用 ShowSecurityDescriptorUI 參數來取代這個參數。 你不能在同一個指令中使用兩個參數。

參數屬性

類型:String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-SessionTypeOption

指定會話設定的類型專屬選項。 輸入一個會話型態的選項物件,例如 psworkflowExecutionOption 物件, New-PSWorkflowExecutionOption 該指令長會回傳它。

使用會話設定的會話選項由會話選項的值與會話設定選項決定。 除非特別指定,會話中設定的選項(如 New-PSSessionOption cmdlet)優先於會話設定中的選項。 然而,會話選項值不得超過會話設定中設定的最大值。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:PSSessionTypeOption
預設值:None
支援萬用字元:False
不要顯示:False

參數集

NameParameterSet
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False
AssemblyNameParameterSet
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-ShowSecurityDescriptorUI

當使用這個參數時,cmdlet 會開啟一個屬性表,幫助你為會話設定建立新的 SDDL。 執行 Set-PSSessionConfiguration 指令後,屬性表會顯示出來,然後重新啟動 WinRM 服務。

當你設定設定權限時,記得使用者至少必須有 Execute(Invoke) 權限在會話中使用該設定。

你不能在同一指令中使用 SecurityDescriptorSDDL 參數和這個參數。

參數屬性

類型:SwitchParameter
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-StartupScript

指定設定的啟動腳本。 這時就進入了 PowerShell 腳本的完整合格路徑。 指定的腳本會在使用該會話設定的新工作階段中執行。

若要從會話設定中刪除啟動腳本,請輸入空字串()""或值。$null

你可以使用啟動腳本進一步設定使用者會話。 如果腳本產生錯誤,即使是非終止錯誤,該會話不會被建立,指令 New-PSSession 也會失敗。

參數屬性

類型:String
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-ThreadApartmentState

指定要使用的執行緒模組的公寓狀態。 可接受的值為:

  • Unknown
  • MTA
  • STA

參數屬性

類型:ApartmentState
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-ThreadOptions

在設定中指定執行緒選項設定。 此設定定義了執行緒在會話中執行指令時的建立與使用方式。 此參數可接受的值為:

  • Default
  • ReuseThread
  • UseCurrentThread
  • UseNewThread

預設值為 UseCurrentThread。

欲了解更多資訊,請參閱 PSThreadOptions 列舉。

參數屬性

類型:PSThreadOptions
預設值:None
接受的值:Default, UseNewThread, ReuseThread, UseCurrentThread
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-TransportOption

指定會話設定的傳輸選項。 輸入一個傳輸選項物件,例如 WSManConfigurationOption 物件, New-PSTransportOption 這是 cmdlet 回傳的物件。

使用會話設定的會話選項由會話選項的值與會話設定選項決定。 除非特別指定,會話中設定的選項(如 New-PSSessionOption cmdlet)優先於會話設定中的選項。 然而,會話選項值不得超過會話設定中設定的最大值。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:PSTransportOption
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-UseSharedProcess

只用一個程序來承載所有由同一使用者啟動且使用相同會話設定的會話。 預設情況下,每個會話都以自己的程序承載。

此參數是在 PowerShell 3.0 中引進的。

參數屬性

類型:SwitchParameter
預設值:None
支援萬用字元:False
不要顯示:False

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

-WhatIf

顯示 Cmdlet 執行時會發生什麼事。 指令未執行。

參數屬性

類型:SwitchParameter
預設值:False
支援萬用字元:False
不要顯示:False
別名:威斯康辛

參數集

(All)
Position:Named
必要:False
來自管線的值:False
來自管線按屬性名稱的值:False
來自剩餘引數的值:False

CommonParameters

此 cmdlet 支援常見參數:-Debug、-ErrorAction、-ErrorVariable、-InformationAction、-InformationVariable、-OutBuffer、-OutVariable、-PipelineVariable、-ProgressAction、-Verbose、-WarningAction 和 -WarningVariable。 如需詳細資訊,請參閱 about_CommonParameters。

輸入

None

您不能將物件透過管道傳送到此 Cmdlet。

輸出

WSManConfigLeafElement

備註

此 Cmdlet 僅適用於 Windows 平臺。

若要執行此 Cmdlet,請使用 [以系統管理員身分執行] 選項 啟動 PowerShell。

Set-PSSessionConfiguration指令檔不會更改設定名稱,且 WSMan 提供者不支援該Rename-Item指令檔。 要更改會話組的名稱,請使用 Unregister-PSSessionConfiguration cmdlet 刪除該組設定,然後再用 Register-PSSessionConfiguration cmdlet 建立並註冊新的會話組態。

你可以使用 Set-PSSessionConfiguration 指令小程式來更改預設的 Microsoft.PowerShell 和 Microsoft.PowerShell32 session 設定。 他們沒有受到保護。 要回復預設會話設定的原始版本,請使用 Unregister-PSSessionConfiguration cmdlet 刪除預設會話設定,然後再用 Enable-PSRemoting cmdlet 還原它。

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

你可以在磁碟機裡用指令 WSMan: 來更改會話設定的屬性。 然而,你無法在 PowerShell 2.0 中使用該 WSMan: 磁碟機更改 PowerShell 3.0 中引入的會話設定屬性,例如 OutputBufferingMode。 Windows PowerShell 2.0 指令不會產生錯誤,但它們是無效的。 若要更改 PowerShell 3.0 中引入的屬性,請使用 PowerShell 3.0 或更新版本中的磁碟機 WSMan: 。