Set-TraceSource

 

SYNOPSIS

Configures, starts, and stops a trace of Windows PowerShell components.

 

SYNTAX

Set-TraceSource [-name] <string[]> [[-option] {<None> | <Constructor> | <Dispose> | <Finalizer> | <Method> | <Property> | <Delegates> | <Events> | <Exception> | <Lock> | <Error> | <Errors> | <Warning> | <Verbose> | <WriteLine> | <Data> | <Scope> | <ExecutionFlow> | <Assert> | <All>}] [-filePath <string>] [-debugger] [-pSHost] [-listenerOption {<None> | <LogicalOperationStack> | <DateTime> | <Timestamp> | <ProcessId> | <ThreadId> | <Callstack>}] [-passThru] [-force] [<CommonParameters>]

 

Set-TraceSource [-name] <string[]> [-removeListener <string[]>] [<CommonParameters>]

 

Set-TraceSource [-name] <string[]> [-removeFileListener <string[]>] [<CommonParameters>]

 

DETAILED DESCRIPTION

The Set-TraceSource cmdlet configures, starts, and stops a trace of a Windows PowerShell component. You can use it to specify which components will be traced and where the tracing output is sent.

 

PARAMETERS

 

-name <string[]>

Determines which components are traced. Enter the name of the trace source of each component. Wildcards are permitted.

 

Required?

true

Position?

1

Default value

 

Accept pipeline input?  

true (ByValue, ByPropertyName)

Accept wildcard characters? 

true

 

-option <PSTraceSourceOptions>

Determines the type of events that are traced.

 

The valid values are: None, Constructor, Dispose, Finalizer, Method, Property, Delegates, Events, Exception, Lock, Error, Errors, Warning, Verbose, WriteLine, Data, Scope, ExecutionFlow, Assert, and All. "All" is the default.

 

The following values are combinations of other values:

 

·          ExecutionFlow: (Constructor, Dispose, Finalizer, Method, Delegates, Events, and Scope)

·          Data: (Constructor, Dispose, Finalizer, Property, Verbose, and WriteLine)

·          Errors: (Error and Exception).

 

To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "Constructor,Dispose".

 

The following lists the acceptable values for this parameter:

 

·          None

·          Constructor

·          Dispose

·          Finalizer

·          Method

·          Property

·          Delegates

·          Events

·          Exception

·          Lock

·          Error

·          Errors

·          Warning

·          Verbose

·          WriteLine

·          Data

·          Scope

·          ExecutionFlow

·          Assert

·          All

 

Required?

false

Position?

2

Default value

 

Accept pipeline input?  

true (ByPropertyName)

Accept wildcard characters? 

false

 

-filePath <string>

Sends the trace output to specified file. This parameter also selects the file trace listener. If you use this parameter to start the trace, use the RemoveFileListener parameter to stop the trace.

 

Required?

false

Position?

named

Default value

 

Accept pipeline input?  

false

Accept wildcard characters? 

true

 

-debugger <SwitchParameter>

Sends the trace output to the debugger. You can view the output in any user-mode or kernel mode debugger or in Visual Studio. This parameter also selects the default trace listener.

 

Required?

false

Position?

named

Default value

False

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-pSHost <SwitchParameter>

Sends the trace output to the Windows PowerShell host. This parameter also selects the PSHost trace listener.

 

Required?

false

Position?

named

Default value

False

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-listenerOption <TraceOptions>

Adds optional data to the prefix of each trace message in the output. The valid values are None, LogicalOperationStack, DateTime, Timestamp, ProcessId, ThreadId, and Callstack. "None" is the default.

 

To specify multiple options, separate them with commas, but with no spaces, and enclose them in quotation marks, such as "ProcessID,ThreadID".

 

The following lists the acceptable values for this parameter:

 

·          None

·          LogicalOperationStack

·          DateTime

·          Timestamp

·          ProcessId

·          ThreadId

·          Callstack

 

Required?

false

Position?

named

Default value

TraceOptions.None

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-passThru <SwitchParameter>

