设置 TraceSource (Microsoft.PowerShell.Utility)

Set-TraceSource

配置、启动和停止 PowerShell 组件的跟踪。

句法

Set-TraceSource
   [-Name] <String[]>
   [[-Option] <PSTraceSourceOptions>]
   [-ListenerOption <TraceOptions>]
   [-FilePath <String>]
   [-Force]
   [-Debugger]
   [-PSHost]
   [-PassThru]
   [<CommonParameters>]

Set-TraceSource
   [-Name] <String[]>
   [-RemoveListener <String[]>]
   [<CommonParameters>]

Set-TraceSource
   [-Name] <String[]>
   [-RemoveFileListener <String[]>]
   [<CommonParameters>]

描述

Set-TraceSource cmdlet 配置、启动和停止 PowerShell 组件的跟踪。您可以使用它来指定将跟踪哪些组件以及将跟踪输出发送到何处。

示例

示例 1：跟踪 ParameterBinding 组件

Set-TraceSource -Name "ParameterBinding" -Option ExecutionFlow -PSHost -ListenerOption "ProcessId,TimeStamp"

此命令开始跟踪 PowerShell 的 ParameterBinding 组件。它使用 Name 参数指定跟踪源，使用 Option 参数选择 ExecutionFlow 跟踪事件，以及 PSHost 参数来选择 PowerShell 主机侦听器，它将输出发送到控制台。 ListenerOption 参数将 ProcessID 和 TimeStamp 值添加到跟踪消息前缀。

示例 2：停止跟踪

Set-TraceSource -Name "ParameterBinding" -RemoveListener "Host"

此命令停止对 PowerShell 的 ParameterBinding 组件的跟踪。它使用 Name 参数来标识正在跟踪的组件，并使用 RemoveListener 参数来标识跟踪侦听器。

参数

-Debugger

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

SwitchParameter

命名

None

False

False

False

-FilePath

指定此 cmdlet 将跟踪输出发送到的文件。此参数还选择文件跟踪侦听器。如果使用此参数启动跟踪，请使用 RemoveFileListener 参数停止跟踪。

String

PSPath, Path

命名

None

False

False

False

-Force

指示 cmdlet 覆盖只读文件。与FilePath 参数一起使用。

SwitchParameter

命名

None

False

False

False

-ListenerOption

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

None

LogicalOperationStack

DateTime

Timestamp

ProcessId

ThreadId

Callstack

无 是默认值。

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

TraceOptions

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

命名

None

False

False

False

-Name

指定跟踪哪些组件。输入每个组件的跟踪源名称。允许使用通配符。

String[]

0

None

True

True

True

-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、断言、全部

1

None

False

True

False

-PassThru

返回一个代表您正在使用的项目的对象。默认情况下，此 cmdlet 不生成任何输出。

SwitchParameter

命名

None

False

False

False

-PSHost

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

SwitchParameter

命名

None

False

False

False

-RemoveFileListener

通过删除与指定文件关联的文件跟踪侦听器来停止跟踪。输入跟踪输出文件的路径和文件名。

String[]

命名

None

False

False

False

-RemoveListener

通过删除跟踪侦听器来停止跟踪。

将以下值与 RemoveListener 结合使用：

• 要删除 PSHost（控制台），请键入 Host。
• 要删除调试器，请输入 Debug。
• 要删除所有跟踪侦听器，请键入 *。

要删除文件跟踪侦听器，请使用 RemoveFileListener 参数。

String[]

命名

None

False

False

False

输入

字符串

您可以通过管道将包含名称的字符串传递给此 cmdlet。

输出

无

默认情况下，此 cmdlet 不返回任何输出。

PSTrace来源

当您使用 PassThru 参数时，此 cmdlet 将返回表示跟踪会话的 PSTraceSource 对象。

笔记

• 跟踪是开发人员用来调试和完善程序的一种方法。跟踪时，程序会生成有关其内部处理中每个步骤的详细消息。

  PowerShell 跟踪 cmdlet 旨在帮助 PowerShell 开发人员，但所有用户都可以使用它们。它们使您可以监控 PowerShell 功能的几乎各个方面。

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

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

• 要启动跟踪，请使用名称参数指定跟踪源和FilePath、调试器或PSHost参数来指定侦听器（输出的目的地）。使用 Options 参数确定跟踪的事件类型，并使用 ListenerOption 参数配置跟踪输出。

• 要更改跟踪的配置，请输入 Set-TraceSource 命令，就像启动跟踪一样。 PowerShell 识别出跟踪源已被跟踪。它停止跟踪，添加新配置，然后启动或重新启动跟踪。

• 要停止跟踪，请使用 RemoveListener 参数。要停止使用文件侦听器的跟踪（使用 FilePath 参数启动的跟踪），请使用 RemoveFileListener 参数。当您删除侦听器时，跟踪将停止。

• 要确定可以跟踪哪些组件，请使用 Get-TraceSource。当组件使用时，每个模块的跟踪源都会自动加载，并且它们出现在 Get-TraceSource 的输出中。