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 參數會將 ProcessId 和 TimeStamp 值新增至追蹤訊息前置詞。

範例 2：停止追蹤

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

此命令會停止PowerShell ParameterBinding 元件的追蹤。 它會使用 Name 參數來識別所追蹤的元件，以及 RemoveListener 參數來識別追蹤接聽程式。

參數

-Debugger

指出 Cmdlet 會將追蹤輸出傳送至調試程式。 您可以在任何使用者模式或核心模式調試程式中，或在 Visual Studio Microsoft檢視輸出。 此參數也會選取預設追蹤接聽程式。

參數屬性

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

參數集

optionsSet

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

-FilePath

指定這個 Cmdlet 傳送追蹤輸出的檔案。 此參數也會選取檔案追蹤接聽程式。 如果您使用此參數啟動追蹤，請使用 RemoveFileListener 參數來停止追蹤。

參數屬性

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

參數集

optionsSet

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

-Force

指出 Cmdlet 會覆寫唯讀檔案。 搭配 FilePath 參數使用。

參數屬性

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

參數集

optionsSet

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

-ListenerOption

指定輸出中每個追蹤訊息前置詞的選擇性數據。 此參數可接受的值為：

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

None 是預設值。

這些值會定義為旗標型列舉。 您可以將多個值結合在一起，以使用此參數來設定多個旗標。 這些值可以傳遞至 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、Finalizer、Method、Delegates、Events、Scope
• Data：Constructor、Dispose、Finalizer、Property、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

指出此 Cmdlet 會將追蹤輸出傳送至 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 類別的自定義接聽程式。

• 若要啟動追蹤，請使用 Name 參數來指定追蹤來源和 FilePath、Debugger或 PSHost 參數來指定接聽程式 （輸出的目的地）。 使用 Options 參數來判斷追蹤的事件類型和 ListenerOption 參數，以設定追蹤輸出。

• 若要變更追蹤的組態，請輸入 Set-TraceSource 命令，就像開始追蹤一樣。 PowerShell 會辨識追蹤來源已經追蹤。 它會停止追蹤、新增組態，然後啟動或重新啟動追蹤。

• 若要停止追蹤，請使用 RemoveListener 參數。 若要停止使用檔案接聽程式的追蹤（使用 FilePath 參數啟動的追蹤），請使用 removeFileListener 參數 。 當您移除接聽程式時，追蹤會停止。

• 若要判斷哪些元件可以追蹤，請使用 Get-TraceSource。 當元件正在使用時，每個模組的追蹤來源都會自動載入，而且它們會出現在 Get-TraceSource的輸出中。

相關連結

• Get-TraceSource
• Trace-Command