閱讀英文

共用方式為

Trace-Command

  • 參考
模組:
Microsoft.PowerShell.Utility

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

語法

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

Description

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

範例

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

此範例會開始追蹤元數據處理、參數係結，以及建立和銷毀 Get-Process Notepad 表達式的 Cmdlet。

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

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

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

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

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

PowerShell 
$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。

PowerShell 
$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。

類型:Object[]
別名:Args
Position:Named
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

-Command

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

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

類型:String
Position:1
預設值:None
必要:True
接受管線輸入:False
接受萬用字元:False

-Debugger

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

類型:SwitchParameter
Position:Named
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

-Expression

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

類型:ScriptBlock
Position:1
預設值:None
必要:True
接受管線輸入:False
接受萬用字元:False

-FilePath

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

類型:String
別名:PSPath, Path
Position:Named
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

-Force

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

類型:SwitchParameter
Position:Named
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

-InputObject

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

類型:PSObject
Position:Named
預設值:None
必要:False
接受管線輸入:True
接受萬用字元:False

-ListenerOption

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

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

None 是預設值。

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

類型:TraceOptions
接受的值:None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack
Position:Named
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

-Name

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

類型:String[]
Position:0
預設值:None
必要:True
接受管線輸入:False
接受萬用字元: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、Finalizer、Method、Delegates、Events、Scope
  • Data：Constructor、Dispose、Finalizer、Property、Verbose、WriteLine
  • Errors：Error、Exception

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

類型:PSTraceSourceOptions
接受的值:None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, All
Position:2
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

-PSHost

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

類型:SwitchParameter
Position:Named
預設值:None
必要:False
接受管線輸入:False
接受萬用字元:False

輸入

PSObject

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

輸出

PSObject

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

備註

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

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

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

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