Tag Archives: PSHost

cmdlet, Command, Trace

Trace-Command

NAME
    Trace-Command

SYNOPSIS
    Configures and starts a trace of the specified expression or command.

SYNTAX
    Trace-Command [-Command] <string> [-ArgumentList <Object[]>] [-Name] <string[]> [[-Option] {None | Constructor | Dispose | Finalizer | Method | Property | Delegates | Events | Exception | Lock | Error | Errors | Warning | Verbose | WriteLine | Data | Scope | ExecutionFlow | Assert | All}] [-Debugger] [-FilePath <string>] [-Force] [-InputObject <psobject>] [-ListenerOption {None | LogicalOperationStack | DateTime | Timestamp | ProcessId | ThreadId | Callstack}] [-PSHost] [<CommonParameters>]

    Trace-Command [-Expression] <scriptblock> [-Name] <string[]> [[-Option] {None | Constructor | Dispose | Finalizer | Method | Property | Delegates | Events | Exception | Lock | Error | Errors | Warning | Verbose | WriteLine | Data | Scope | ExecutionFlow | Assert | All}] [-Debugger] [-FilePath <string>] [-Force] [-InputObject <psobject>] [-ListenerOption {None | LogicalOperationStack | DateTime | Timestamp | ProcessId | ThreadId | Callstack}] [-PSHost] [<CommonParameters>]

DESCRIPTION
    The Trace-Command cmdlet configures and starts a trace of the specified expression or command. It works like Set-TraceSource, except that it applies only to the specified command.

PARAMETERS
    -ArgumentList <Object[]>
        Specifies the parameters and parameter values for the command being traced. The Alias for ArgumentList is Args. This feature is especially useful for debugging dynamic parameters.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Command <string>
        Specifies a command that is being processed during the trace.

        Required?                    true
        Position?                    2
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -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
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Expression <scriptblock>
        Specifies the expression that is being processed during the trace. Enclose the expression in curly braces ({}).

        Required?                    true
        Position?                    2
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -FilePath <string>
        Sends the trace output to the specified file. This parameter also selects the file trace listener.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Force [<SwitchParameter>]
        Allows the cmdlet to append trace information to a read-only file. Used with the FilePath parameter. Even using the Force parameter, the cmdlet cannot override security restrictions.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -InputObject <psobject>
        Provides input to the expression that is being processed during the trace.

        You can enter a Variable that represents the input that the expression accepts, or pass an object through the pipeline.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     true (ByValue)
        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”.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -Name <string[]>
        Determines which Windows PowerShell components are traced. Enter the name of the trace source of each component. Wildcards are permitted. To find the trace sources on your computer, type “Get-TraceSource“.

        Required?                    true
        Position?                    1
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -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”.

        Required?                    false
        Position?                    3
        Default value
        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
        Accept pipeline input?     false
        Accept wildcard characters? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.Management.Automation.PSObject
        You can pipe objects that represent input to the expression to Trace-Command.

OUTPUTS
    System.Management.Automation.PSObject
        Returns the command trace in the debug stream.

