Trace-Command (Microsoft.PowerShell.Utility)

Trace-Command

配置并启动指定表达式或命令的跟踪。

句法

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>]

描述

Trace-Command cmdlet 配置并启动指定表达式或命令的跟踪。它的工作方式类似于 Set-TraceSource，不同之处在于它仅适用于指定的命令。

示例

示例 1：跟踪元数据处理、参数绑定和表达式

此示例开始跟踪 Get-Process Notepad 表达式的元数据处理、参数绑定以及 cmdlet 创建和销毁。

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

它使用 Name 参数指定跟踪源，使用 Expression 参数指定命令，使用 PSHost 参数将输出发送到安慰。由于它没有指定任何跟踪选项或侦听器选项，因此该命令使用默认值：

• 全部用于跟踪选项
• 没有监听器选项

示例 2：跟踪 ParameterBinding 操作的动作

此示例跟踪 PowerShell 处理从管道获取输入的 Get-Alias 表达式时的 ParameterBinding 操作的操作。

$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" 或 "$A |获取别名。

示例 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。

Object[]

Args

命名

None

False

False

False

-Command

指定跟踪期间正在处理的命令。

使用此参数时，PowerShell 会像在管道中处理命令一样处理该命令。例如，不会对每个传入对象重复命令发现。

String

1

None

True

False

False

-Debugger

指示 cmdlet 将跟踪输出发送到调试器。您可以在任何用户模式或内核模式调试器或 Visual Studio 中查看输出。此参数还选择默认跟踪侦听器。

SwitchParameter

命名

None

False

False

False

-Expression

指定跟踪期间正在处理的表达式。将表达式括在大括号 ({}) 中。

ScriptBlock

1

None

True

False

False

-FilePath

指定 cmdlet 将跟踪输出发送到的文件。此参数还选择文件跟踪侦听器。

String

PSPath, Path

命名

None

False

False

False

-Force

强制运行命令而不要求用户确认。与FilePath 参数一起使用。即使使用 Force 参数，cmdlet 也无法覆盖安全限制。

SwitchParameter

命名

None

False

False

False

-InputObject

指定跟踪期间正在处理的表达式的输入。您可以输入一个代表表达式接受的输入的变量，或者通过管道传递一个对象。

PS对象

命名

None

False

True

False

-ListenerOption

将可选数据指定为输出中每条跟踪消息的前缀。该参数可接受的值为：

None

LogicalOperationStack

DateTime

Timestamp

ProcessId

ThreadId

Callstack

无 是默认值。

这些值被定义为基于标志的枚举。您可以使用此参数将多个值组合在一起以设置多个标志。这些值可以作为值数组或这些值的逗号分隔字符串传递给 ListenerOption 参数。该 cmdlet 将使用二进制 OR 运算组合这些值。将值作为数组传递是最简单的选项，并且还允许您对值使用制表符补全。

TraceOptions

无、LogicalOperationStack、日期时间、时间戳、进程 ID、线程 ID、调用堆栈

命名

None

False

False

False

-Name

指定跟踪的 PowerShell 组件的数组。输入每个组件的跟踪源名称。允许使用通配符。要查找计算机上的跟踪源，请输入 Get-TraceSource。

String[]

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

全部 是默认值。

以下值是其他值的组合：

• ExecutionFlow：构造函数、Dispose、终结器、方法、委托, 事件, 范围
• 数据：构造函数、Dispose、终结器、属性、详细, WriteLine
• 错误：错误，异常

这些值被定义为基于标志的枚举。您可以使用此参数将多个值组合在一起以设置多个标志。这些值可以作为值数组或这些值的逗号分隔字符串传递给 Option 参数。该 cmdlet 将使用二进制 OR 运算组合这些值。将值作为数组传递是最简单的选项，并且还允许您对值使用制表符补全。

PSTrace源选项

无、构造函数、Dispose、终结器、方法、属性、委托、事件、异常、锁定、错误、错误、警告、详细、WriteLine、数据、范围、ExecutionFlow、断言、全部

2

None

False

False

False

-PSHost

指示 cmdlet 将跟踪输出发送到 PowerShell 主机。此参数还选择 PSHost 跟踪侦听器。

SwitchParameter

命名

None

False

False

False

输入

PSObject

您可以通过管道将表示表达式输入的对象传递给此 cmdlet。

输出

PSObject

此 cmdlet 不返回其自身的输出。跟踪的命令可能会返回输出。此 cmdlet 将命令跟踪写入调试流。

笔记

跟踪是开发人员用来调试和完善程序的一种方法。跟踪时，程序会生成有关其内部处理中每个步骤的详细消息。 PowerShell 跟踪 cmdlet 旨在帮助 PowerShell 开发人员，但它们可供所有用户使用。它们使您可以监控 shell 功能的几乎每个方面。

跟踪源是每个 PowerShell 组件的一部分，用于管理跟踪并为组件生成跟踪消息。要跟踪组件，您需要识别其跟踪源。

使用 Get-TraceSource 查看启用跟踪的 PowerShell 组件列表。

跟踪侦听器接收跟踪的输出并将其显示给用户。您可以选择将跟踪数据发送到用户模式或内核模式调试器、主机或控制台、文件或从 System.Diagnostics.TraceListener 类派生的自定义侦听器。