Trace-Command

  • 參考
模組:
Microsoft.PowerShell.Utility

設定並啟動指定之表示式或命令的追蹤。

Syntax

Trace-Command
     [-InputObject <PSObject>]
     [-Name] <String[]>
     [[-Option] <PSTraceSourceOptions>]
     [-Expression] <ScriptBlock>
     [-ListenerOption <TraceOptions>]
     [-FilePath <String>]
     [-Force]
     [-Debugger]
     [-PSHost]
     [<CommonParameters>]
Trace-Command
     [-InputObject <PSObject>]
     [-Name] <String[]>
     [[-Option] <PSTraceSourceOptions>]
     [-Command] <String>
     [-ArgumentList <Object[]>]
     [-ListenerOption <TraceOptions>]
     [-FilePath <String>]
     [-Force]
     [-Debugger]
     [-PSHost]
     [<CommonParameters>]

Description

Cmdlet 會 Trace-Command 設定並啟動指定之表達式或命令的追蹤。 它的運作方式就像 Set-TraceSource，不同之處在於它只適用於指定的命令。

範例

範例 1：追蹤元數據處理、參數系結和表達式

此範例會啟動元數據處理、參數係結和 Cmdlet 建立和解構表達式的 Get-Process Notepad 追蹤。

Trace-Command -Name metadata,parameterbinding,cmdlet -Expression {Get-Process Notepad} -PSHost

它會使用 Name 參數來指定追蹤來源、 指定命令的 Expression 參數，以及 將輸出傳送至主控台的 PSHost 參數。 因為它未指定任何追蹤選項或接聽程式選項，所以命令會使用預設值：

  • 全部用於追蹤選項
  • 接聽程式選項無

範例 2：追蹤 ParameterBinding 作業的動作

此範例會追蹤PowerShell ParameterBinding作業的動作，同時處理Get-Alias從管線取得輸入的表達式。

$A = "i*"
Trace-Command ParameterBinding {Get-Alias $Input} -PSHost -InputObject $A

在 Trace-Command中 ，InputObject 參數會將對象傳遞至追蹤期間正在處理的表達式。

第一個命令會將字串 i* 儲存在變數中 $A 。 第二個命令會 Trace-Command 使用 Cmdlet 搭配 ParameterBinding 追蹤來源。 PSHost 參數會將輸出傳送至控制台。

正在處理的表達式是 Get-Alias $Input，其中 $Input 變數與 InputObject 參數相關聯。 InputObject 參數會將變數$A傳遞至表達式。 實際上，追蹤期間正在處理的命令為 Get-Alias -InputObject $A" or "$A | Get-Alias。

範例 3：原生命令的追蹤 ParameterBinding 作業

PowerShell 7.3 新增了追蹤原生命令參數係結的功能。 下列範例示範 PowerShell 如何剖析原生命令 TestExe的命令行自變數。

$a = 'a" "b'
Trace-Command -PSHOST -Name ParameterBinding { TestExe -echoargs $a 'c" "d' e" "f }

DEBUG: 2023-02-27 14:20:45.3975 ParameterBinding Information: 0 : BIND NAMED native application line args [C:\Public\Toolbox\TestExe\testexe.exe]
DEBUG: 2023-02-27 14:20:45.3978 ParameterBinding Information: 0 :     BIND cmd line arg [-echoargs] to position [0]
DEBUG: 2023-02-27 14:20:45.3979 ParameterBinding Information: 0 :     BIND cmd line arg [a" "b] to position [1]
DEBUG: 2023-02-27 14:20:45.3980 ParameterBinding Information: 0 :     BIND cmd line arg [c" "d] to position [2]
DEBUG: 2023-02-27 14:20:45.3982 ParameterBinding Information: 0 :     BIND cmd line arg [e f] to position [3]
DEBUG: 2023-02-27 14:20:47.6092 ParameterBinding Information: 0 : CALLING BeginProcessing

參數

-ArgumentList

指定要追蹤之命令的參數和參數值。 ArgumentList 的別名是 Args。 這項功能適用於偵錯動態參數。

如需 ArgumentList 行為的詳細資訊，請參閱about_Splatting。

Type:Object[]
Aliases:Args
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Command

指定追蹤期間正在處理的命令。

當您使用此參數時，PowerShell 會處理命令，就像在管線中處理一樣。 例如，不會針對每個傳入物件重複命令探索。

Type:String
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Debugger

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

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

-Expression

指定追蹤期間正在處理的表達式。 以大括弧 （{}） 括住表達式。

Type:ScriptBlock
Position:1
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-FilePath

指定 Cmdlet 傳送追蹤輸出的檔案。 此參數也會選取檔案追蹤接聽程式。

Type:String
Aliases:PSPath, Path
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

強制命令執行，而不要求使用者確認。 與 FilePath 參數搭配使用。 即使使用 Force 參數，Cmdlet 也無法覆寫安全性限制。

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

-InputObject

指定追蹤期間正在處理的運算式輸入。 您可以輸入代表表達式所接受之輸入的變數，或透過管線傳遞物件。

Type:PSObject
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-ListenerOption

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

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

None 是預設值。

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

Type:TraceOptions
Accepted values:None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

指定追蹤的 PowerShell 元件數組。 輸入每個元件的追蹤來源名稱。 允許通配符。 若您在您的電腦上尋找追蹤來源， 請輸入 Get-TraceSource。

Type:String[]
Position:0
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Option

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

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

All 是預設值。

下列值是其他值的組合：

  • ExecutionFlow：Constructor、Dispose、、MethodFinalizer、Delegates、、、 EventsScope
  • Data：Constructor、、Dispose、PropertyFinalizer、、Verbose、WriteLine
  • Errors： Error、 Exception

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

Type:PSTraceSourceOptions
Accepted values:None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, All
Position:2
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PSHost

指出 Cmdlet 會將追蹤輸出傳送至 PowerShell 主機。 此參數也會選取 PSHost 追蹤接聽程式。

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

輸入

PSObject

您可以使用管線將代表表達式輸入的物件傳送至這個 Cmdlet。

輸出

PSObject

此 Cmdlet 不會傳回自己的輸出。 追蹤的命令可能會傳回輸出。 此 Cmdlet 會將命令追蹤寫入偵錯數據流。

備註

追蹤是開發人員用來偵錯和精簡程式的方法。 追蹤時，程式會產生其內部處理中每個步驟的詳細訊息。 PowerShell 追蹤 Cmdlet 的設計目的是協助 PowerShell 開發人員，但可供所有使用者使用。 它們可讓您監視殼層功能的幾乎所有層面。

追蹤來源是管理追蹤併產生元件追蹤訊息之每個 PowerShell 元件的一部分。 若要追蹤元件，您可以識別其追蹤來源。

用來 Get-TraceSource 查看已啟用追蹤的PowerShell元件清單。

追蹤接聽程式會接收追蹤的輸出，並將它顯示給使用者。 您可以選擇將追蹤數據傳送至使用者模式或內核模式調試程式、主機或控制台、檔案，或傳送至衍生自 System.Diagnostics.TraceListener 類別的 自定義接聽程式 。