Share via

Set-TraceSource

  • 参考
模块:
Microsoft.PowerShell.Utility

配置、启动和停止 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>]

说明

cmdlet Set-TraceSource 配置、启动和停止 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 中查看输出。 此参数还将选择默认的跟踪侦听器。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-FilePath

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

Type:String
Aliases:PSPath, Path
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ListenerOption

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

  • None
  • LogicalOperationStack
  • DateTime
  • Timestamp
  • ProcessId
  • ThreadId
  • Callstack

None 是默认值。

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

Type:TraceOptions
Accepted values:None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, Callstack
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

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

Type:String[]
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:True

-Option

指定要跟踪的事件类型。 此参数的可接受值为：

  • None
  • Constructor
  • Dispose
  • Finalizer
  • Method
  • Property
  • Delegates
  • Events
  • Exception
  • Lock
  • Error
  • Errors
  • Warning
  • Verbose
  • WriteLine
  • Data
  • Scope
  • ExecutionFlow
  • Assert
  • All

All 是默认值。

以下值是其他值的组合：

  • ExecutionFlow: Constructor, Dispose, Finalizer, Method, Delegates, Events, Scope
  • Data: Constructor, Dispose, Finalizer, Property, Verbose, WriteLine
  • Errors: Error, Exception

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

Type:PSTraceSourceOptions
Accepted values:None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, All
Position:1
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-PassThru

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PSHost

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

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RemoveFileListener

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

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RemoveListener

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

对 RemoveListener 使用以下值：

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

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

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

输入

String

可以通过管道将包含名称的字符串传递给 Set-TraceSource。

输出

None or System.Management.Automation.PSTraceSource

使用 PassThru 参数时， Set-TraceSource 会生成表示跟踪会话的 System.Management.Automation.PSTraceSource 对象。 否则，此 cmdlet 将不生成任何输出。

备注

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

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

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

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

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

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

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

  • 若要确定可以跟踪哪些组件，请使用 Get-TraceSource。 使用组件时，将自动加载每个模块的跟踪源，它们将显示在 的 Get-TraceSource输出中。