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 参数将 ProcessIDTimeStamp 值添加到跟踪消息前缀。

示例 2:停止跟踪

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

此命令停止对 PowerShell 的 ParameterBinding 组件的跟踪。 它使用 Name 参数标识已被跟踪的组件,并使用 RemoveListener 参数标识跟踪侦听器。

参数

-Debugger

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

类型:SwitchParameter
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-FilePath

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

类型:String
别名:PSPath, Path
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-Force

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

类型:SwitchParameter
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符: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

指定被跟踪的组件。 请输入各个组件的跟踪源的名称。 允许使用通配符。

类型:String[]
Position: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

None 是默认值。

以下值是其他值的组合:

  • .- .

这些值定义为基于标志的枚举。 可以使用此参数将多个值组合在一起以设置多个标志。 可以将这些值以值数组或这些值的逗号分隔字符串形式传递给 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:1
默认值:None
必需:False
接受管道输入:True
接受通配符:False

-PassThru

返回一个代表你所处理的项目的对象。 默认情况下,此 cmdlet 将不产生任何输出。

类型:SwitchParameter
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-PSHost

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

类型:SwitchParameter
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-RemoveFileListener

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

类型:String[]
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

-RemoveListener

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

将以下值与 RemoveListener 结合使用:

  • 若要移除 PSHost(控制台),请键入 Host
  • 若要移除调试程序,请键入 Debug
  • 若要移除所有跟踪侦听器,请键入 *

若要移除文件跟踪侦听器,请使用 RemoveFileListener 参数。

类型:String[]
Position:Named
默认值:None
必需:False
接受管道输入:False
接受通配符:False

输入

String

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

输出

None

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

PSTraceSource

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

备注

  • 跟踪是开发人员用于调试和优化程序的一种方法。 在跟踪过程中,程序将生成有关其内部处理过程中每个步骤的详细消息。

    PowerShell 跟踪 cmdlet 专为帮助 PowerShell 开发人员而设计,但可供所有用户使用。 使用这些 cmdlet,你可以监视 PowerShell 功能的几乎每个方面。

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

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

  • 若要启动跟踪,请使用 Name 参数指定跟踪源,并使用 FilePath、Debugger 或 PSHost 参数指定侦听器(输出目标)。 使用 Options 参数确定要跟踪的事件类型,并使用 ListenerOptions 参数配置跟踪输出。

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

  • 若要停止跟踪,请使用 RemoveListener 参数。 若要停止使用文件侦听器的跟踪(使用 FilePath 参数启动的跟踪),请使用 RemoveFileListener 参数。 删除该侦听器后,跟踪将停止。

  • 若要确定可以跟踪哪些组件,请使用 Get-TraceSource。 每个模块的跟踪源在该组件处于使用状态时将自动加载,并且显示在 Get-TraceSource 的输出中。