Set-TraceSource

模組:

Microsoft.PowerShell.Utility Module

設定、啟動並停止 PowerShell 元件的痕跡。

語法

optionsSet (預設值)

Set-TraceSource
    [-Name] <String[]>
    [[-Option] <PSTraceSourceOptions>]
    [-ListenerOption <TraceOptions>]
    [-FilePath <String>]
    [-Force]
    [-Debugger]
    [-PSHost]
    [-PassThru]
    [<CommonParameters>]

removeAllListenersSet

Set-TraceSource
    [-Name] <String[]>
    [-RemoveListener <String[]>]
    [<CommonParameters>]

removeFileListenersSet

Set-TraceSource
    [-Name] <String[]>
    [-RemoveFileListener <String[]>]
    [<CommonParameters>]

Description

這個 Set-TraceSource cmdlet 會設定、啟動並停止 PowerShell 元件的一段痕跡。 你可以用它來指定要追蹤哪些元件，以及追蹤輸出會送到哪裡。

範例

範例 1：追蹤 ParameterBinding 元件

Set-TraceSource -Name "ParameterBinding" -Option ExecutionFlow -PSHost -ListenerOption "ProcessId,TimeStamp"

此指令開始追蹤 PowerShell 的 ParameterBinding 元件。 它使用 Name 參數指定追蹤來源， Option 參數選擇 ExecutionFlow 追蹤事件， PSHost 參數選擇 PowerShell 主機監聽器，後者將輸出傳送至主控台。 ListenerOption 參數會在追蹤訊息前綴中加入 和 ProcessIdTimeStamp 值。

範例二：停止追蹤

Set-TraceSource -Name "ParameterBinding" -RemoveListener "Host"

此指令會停止 PowerShell 中 ParameterBinding 元件的追蹤。 它使用 Name 參數來識別正在追蹤的元件，並使用 RemoveListener 參數來識別追蹤監聽器。

參數

-Debugger

表示指令本會將追蹤輸出傳送到除錯器。 你可以在任何使用者模式或核心模式的除錯器中查看輸出，或在 Microsoft Visual Studio 中。 此參數同時選擇預設的追蹤監聽器。

參數屬性

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

參數集

optionsSet

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

-FilePath

指定一個檔案，該指令小程式將追蹤輸出傳送到那裡。 此參數同時選擇檔案追蹤監聽器。 如果你用這個參數開始追蹤，請用 RemoveFileListen 參數停止追蹤。

參數屬性

類型:	String
預設值:	None
支援萬用字元:	False
不要顯示:	False
別名:	PSPath, 路徑

參數集

optionsSet

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

-Force

表示該指令本會覆寫唯讀檔案。 搭配 FilePath 參數使用。

參數屬性

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

參數集

optionsSet

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

-ListenerOption

指定輸出中每個追蹤訊息前綴的可選資料。 此參數可接受的值為：

• None
• LogicalOperationStack
• DateTime
• Timestamp
• ProcessId
• ThreadId
• Callstack

None 是預設值。

這些值會定義為旗標型列舉。 您可以將多個值結合在一起，以使用此參數來設定多個旗標。 這些值可以以數值陣列的形式傳遞到 ListenerOption 參數，或以逗號分隔的字串形式傳遞給 ListenerOption 參數。 Cmdlet 會使用二進位 OR 作業來合併值。 將值以陣列的形式傳遞是最簡單的選擇，還可以讓您在使用 Tab 鍵時自動完成值。

參數屬性

類型:	TraceOptions
預設值:	None
接受的值:	None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack
支援萬用字元:	False
不要顯示:	False

參數集

optionsSet

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

-Name

指定追蹤哪些元件。 輸入每個元件的追蹤來源名稱。 允許使用通配符。

參數屬性

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

參數集

(All)

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

-Option

指定追蹤的事件類型。 此參數可接受的值為：

• None
• Constructor
• Dispose
• Finalizer
• Method
• Property
• Delegates
• Events
• Exception
• Lock
• Error
• Errors
• Warning
• Verbose
• WriteLine
• Data
• Scope
• ExecutionFlow
• Assert
• All

