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 |
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 |
输入
可通过管道将包含名称的字符串传递给此 cmdlet。
输出
None
默认情况下,此 cmdlet 不返回任何输出。
使用 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
的输出中。