NOTES

        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.

        To find the Windows PowerShell components that are enabled for tracing, type “Get-Help Get-TraceSource.”

        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 host or console, to a file, or to a custom listener derived from the System.Diagnostics.TraceListener class.

        When you use the Command parameter set, Windows PowerShell processes the command just as it would be processed in a pipeline. For example, command discovery is not repeated for each incoming object.

        The names of the Name, Expression, Option, and Command parameters are optional. If you omit the parameter names, the unnamed parameter values must appear in this order: Name, Expression, Option or Name, Command,-Option . If you include the parameter names, the parameters can appear in any order.

    ————————– EXAMPLE 1 ————————–

    C:\PS>Trace-Command -Name metadata,parameterbinding,cmdlet -Expression {Get-Process notepad} -PSHost

    Description
    ———–
    This command starts a trace of metadata processing, parameter binding, and cmdlet creation and destruction of the “Get-Process notepad” expression. It uses the Name parameter to specify the trace sources, the Expression parameter to specify the command, and the PSHost parameter to send the output to the console. Because it does not specify any tracing options or listener options, the command uses the defaults, “All” for the tracing options, and “None” for the listener options.

    ————————– EXAMPLE 2 ————————–

    C:\PS>Trace-Command -Name commandprocessor,pipelineprocessor -command Get-Alias -argumentlist “ghy” -Option executionflow -ListenerOption “timestamp,callstack” -FilePath c:\test\debug.txt

    Description
    ———–
    This command starts a trace of the command processor and pipeline processor while processing the “Get-Alias cd” command.

    It uses the Name parameter to specify the trace sources, the Command parameter to specify the command, the ArgumentList parameter to specify the parameters of the Get-Alias command, the Option parameter to specify tracing options, and the ListenerOption parameter to specify the fields in the trace message prefix. The FilePath parameter sends the output to the C:\Test\Debug.txt file.

    ————————– EXAMPLE 3 ————————–

    C:\PS>$a = “i*”

    C:\PS> Trace-Command parameterbinding {Get-Alias $input} -PSHost -InputObject $a

    Description
    ———–
    These commands trace the actions of the ParameterBinding operations of Windows PowerShell while it processes a Get-Alias expression that takes input from the pipeline.

    In Trace-Command, the InputObject parameter passes an object to the expression that is being processed during the trace.

    The first command stores the string “i*” in the $a Variable. The second command uses the Trace-Command cmdlet with the ParameterBinding trace source. The PSHost parameter sends the output to the console.

    The expression being processed is “Get-Alias $input”, where the $input Variable is associated with the InputObject parameter. The InputObject parameter passes the Variable $a to the expression. In effect, the command being processed during the trace is “Get-Alias -InputObject $a” or “$a | Get-Alias“.

RELATED LINKS
    Online version: http://go.microsoft.com/fwlink/?LinkID=113419
    Get-TraceSource
    Set-TraceSource

cmdlet, Set, TraceSource

Set-TraceSource

NAME
    Set-TraceSource

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

SYNTAX
    Set-TraceSource [[-Option] {None | Constructor | Dispose | Finalizer | Method | Property | Delegates | Events | Exception | Lock | Error | Errors | Warning | Verbose | WriteLine | Data | Scope | ExecutionFlow | Assert | All}] [-Debugger] [-FilePath <string>] [-Force] [-ListenerOption {None | LogicalOperationStack | DateTime | Timestamp | ProcessId | ThreadId | Callstack}] [-PassThru] [-PSHost] [-Name] <string[]> [<CommonParameters>]

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

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

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
    -Debugger [<SwitchParameter>]
        Sends the trace output to the debugger. You can view the output in any user-mode or kernel mode debugger or in Microsoft Visual Studio. This parameter also selects the default trace listener.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -FilePath <string>
        Sends the trace output to the 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? false

    -Force [<SwitchParameter>]
        Allows the cmdlet to overwrite a read-only file. Use with the FilePath parameter.

        Required?                    false
        Position?                    named
        Default value
        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”.

        Required?                    false
        Position?                    named
        Default value
        Accept pipeline input?     false
        Accept wildcard characters? false

    -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? false

    -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”.

        Required?                    false
        Position?                    2
        Default value
        Accept pipeline input?     true (ByPropertyName)
        Accept wildcard characters? false

    -PassThru [<SwitchParameter>]
        Returns an object representing the trace session. By default, this cmdlet does not generate any output.

        Required?                    false
        Position?                    named
        Default value
        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
        Accept pipeline input?     false
        Accept wildcard characters? false

    -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? 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? false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer and OutVariable. For more information, type,
        “Get-Help about_CommonParameters“.

INPUTS
    System.String
        You can pipe a string that contains a name to Set-TraceSource.

OUTPUTS
    None or System.Management.Automation.PSTraceSource
        When you use the PassThru parameter, Set-TraceSource generates a System.Management.Automation.PSTraceSource object representing the trace session. Otherwise, this cmdlet does not generate any output.

NOTES

        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 Windows PowerShell.

        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.

    ————————– EXAMPLE 1 ————————–

    C:\PS>Set-TraceSource -Name Parameterbinding -Option ExecutionFlow -PSHost ‘
    -ListenerOption “ProcessID,TimeStamp”

    Description
    ———–
    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 ————————–

    C:\PS>Set-TraceSource -Name ParameterBinding -RemoveListener Host

    Description
    ———–
    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
    Online version: http://go.microsoft.com/fwlink/?LinkID=113400
    Get-TraceSource
    Trace-Command
    Set-PSDebug