Passes the object created by this cmdlet through the pipeline. By default, this cmdlet does not pass any objects through the pipeline.

 

Required?

false

Position?

named

Default value

False

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

-removeListener <string[]>

Stops the trace by removing the trace listener.

 

Use the following values with RemoveListener:

 

·          To remove PSHost (console), type "Host".

·          To remove Debugger, type "Debug".

·          To remove all trace listeners, type "*".

 

To remove the file trace listener, use the RemoveFileListener parameter.

 

Required?

false

Position?

named

Default value

 

Accept pipeline input?  

false

Accept wildcard characters? 

true

 

-removeFileListener <string[]>

Stops the trace by removing the file trace listener associated with the specified file. Enter the path and file name of the trace output file.

 

Required?

false

Position?

named

Default value

 

Accept pipeline input?  

false

Accept wildcard characters? 

true

 

-force <SwitchParameter>

Overrides restrictions that prevent the command from succeeding, just so the changes do not compromise security. For example, Force will override the read-only attribute or create directories to complete a file path, but it will not attempt to change file permissions.

 

Required?

false

Position?

named

Default value

False

Accept pipeline input?  

false

Accept wildcard characters? 

false

 

<CommonParameters>

This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, and -OutVariable. For more information, type, "get-help about_commonparameters".

 

INPUT TYPE

System.Management.Automation.PSTraceSource

 

RETURN TYPE

None or System.Management.Automation.PSTraceSource,when Passthru specified.

 

NOTES

 

For more information, type "Get-Help Set-TraceSource -detailed". For technical information, type "Get-Help Set-TraceSource -full".

 

Tracing is a method that developers use to debug and refine programs. When tracing, the program generates detailed messages about each step in its internal processing.

 

The Windows PowerShell tracing cmdlets are designed to help Windows PowerShell developers, but they are available to all users. They let you monitor nearly every aspect of the functionality of the shell.

 

A "trace source" is the part of each Windows PowerShell component that manages tracing and generates trace messages for the component. To trace a component, you identify its trace source.

 

A "trace listener" receives the output of the trace and displays it to the user. You can elect to send the trace data to a user-mode or kernel-mode debugger, to the console, to a file, or to a custom listener derived from the System.Diagnostics.TraceListener class.

 

To start a trace, use the -Name parameter to specify a trace source (the component to be traced), and the FilePath, Debugger, or PSHost parameters to specify a listener (a destination for the output). Use the Options parameter to determine the types of events that are traced and the ListenerOptions parameter to configure the trace output.

 

To change the configuration of a trace, enter a Set-TraceSource command as you would to start a trace. Windows PowerShell recognizes that the trace source is already being traced. It stops the trace, adds the new configuration, and starts or restarts the trace.

 

To stop a trace, use the RemoveListener parameter. To stop a trace that uses the file listener (a trace started by using the -FilePath parameter), use the RemoveFileListener parameter. When you remove the listener, the trace stops.

 

To determine which components can be traced, use Get-TraceSource. The trace sources for each module are loaded automatically when the component is in use and they appear in the output of Get-TraceSource.

 

When specifying multiple values for a parameter, use commas to separate the values. For example, "<parameter-name> <value1>, <value2>".

 

EXAMPLE 1

 

Set-TraceSource -Name Parameterbinding -Option ExecutionFlow -PSHost '

-ListenerOption "ProcessID,TimeStamp"

 

This command starts tracing for the ParameterBinding component of Windows PowerShell. It uses the Name parameter to specify the trace source, the Option parameter to select the ExecutionFlow trace events, and the PSHost parameter to select the Windows PowerShell host listener, which sends the output to the console. The ListenerOption parameter adds the ProcessID and TimeStamp values to the trace message prefix.

 

EXAMPLE 2

 

set-tracesource -name ParameterBinding -RemoveListener Host

 

This command stops the trace of the ParameterBinding component of Windows PowerShell. It uses the Name parameter to identify the component that was being traced and the RemoveListener parameter to identify the trace listener.

 

RELATED LINKS

Get-TraceSource

Trace-Command

Set-PSDebug