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 僅適用于 Windows 平臺。

Cmdlet 會 Set-PSSessionConfiguration 變更本機電腦上的會話設定屬性。

使用 Name 參數可以識別您想要變更的工作階段設定。 使用其他參數可以為工作階段設定的屬性指定新值。 若要從組態中刪除屬性值,並使用預設值,請輸入空字串 ("") 或對應參數的值 $Null

從 PowerShell 3.0 開始,您可以使用會話組態檔來定義會話組態。 此功能為使用工作階段設定的工作階段,提供一個簡單且可探索的方法來設定和變更其屬性。 若要指定會話組態檔,請使用 的 Set-PSSessionConfigurationPath參數。 如需會話組態檔的相關資訊,請參閱 about_Session_Configuration_Files。 如需如何建立和修改會話組態檔的資訊,請參閱 New-PSSessionConfigurationFile Cmdlet。

會話組態會定義連線到本機電腦的遠端會話環境 (PSSessions) 。 每個 PSSession 都會使用會話設定。 會話組態會決定 PSSession的功能,例如會話中可用的模組、允許執行的 Cmdlet、語言模式、配額和逾時。 會話設定的安全性描述元會決定誰可以使用會話組態連線到本機電腦。 如需會話設定的詳細資訊,請參閱 about_Session_Configurations

若要查看會話組態的屬性,請使用 Get-PSSessionConfiguration Cmdlet 或 WSMan 提供者。 如需 WSMan 提供者的詳細資訊,請輸入 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-PSSessionConfigurationMaintenanceShell 會話組態中的啟動腳本變更為 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. 停用工作階段設定。 它不能用於電腦的遠端或本機存取。 此值會將會話組態的 Enabled 屬性設定 (WSMan:\<ComputerName>\PlugIn\<SessionConfigurationName>\Enabled) 設定為 False
  • Local. 將 Network_Deny_All 項目新增到工作階段設定的安全性描述元。 本機電腦的使用者可以使用會話設定,在同一部電腦上建立本機回送會話,但遠端使用者遭到拒絕存取。
  • Remote. 將 Deny_AllNetwork_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
Accept pipeline input:False
Accept wildcard characters:False
-ApplicationBase

指定元件檔 *.dll () 在 AssemblyName 參數的值中指定的路徑。

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-AssemblyName

指定組件名稱。 此 Cmdlet 會根據元件中定義的類別建立會話組態。

輸入定義會話組態之元件 .dll 檔的檔案名或完整路徑。 如果您只輸入檔案名,您可以在 ApplicationBase 參數的值中輸入路徑。

Type:String
Position:1
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ConfigurationTypeName

指定 AssemblyName 參數內的組件中定義的工作階段設定類型。 您指定的類型必須實作 System.Management.Automation.Remoting.PSSessionConfiguration 類別。

指定組件名稱時,此參數是必要的。

Type:String
Position:2
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Confirm

在執行 Cmdlet 前提示您確認。

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False
-Force

隱藏所有使用者提示,並在不提示的情況下重新開機 WinRM 服務。 重新啟動服務可讓設定變更生效。

若要避免重新啟動並抑制重新啟動提示,請使用 NoServiceRestart 參數。

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-MaximumReceivedDataSizePerCommandMB

指定可在任何單一遠端命令中傳送至這部電腦之資料量的限制。 輸入資料大小 (單位為 MB)。 預設值為 50

如果在 ConfigurationTypeName 參數中指定的組態類型中定義資料大小限制,則會使用組態類型中的限制。 忽略此參數的值。

Type:Nullable<T>[Double]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-MaximumReceivedObjectSizeMB

指定可在任何單一物件中傳送至這部電腦之資料量的限制。 以 MB 為單位輸入資料大小。 預設值為 10

如果在 ConfigurationTypeName 參數中指定的組態類型中定義物件大小限制,則會使用組態類型中的限制。 忽略此參數的值。

Type:Nullable<T>[Double]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ModulesToImport

指定要自動匯入使用工作階段設定之工作階段的模組和嵌入式管理單元。 請輸入模組和嵌入式管理單元名稱。

根據預設,只有 Microsoft.PowerShell.Core 模組會匯入會話,但除非排除 Cmdlet,否則您可以使用 Import-ModuleAdd-PSSnapin Cmdlet 將模組和嵌入式管理單元新增至會話。

除了會話組態檔中指定的模組之外,這個參數值中指定的模組也會匯入 (New-PSSessionConfigurationFile) 。 不過,工作階段設定檔中的設定可以隱藏模組所匯出的命令,或是防止使用者使用它們。

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

此參數是在 PowerShell 3.0 中引進。

Type:Object[]
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Name

指定您想要變更之工作階段設定的名稱。

您無法使用這個參數來變更工作階段設定的名稱。

Type:String
Position:0
Default value:None
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
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
Accept pipeline input:False
Accept wildcard characters:False
-PSVersion

指定使用此會話組態之會話中的 PowerShell 版本。

此參數的值優先順序高於工作階段設定檔中的 PowerShellVersion 索引鍵值。

