Trace-Command

参考

模块:: Microsoft.PowerShell.Utility

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

语法

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 参数将输出发送到控制台。因为它未指定任何跟踪选项或侦听器选项，所以此命令将使用默认值：

对于跟踪选项为 All
对于侦听器选项为 None

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

类型:	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 将使用二进制或运算合并这些值。将值作为数组传递是最简单的选项，此选项还支持对值使用 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 是默认值。

以下值是其他值的组合：

.- .

这些值定义为基于标志的枚举。可以使用此参数将多个值组合在一起以设置多个标志。可以将这些值以值数组或这些值的逗号分隔字符串形式传递给 Option 参数。该 cmdlet 将使用二进制或运算合并这些值。将值作为数组传递是最简单的选项，此选项还支持对值使用 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 开发人员而设计，但可供所有用户使用。使用这些 cmdlet，你可以监视 shell 功能的几乎每个方面。

跟踪源是每个 PowerShell 组件的一部分，负责为该组件管理跟踪并生成跟踪消息。若要跟踪某个组件，你应标识其跟踪源。

可以使用 Get-TraceSource 查看已启用跟踪功能的 PowerShell 组件的列表。

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

通过