Set-PSSessionConfiguration
變更已登錄的工作階段設定屬性。
Syntax
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>]
Set-PSSessionConfiguration
[-Name] <String>
[-AssemblyName] <String>
[-ApplicationBase <String>]
[-ConfigurationTypeName] <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>]
Set-PSSessionConfiguration
[-Name] <String>
[-RunAsCredential <PSCredential>]
[-ThreadApartmentState <ApartmentState>]
[-ThreadOptions <PSThreadOptions>]
[-AccessMode <PSSessionConfigurationAccessMode>]
[-UseSharedProcess]
[-StartupScript <String>]
[-MaximumReceivedDataSizePerCommandMB <Double>]
[-MaximumReceivedObjectSizeMB <Double>]
[-SecurityDescriptorSddl <String>]
[-ShowSecurityDescriptorUI]
[-Force]
[-NoServiceRestart]
[-TransportOption <PSTransportOption>]
-Path <String>
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
Cmdlet 會 Set-PSSessionConfiguration
變更本機計算機上的會話設定屬性。
使用 Name 參數可以識別您想要變更的工作階段設定。 使用其他參數可以為工作階段設定的屬性指定新值。 若要從組態中刪除屬性值,並使用預設值,請輸入空字串 (“”) 或對應參數的值 $Null
。
從 PowerShell 3.0 開始,您可以使用工作階段設定檔來定義工作階段組態。 此功能為使用工作階段設定的工作階段,提供一個簡單且可探索的方法來設定和變更其屬性。 若要指定會話組態檔,請使用的 Set-PSSessionConfiguration
Path 參數。 如需會話配置檔的相關信息,請參閱 about_Session_Configuration_Files。
如需如何建立和修改會話配置文件的資訊,請參閱 New-PSSessionConfigurationFile
Cmdlet。
會話組態會定義連線到本機計算機的遠端會話環境 (PSSessions) 。 每個 PSSession 都會使用會話設定。 會話設定會決定 PSSession 的功能,例如會話中可用的模組、允許執行的 Cmdlet、語言模式、配額和逾時。 會話組態的安全性描述項會決定誰可以使用會話設定來連線到本機計算機。 如需會話設定的詳細資訊,請參閱 about_Session_Configurations。
若要查看會話設定的屬性,請使用 Get-PSSessionConfiguration
Cmdlet 或 WSMan 提供者。 如需 WSMan 提供者的詳細資訊,請輸入 Get-Help WSMan
。
範例
範例 1:變更線程 Apartment 狀態
PS C:\> Set-PSSessionConfiguration -Name "MaintenanceShell" -ThreadApartmentState STA
此命令將 MaintenanceShell 設定中的執行緒 Apartment 狀態變更為 STA。 當您重新啟動 WinRM 服務時,變更會有效。
範例 2:Create 並變更會話設定
此範例示範如何從組態新增和移除啟動腳本。
第一個命令會建立 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
範例 3:顯示結果
本範例會將 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
範例 4:以不同方式顯示結果
在這裡範例中, Set-PSSessionConfiguration
將 MaintenanceShell 工作階段組態中的啟動文稿變更為 Maintenance.ps1
。 輸出會顯示變更,並提示您重新啟動 WinRM 服務。 回應是 "y" (是)。
Get-PSSessionConfiguration
取得 MaintenanceShell 工作階段組態。 管線運算子 (|) 將命令的結果傳送至 Format-List
,這會在清單中顯示組態物件的所有屬性。 接下來,我們會使用 WSMan 提供者來檢視 MaintenanceShell 組態的初始化參數。 Get-ChildItem
(別名 dir
) 取得 MaintenanceShell 外掛程式之 InitializationParameters 節點中的子專案。 如需 WSMan 提供者的詳細資訊,請輸入 Get-Help wsman
。
PS> 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
PS> Get-PSSessionConfiguration MaintenanceShell | Format-List -Property *
xmlns : https://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 : https://schemas.microsoft.com/powershell/MaintenanceShell
SupportsOptions : true
ExactMatch : true
Capability : {Shell}
Permission :
PS> dir WSMan:\localhost\Plugin\MaintenanceShell\InitializationParameters
ParamName ParamValue
--------- ----------
PSVersion 2.0
startupscript c:\ps-test\Maintenance.ps1
參數
-AccessMode
啟用和停用工作階段設定,並判斷是否可以用於電腦上的遠端或本機工作階段。 此參數可接受的值為:
- 已停用。 停用工作階段設定。 它不能用於電腦的遠端或本機存取。 這個值會將會話組態的 Enabled 屬性設定 (
WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled
) 設為 False。 - 本機。 將 Network_Deny_All 項目新增到工作階段設定的安全性描述元。 本機計算機的使用者可以使用會話設定,在同一部計算機上建立本機回送會話,但遠端使用者遭到拒絕存取。
- 遠端。 將 Deny_All 和 Network_Deny_All 項目從工作階段設定的安全性描述元中移除。 本機電腦和遠端電腦的使用者可以使用工作階段設定來建立工作階段,並在這部電腦上執行命令。
預設值為 Remote。
其他 Cmdlet 稍後可以覆寫此參數的值。 例如, Enable-PSRemoting
Cmdlet 會啟用電腦上的所有會話設定,並允許遠端訪問它們,而 Disable-PSRemoting
Cmdlet 只允許本機存取電腦上的所有會話設定。
此參數是在 PowerShell 3.0 中引進。
Type: | PSSessionConfigurationAccessMode |
Accepted values: | Disabled, Local, Remote |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ApplicationBase
指定 AssemblyName 參數值中指定的元件檔案路徑 (*.dll) 。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-AssemblyName
指定組件名稱。 此 Cmdlet 會根據元件中定義的類別建立會話組態。
輸入定義會話組態之元件 .dll 檔的檔名或完整路徑。 如果您只輸入檔名,您可以在 ApplicationBase 參數的值中輸入路徑。
Type: | String |
Position: | 1 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ConfigurationTypeName
指定 AssemblyName 參數內的組件中定義的工作階段設定類型。 您指定的類型必須實作 System.Management.Automation.Remoting.PSSessionConfiguration 類別。
指定組件名稱時,此參數是必要的。
Type: | String |
Position: | 2 |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Confirm
在執行 Cmdlet 前提示您確認。
Type: | SwitchParameter |
Aliases: | cf |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Force
隱藏所有使用者提示,並在不提示的情況下重新啟動 WinRM 服務。 重新啟動服務可讓設定變更生效。
若要避免重新啟動並抑制重新啟動提示,請使用 NoServiceRestart 參數。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumReceivedDataSizePerCommandMB
指定可在任何單一遠端命令中傳送至這部計算機的數據量限制。 輸入資料大小 (單位為 MB)。 預設值為 50 MB。
如果在 ConfigurationTypeName 參數所指定的組態類型中定義數據大小限制,則會使用組態類型中的限制。 忽略此參數的值。
Type: | Double |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-MaximumReceivedObjectSizeMB
指定可在任何單一物件中傳送至這部電腦之數據量的限制。 以 MB 為單位輸入數據大小。 預設值為 10 MB。
如果在 ConfigurationTypeName 參數中指定的組態類型中定義物件大小限制,則會使用組態類型中的限制。 忽略此參數的值。
Type: | Double |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ModulesToImport
指定要自動匯入使用工作階段設定之工作階段的模組和嵌入式管理單元。 請輸入模組和嵌入式管理單元名稱。
根據預設,只有 Microsoft.PowerShell.Core 嵌入式管理單元會匯入會話,但除非排除 Cmdlet,否則您可以使用 Import-Module
和 Add-PSSnapin Cmdlet 將模組和嵌入式管理單元新增至會話。
除了工作階段組態檔中指定的模組之外,也會匯入此參數值中指定的模組 (New-PSSessionConfigurationFile
) 。 不過,工作階段設定檔中的設定可以隱藏模組所匯出的命令,或是防止使用者使用它們。
此參數值中指定的模組會取代 Cmdlet 的 Register-PSSessionConfiguration
ModulesToImport 參數所指定的模組清單。
此參數是在 PowerShell 3.0 中引進。
Type: | Object[] |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Name
指定您想要變更之工作階段設定的名稱。
您無法使用這個參數來變更工作階段設定的名稱。
Type: | String |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-NoServiceRestart
不會重新啟動 WinRM 服務,並隱藏重新啟動服務的提示。
根據預設,當您執行 Set-PSSessionConfiguration
時,系統會提示您重新啟動 WinRM 服務,讓新的工作階段設定生效。 在 重新啟動 WinRM 服務之前,新的工作階段設定無效。
若要重新啟動 WinRM 服務而不提示,請使用 Force 參數。 若要手動重新啟動 WinRM 服務,請使用 Restart-Service
Cmdlet。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Path
指定工作階段配置檔 (.pssc) 的路徑,例如 Cmdlet 所建立的路徑 New-PSSessionConfigurationFile
。 若省略路徑,則預設為目前目錄。
如需如何修改會話配置檔的相關信息,請參閱 Cmdlet 的說明 New-PSSessionConfigurationFile
主題。
此參數是在 PowerShell 3.0 中引進。
Type: | String |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-PSVersion
指定使用此工作階段組態之工作階段中的PowerShell版本。
此參數的值優先順序高於工作階段設定檔中的 PowerShellVersion 索引鍵值。
此參數是在 PowerShell 3.0 中引進。
Type: | Version |
Aliases: | PowerShellVersion |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-RunAsCredential
指定工作階段中命令的認證。 根據預設,命令以目前使用者的權限執行。
此參數是在 PowerShell 3.0 中引進。
Type: | PSCredential |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SecurityDescriptorSddl
為設定指定不同的 Security Descriptor Definition Language (SDDL) 字串。
此字串會決定使用新工作階段設定的必要權限。 若要在工作階段中使用工作階段設定,使用者至少必須具有設定的「執行 (叫用) 」許可權。
若要使用組態的預設安全性描述元,請輸入空字串 (“”“) 或 的值 $Null
。 預設值為 WSMan: 磁碟機中的根 SDDL。
如果安全性描述元很複雜,請考慮使用 ShowSecurityDescriptorUI 參數,而不是這個參數。 您無法在相同的命令中使用這兩個參數。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-SessionTypeOption
指定工作階段組態的類型特定選項。 輸入工作階段類型選項物件,例如 Cmdlet 傳回的 PSWorkflowExecutionOption 物件 New-PSWorkflowExecutionOption
。
使用工作階段設定之工作階段的選項,取決於工作階段選項和工作階段設定選項的值。 除非指定,否則在會話中設定的選項會優先於會話設定中設定的選項,例如使用 New-PSSessionOption
Cmdlet。 不過,工作階段選項值不能超過工作階段設定中設定的最大值。
此參數是在 PowerShell 3.0 中引進。
Type: | PSSessionTypeOption |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ShowSecurityDescriptorUI
指出這個 Cmdlet 的屬性表可協助您為工作階段設定建立新的 SDDL。 屬性表會出現在執行 Set-PSSessionConfiguration
命令之後,然後重新啟動 WinRM 服務。
當您將許可權設定為組態時,請記住,使用者至少必須擁有Execute (Invoke) 許可權,才能在工作階段中使用會話設定。
您無法在相同的命令中使用 SecurityDescriptorSDDL 參數與此參數。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-StartupScript
指定組態的啟動文稿。 輸入 PowerShell 腳本的完整路徑。 指定的指令碼會在使用工作階段設定的新工作階段中執行。
若要從會話設定中刪除啟動腳本,請輸入空字串 (“”) 或 的值 $Null
。
您可以使用啟動文稿進一步設定使用者工作階段。 如果腳本產生錯誤,即使發生非終止錯誤,也不會建立會話,而且 New-PSSession
命令會失敗。
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ThreadApartmentState
指定工作階段中線程的 Apartment 狀態設定。 此參數可接受的值為:STA、MTA 和 Unknown。 預設值為 [未知]。
Type: | ApartmentState |
Accepted values: | STA, MTA, Unknown |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-ThreadOptions
指定組態中的線程選項設定。 此設定會定義在工作階段中執行某個命令時,要如何建立及使用執行緒。 此參數可接受的值為:
- Default
- ReuseThread
- UseCurrentThread
- UseNewThread
默認值為 UseCurrentThread。
如需詳細資訊,請參閱 PSThreadOptions 列舉。
Type: | PSThreadOptions |
Accepted values: | Default, UseNewThread, ReuseThread, UseCurrentThread |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-TransportOption
指定工作階段組態的傳輸選項。 輸入傳輸選項物件,例如 Cmdlet 傳回的 WSManConfigurationOption 物件 New-PSTransportOption
。
使用工作階段設定之工作階段的選項,取決於工作階段選項和工作階段設定選項的值。 除非指定,否則在會話中設定的選項會優先於會話設定中設定的選項,例如使用 New-PSSessionOption
Cmdlet。 不過,工作階段選項值不能超過工作階段設定中設定的最大值。
此參數是在 PowerShell 3.0 中引進。
Type: | PSTransportOption |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-UseSharedProcess
只使用一個進程來裝載由相同用戶啟動的所有會話,並使用相同的會話設定。 根據預設,每個工作階段會裝載於自己的處理程序。
此參數是在 PowerShell 3.0 中引進。
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-WhatIf
顯示執行 Cmdlet 後會發生的情況。 Cmdlet 並不會執行。
Type: | SwitchParameter |
Aliases: | wi |
Position: | Named |
Default value: | False |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
輸入
None
您無法使用管線傳送輸入至此 Cmdlet。
輸出
備註
若要執行此 Cmdlet,請使用 [以系統管理員身分執行] 選項啟動 PowerShell。
Cmdlet Set-PSSessionConfiguration
不會變更組態名稱,而 WSMan 提供者不支援 Rename-Item
Cmdlet。 若要變更會話組態的名稱,請使用 Unregister-PSSessionConfiguration
Cmdlet 來刪除設定, Register-PSSessionConfiguration
然後使用 Cmdlet 來建立和註冊新的工作階段組態。
您可以使用 Set-PSSessionConfiguration
Cmdlet 來變更預設的 Microsoft.PowerShell 和 Microsoft.PowerShell32 會話設定。 它們並不受保護。 若要還原為預設會話設定的原始版本,請使用 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: 磁碟驅動器。
相關連結
- Disable-PSSessionConfiguration
- Enable-PSSessionConfiguration
- Get-PSSessionConfiguration
- New-PSSessionConfigurationFile
- New-PSSessionOption
- New-PSTransportOption
- New-PSWorkflowExecutionOption
- Register-PSSessionConfiguration
- Test-PSSessionConfigurationFile
- Unregister-PSSessionConfiguration
- WSMan 提供者
- about_Session_Configurations
- about_Session_Configuration_Files