None 是預設值。

以下數值為其他數值的組合：

• ExecutionFlow： Constructor， ， Dispose， MethodDelegatesEventsFinalizerScope
• Data：Constructor， Dispose， ， FinalizerProperty， Verbose， ，WriteLine
• Errors： Error、 Exception

這些值會定義為旗標型列舉。 您可以將多個值結合在一起，以使用此參數來設定多個旗標。 這些值可以以數值陣列的形式傳遞給 Option 參數，或以逗號分隔的數值串形式傳遞。 Cmdlet 會使用二進位 OR 作業來合併值。 將值以陣列的形式傳遞是最簡單的選擇，還可以讓您在使用 Tab 鍵時自動完成值。

參數屬性

類型:	PSTraceSourceOptions
預設值:	None
接受的值:	None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, All
支援萬用字元:	False
不要顯示:	False

參數集

optionsSet

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

-PassThru

返回一個物件，代表您正在處理的項目。 根據預設，此 Cmdlet 不會產生任何輸出。

參數屬性

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

參數集

optionsSet

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

-PSHost

表示此指令檔會將追蹤輸出傳送至 PowerShell 主機。 此參數同時選擇 PSHost 追蹤監聽器。

參數屬性

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

參數集

optionsSet

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

-RemoveFileListener

透過移除與指定檔案相關的檔案追蹤監聽器來停止追蹤。 輸入追蹤輸出檔案的路徑與檔名。

參數屬性

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

參數集

removeFileListenersSet

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

-RemoveListener

移除追蹤監聽器來停止追蹤。

使用 RemoveListener 使用以下數值：

• 要移除 PSHost（主控台），請輸入 Host。
• 要移除除錯器，請輸入 Debug.
• 要移除所有追蹤監聽器，請輸入 *。

要移除檔案追蹤監聽器，請使用 RemoveFileListener 參數。

參數屬性

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

參數集

removeAllListenersSet

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

CommonParameters

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

輸入

String

你可以將包含名稱的字串輸入這個 cmdlet。

輸出

None

根據預設，此 Cmdlet 不會傳回任何輸出。

PSTraceSource

當你使用 PassThru 參數時，這個 cmdlet 會回傳一個代表追蹤會話的 PSTraceSource 物件。

備註

• 追蹤是一種開發者用來除錯和優化程式的方法。 在追蹤時，程式會針對內部處理的每個步驟產生詳細訊息。

  PowerShell 追蹤 cmdlet 是為了幫助 PowerShell 開發者而設計，但它們對所有使用者開放。 它們讓你幾乎能監控 PowerShell 功能的每一個面向。

  追蹤來源是每個 PowerShell 元件中負責追蹤並產生該元件追蹤訊息的部分。 要追蹤一個元件，你必須找出它的追蹤來源。

  追蹤監聽器接收追蹤的輸出，並顯示給使用者。 你可以選擇將追蹤資料傳送到使用者模式或核心模式除錯器、主控台、檔案，或是從 System.Diagnostics.TraceListener 類別衍生的自訂監聽器。

• 要啟動追蹤，使用 名稱 參數指定追蹤來源，並使用 檔案路徑、 除錯器或 PSHost 參數指定監聽器（輸出的目的地）。 使用 Options 參數來決定追蹤的事件類型，並使用 ListenerOption 參數來設定追蹤輸出。

• 要更改追蹤的設定，請輸入 Set-TraceSource 指令，就像開始追蹤一樣。 PowerShell 能辨識追蹤來源已經被追蹤。 它會停止追蹤，新增設定，然後開始或重啟追蹤。

• 要停止追蹤，請使用 RemoveListen 參數。 要停止使用檔案監聽器（由 FilePath 參數開始的追蹤），請使用 RemoveFileListener 參數。 當你移除竊聽器時，追蹤就會停止。

• 要判斷哪些元件可以被追蹤，請使用 Get-TraceSource。 每個模組的追蹤源會在元件使用時自動載入，並會出現在 的輸出 Get-TraceSource中。

相關連結

• Get-TraceSource
• Trace-Command