Skip to content

Latest commit

 

History

History
157 lines (106 loc) · 3.81 KB

Trace-Message.md

File metadata and controls

157 lines (106 loc) · 3.81 KB
Raw
external help file Module Name online version schema
PSScriptTools-help.xml
PSScriptTools
2.0.0

Trace-Message

SYNOPSIS

Create a graphical trace window.

SYNTAX

message (Default)

Trace-Message [[-Message] <String>] [<CommonParameters>]

init

Trace-Message [-Title <String>] [-BackgroundColor <String>] [-Width <Int32>]
[-Height <Int32>] [<CommonParameters>]

DESCRIPTION

Trace-Message is designed to be used with script or function. Its purpose is to create a graphical trace window using Windows Presentation Foundation. Inside the function or script, you can use this command to send messages to the window. When finished, you have an option to save the output to a text file.

There are 3 steps to using this function. First, in your code, you need to create a boolean global variable called TraceEnabled. When the value is $True, the Trace-Message command will run. When set to false, the command will be ignored. Second, you need to initialize a form, specifying the title and dimensions. The form will automatically include some pre-defined metadata. Finally, you can send trace messages to the window. All messages are prepended with a timestamp.

This command is not optimized for performance and is intended for development purposes. When your code is finished, you can set $TraceEnabled to $False. If you need to troubleshoot, you can set it to $True.

EXAMPLES

Example 1

PS C:\> Trace-Message -title "Troubleshooting Log" -width 600

This command will initialize a trace window with the given title and width. It is assumed you have set $TraceEnabled to $True. This is a command you would normally run in your code and not from the console.

Example 2

PS C:\> Trace-Message -message "Starting MyCommand"

This example is a continuation of the previous example. The message text will be appended to the graphical form, prepended with a timestamp.

PARAMETERS

-BackgroundColor

Specify a background color for the trace window. You can use console colors like "Cyan" or HTML color codes.

Type: String
Parameter Sets: init
Aliases:

Required: False
Position: Named
Default value: "#FFFFF8DC",
Accept pipeline input: False
Accept wildcard characters: False

-Height

Specify the Width of the trace window.

Type: Int32
Parameter Sets: init
Aliases:

Required: False
Position: Named
Default value: 500
Accept pipeline input: False
Accept wildcard characters: False

-Message

Specify a message to write to the trace window.

Type: String
Parameter Sets: message
Aliases:

Required: $True
Position: 0
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-Title

Specify a title for the trace window.

Type: String
Parameter Sets: init
Aliases:

Required: False
Position: Named
Default value: "Trace Messages"
Accept pipeline input: False
Accept wildcard characters: False

-Width

Specify the Width of the trace window.

Type: Int32
Parameter Sets: init
Aliases:

Required: False
Position: Named
Default value: 800
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

System.String

OUTPUTS

None

NOTES

Look at $PSSamplePath\Get-Status.ps1 for a demonstration of this command in a function. The buttons have key acclerators of Q and S.

Learn more about PowerShell: http://jdhitsolutions.com/blog/essential-powershell-resources/

RELATED LINKS

Write-Verbose