此參數是在 PowerShell 3.0 中引進。

Type:Version
Aliases:PowerShellVersion
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-RunAsCredential

指定會話中命令的認證。 根據預設,命令以目前使用者的權限執行。

此參數是在 PowerShell 3.0 中引進。

Type:PSCredential
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-SecurityDescriptorSddl

為設定指定不同的 Security Descriptor Definition Language (SDDL) 字串。

此字串會決定使用新工作階段設定的必要權限。 若要在會話中使用會話組態,使用者必須至少有 Execute(Invoke) 設定的許可權。

若要使用組態的預設安全性描述元,請輸入空字串 ("") 或 的值 $Null 。 預設值是磁片磁碟機中的 WSMan: 根 SDDL。

如果安全性描述元很複雜,請考慮使用 ShowSecurityDescriptorUI 參數,而不是這個參數。 您無法在相同的命令中使用這兩個參數。

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-SessionTypeOption

指定會話組態的類型特定選項。 輸入會話類型選項物件,例如 Cmdlet 傳回的 New-PSWorkflowExecutionOptionPSWorkflowExecutionOption物件。

使用工作階段設定之工作階段的選項,取決於工作階段選項和工作階段設定選項的值。 除非指定,否則在會話中設定的選項,例如使用 New-PSSessionOption Cmdlet,優先于會話組態中設定的選項。 不過,工作階段選項值不能超過工作階段設定中設定的最大值。

此參數是在 PowerShell 3.0 中引進。

Type:PSSessionTypeOption
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ShowSecurityDescriptorUI

使用此參數時,Cmdlet 會開啟屬性工作表,以協助您為會話設定建立新的 SDDL。 屬性工作表會出現在執行 Set-PSSessionConfiguration 命令之後,然後重新開機 WinRM 服務。

當您將許可權設定為組態時,請記住,使用者必須至少有 Execute(Invoke) 許可權才能在會話中使用會話組態。

您無法在相同的命令中使用 SecurityDescriptorSDDL 參數與此參數。

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-StartupScript

指定組態的啟動腳本。 輸入 PowerShell 腳本的完整路徑。 指定的指令碼會在使用工作階段設定的新工作階段中執行。

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

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

Type:String
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ThreadApartmentState

指定要使用的執行緒模組 Apartment 狀態。 可接受的值如下:

  • Unknown
  • MTA
  • STA
Type:ApartmentState
Accepted values:STA, MTA, Unknown
Position:Named
Default value:None
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
Accept pipeline input:False
Accept wildcard characters:False
-TransportOption

指定會話組態的傳輸選項。 輸入傳輸選項物件,例如 Cmdlet 傳回的 New-PSTransportOptionWSManConfigurationOption物件。

使用工作階段設定之工作階段的選項,取決於工作階段選項和工作階段設定選項的值。 除非指定,否則在會話中設定的選項,例如使用 New-PSSessionOption Cmdlet,優先于會話組態中設定的選項。 不過,工作階段選項值不能超過工作階段設定中設定的最大值。

此參數是在 PowerShell 3.0 中引進。

Type:PSTransportOption
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-UseSharedProcess

只使用一個進程來裝載由相同使用者啟動的所有會話,並使用相同的會話組態。 根據預設,每個工作階段會裝載於自己的處理程序。

此參數是在 PowerShell 3.0 中引進。

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-WhatIf

顯示執行 Cmdlet 後會發生的情況。 Cmdlet 並不會執行。

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:False
Accept pipeline input:False
Accept wildcard characters:False

輸入

None

您無法使用管線傳送輸入至此 Cmdlet。

輸出

Microsoft.WSMan.Management.WSManConfigLeafElement

備註

此 Cmdlet 僅適用于 Windows 平臺。

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

Cmdlet Set-PSSessionConfiguration 不會變更組態名稱, 而且 WSMan 提供者不支援 Rename-Item Cmdlet。 若要變更會話組態的名稱,請使用 Unregister-PSSessionConfiguration Cmdlet 來刪除設定,然後使用 Register-PSSessionConfiguration Cmdlet 來建立和註冊新的會話組態。

您可以使用 Set-PSSessionConfiguration Cmdlet 來變更預設 Microsoft.PowerShellMicrosoft.PowerShell32 會話組態。 它們並不受保護。 若要還原為預設會話設定的原始版本,請使用 Unregister-PSSessionConfiguration Cmdlet 來刪除預設會話組態,然後使用 Enable-PSRemoting Cmdlet 來還原它。

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

您可以使用磁片磁碟機中的 WSMan: 命令來變更會話組態的屬性。 不過,您無法使用 WSMan: PowerShell 2.0 中的磁片磁碟機來變更 PowerShell 3.0 中引進的會話組態屬性,例如 OutputBufferingMode。 Windows PowerShell 2.0 命令不會產生錯誤,但它們沒有效果。 若要變更 PowerShell 3.0 中引進的屬性,請使用 WSMan: PowerShell 3.0 或更新版本中的磁片磁碟機。