Trace-Command

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

The Trace-Command cmdlet configures and starts a trace of the specified expression or command. It works like Set-TraceSource, except that it applies only to the specified command.

Examples

Example 1: Trace metadata processing, parameter binding, and an expression

This example starts a trace of metadata processing, parameter binding, and cmdlet creation and destruction of the Get-Process Notepad expression.

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

It uses the Name parameter to specify the trace sources, the Expression parameter to specify the command, and the PSHost parameter to send the output to the console. Because it doesn't specify any tracing options or listener options, the command uses the defaults:

• All for the tracing options
• None for the listener options

Example 2: Trace the actions of ParameterBinding operations

This example traces the actions of the ParameterBinding operations of PowerShell while it processes a Get-Alias expression that takes input from the pipeline.

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

In Trace-Command, the InputObject parameter passes an object to the expression that's being processed during the trace.

The first command stores the string i* in the $A variable. The second command uses the Trace-Command cmdlet with the ParameterBinding trace source. The PSHost parameter sends the output to the console.

The expression being processed is Get-Alias $Input, where the $Input variable is associated with the InputObject parameter. The InputObject parameter passes the variable $A to the expression. In effect, the command being processed during the trace is Get-Alias -InputObject $A" or "$A | Get-Alias.

Example 3: Trace ParameterBinding operations for native commands

PowerShell 7.3 added the ability to trace parameter binding for native commands. The following example shows how PowerShell parses the command-line arguments for the native command 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

Parameters

-ArgumentList

-Command

-Debugger

-Expression

-FilePath

-Force

-InputObject

-ListenerOption

-Name

-Option

-PSHost

Inputs

PSObject

You can pipe objects that represent input to the expression to this cmdlet.

Outputs

PSObject

This cmdlet returns no output of its own. The traced command may return output. This cmdlet writes the command trace to the debug stream.

Notes

Tracing is a method that developers use to debug and refine programs. When tracing, the program generates detailed messages about each step in its internal processing. The PowerShell tracing cmdlets are designed to help PowerShell developers, but they're available to all users. They let you monitor nearly every aspect of the functionality of the shell.

A trace source is the part of each PowerShell component that manages tracing and generates trace messages for the component. To trace a component, you identify its trace source.

Use Get-TraceSource to see a list of PowerShell components that are enabled for tracing.

A trace listener receives the output of the trace and displays it to the user. You can elect to send the trace data to a user-mode or kernel-mode debugger, to the host or console, to a file, or to a custom listener derived from the System.Diagnostics.TraceListener class.

Related Links

• Get-TraceSource
• Measure-Command
• Set-TraceSource