Set-TraceSource
設定、啟動和停止追蹤 Windows PowerShell 元件。
語法
Set-TraceSource [[-Option] {<None> | <Constructor> | <Dispose> | <Finalizer> | <Method> | <Property> | <Delegates> | <Events> | <Exception> | <Lock> | <Error> | <Errors> | <Warning> | <Verbose> | <WriteLine> | <Data> | <Scope> | <ExecutionFlow> | <Assert> | <All>}] [-Debugger] [-FilePath <string>] [-Force] [-ListenerOption {<None> | <LogicalOperationStack> | <DateTime> | <Timestamp> | <ProcessId> | <ThreadId> | <Callstack>}] [-PassThru] [-PSHost] [-Name] <string[]> [<CommonParameters>]
Set-TraceSource [-RemoveListener <string[]>] [-Name] <string[]> [<CommonParameters>]
Set-TraceSource [-RemoveFileListener <string[]>] [-Name] <string[]> [<CommonParameters>]
描述
Set-TraceSource Cmdlet 會設定、啟動和停止追蹤 Windows PowerShell 元件。您可以使用它來指定所要追蹤的元件以及傳送追蹤輸出的目的地。
參數
-Debugger
將追蹤輸出傳送至偵錯工具。您可以使用任何使用者模式或核心模式偵錯工具來檢視輸出，或在 Microsoft Visual Studio 中檢視輸出。此參數也會選取預設的追蹤接聽程式。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-FilePath <string>
將追蹤輸出傳送到指定的檔案。此參數也會選取檔案追蹤接聽程式。若您使用此參數啟動追蹤，請使用 RemoveFileListener 參數停止追蹤。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-Force
允許此 Cmdlet 覆寫唯讀的檔案。請搭配 FilePath 參數使用。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-ListenerOption <TraceOptions>
在輸出中的每個追蹤訊息開頭加入選用性資料。有效的值包括 "None"、"LogicalOperationStack"、"DateTime"、"Timestamp"、"ProcessId"、"ThreadId" 和 "Callstack"。預設值為 "None"。
若要指定多重選項，請用逗號分隔選項，但不能包含空格，然後置於引號內，例如 "ProcessID,ThreadID"。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-Name <string[]>
決定所要追蹤的元件。輸入每個元件的追蹤來源的名稱。允許使用萬用字元。
必要? |
true |
位置? |
1 |
預設值 |
|
接受管線輸入? |
true (ByValue, ByPropertyName) |
接受萬用字元? |
false |
-Option <PSTraceSourceOptions>
決定所要追蹤的事件類型。
有效的值包括："None"、"Constructor"、"Dispose"、"Finalizer"、"Method"、"Property"、"Delegates"、"Events"、"Exception"、"Lock"、"Error"、"Errors"、"Warning"、"Verbose"、"WriteLine"、"Data"、"Scope"、"ExecutionFlow"、"Assert" 和 "All"。預設值為 "All"。
下列值是其他值的組合：
-- ExecutionFlow：(Constructor、Dispose、Finalizer、Method、Delegates、Events 和 Scope)
-- Data：(Constructor、Dispose、Finalizer、Property、Verbose 和 WriteLine)
-- Errors：(Error 和 Exception)。
若要指定多重選項，請用逗號分隔選項，但不能包含空格，然後置於引號內，例如 "Constructor,Dispose"。
必要? |
false |
位置? |
2 |
預設值 |
|
接受管線輸入? |
true (ByPropertyName) |
接受萬用字元? |
false |
-PassThru
傳回代表追蹤工作階段的物件。根據預設，此 Cmdlet 不會產生任何輸出。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-PSHost
將追蹤輸出傳送至 Windows PowerShell 主機。此參數也會選取 PSHost 追蹤接聽程式。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-RemoveFileListener <string[]>
移除與指定檔案相關聯的檔案追蹤接聽程式，藉以停止追蹤。輸入追蹤輸出檔的路徑和檔名。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
-RemoveListener <string[]>
移除追蹤接聽程式藉以停止追蹤。
可用的 RemoveListener 值如下：
-- 若要移除 PSHost (主控台)，請輸入 "Host"。
-- 若要移除偵錯工具，請輸入 "Debug"。
-- 若要移除所有的追蹤接聽程式，請輸入 "*"。
若要移除檔案追蹤接聽程式，請使用 RemoveFileListener 參數。
必要? |
false |
位置? |
named |
預設值 |
|
接受管線輸入? |
false |
接受萬用字元? |
false |
<CommonParameters>
這個 Cmdlet 支援一般參數：-Verbose、-Debug、-ErrorAction、-ErrorVariable、-OutBuffer 和 -OutVariable。如需詳細資訊，請參閱 about_Commonparameters.
輸入和輸出
輸入型別是可經由管道輸出至 Cmdlet 的物件型別。傳回型別則是 Cmdlet 所傳回的物件型別。
輸入 |
System.String 您可經由管道將包含名稱的字串輸出至 Set-TraceSource。 |
輸出 |
無或 System.Management.Automation.PSTraceSource 當您使用 PassThru 參數時，Set-TraceSource 會產生代表追蹤工作階段的 System.Management.Automation.PSTraceSource 物件。否則，這個 Cmdlet 不會產生任何輸出。 |
附註
追蹤是開發人員用來偵錯和調整程式的一種方法。進行追蹤時，程式會產生詳細訊息列出每個內部處理步驟的相關資訊。
Windows PowerShell 追蹤 cmdlet 是專為輔助 Windows PowerShell 開發人員而設計，但所有的使用者皆可使用。這些 Cmdlet 幾乎可以監視 Windows PowerShell 每個層面的功能。
「追蹤來源」是每個 Windows PowerShell 元件的一部分，負責管理追蹤並產生元件的追蹤訊息。若要追蹤元件，您必須識別元件的追蹤來源。
「追蹤接聽程式」則接收追蹤的輸出，並顯示輸出供使用者檢視。您可以選擇將追蹤資料傳送到使用者模式或核心模式偵錯工具、主控台、檔案，或者傳送到衍生自 System.Diagnostics.TraceListener 類別的自訂接聽程式。
若要啟動追蹤，請使用 Name 參數指定追蹤來源 (要追蹤的元件)，並使用 FilePath、Debugger 或 PSHost 參數指定接聽程式 (輸出的目的地)。使用 Options 參數決定要追蹤的事件類型，並使用 ListenerOptions 參數設定追蹤輸出。
若要變更追蹤的組態，請輸入 Set-TraceSource 命令，如同啟動追蹤時所做的。Windows PowerShell 察覺追蹤來源已經在追蹤當中，便會停止追蹤、加入新組態，然後啟動或重新啟動追蹤。
若要停止追蹤，請使用 RemoveListener 參數。若要將使用檔案接聽程式 (使用 -FilePath 參數啟動的追蹤) 的追蹤停止，請使用 RemoveFileListener 參數。當您移除接聽程式時，追蹤就會停止。
若要判斷可以追蹤哪些元件，請使用 Get-TraceSource。每個模組的追蹤來源會在元件處於使用中狀態時自動載入，並且會在 Get-TraceSource 的輸出中出現。
範例 1
C:\PS>Set-TraceSource -Name Parameterbinding -Option ExecutionFlow -PSHost '
-ListenerOption "ProcessID,TimeStamp"
描述
-----------
這個命令會為 Windows PowerShell 的 ParameterBinding 元件啟動追蹤。它使用 Name 參數指定追蹤來源；使用 Options 參數選取 ExecutionFlow 追蹤事件；並使用 PSHost 參數選取 Windows PowerShell 主機接聽程式，以將輸出傳送到主控台。ListenerOption 參數會在追蹤訊息開頭加入 "ProcessID" 和 "TimeStamp" 值。
範例 2
C:\PS>set-tracesource -name ParameterBinding -RemoveListener Host
描述
-----------
這個命令會停止追蹤 Windows PowerShell 的 ParameterBinding 元件。它使用 Name 參數識別正在追蹤的元件，並使用 RemoveListener 參數識別追蹤接聽程式。