PSScriptTools

This PowerShell module contains a number of functions you might use to enhance your own functions and scripts. The Samples folder contains demonstration script files.

Current Release

The current release is PSScriptTools-v1.3.0

You can also install this from the PowerShell Gallery:

Install-Module PSScriptTools

or in PowerShell Core:

Install-Module PSScriptTools -scope currentuser

Please post any questions, problems or feedback in Issues. Any input is greatly appreciated.

Add-Border

This command will create a character or text based border around a line of text. You might use this to create a formatted text report or to improve the display of information to the screen.

PS C:\> add-border $env:computername

*************
*   COWPC   *
*************

Get-PSWho

This command will provide a summary of relevant information for the current user in a PowerShell Session. You might use this to troubleshoot an end-user problem running a script or command.

PS C:\> Get-PSWho

User            : COWPC\Jeff
Elevated        : True
Computername    : COWPC
OperatingSystem : Microsoft Windows 10 Pro [64-bit]
OSVersion       : 10.0.16299
PSVersion       : 5.1.16299.64
Edition         : Desktop
PSHost          : ConsoleHost
WSMan           : 3.0
ExecutionPolicy : RemoteSigned
Culture         : en-US

New-CustomFileName

This command will generate a custom file name based on a template string that you provide.

PS C:\> New-CustomFileName %computername_%day%monthname%yr-%time.log
COWPC_28Nov17-142138.log

PS C:\> New-CustomFileName %dayofweek-%####.dat
Tuesday-3128.dat

You can create a template string using any of these variables. Most of these should be self-explanatory

• %username
• %computername
• %year - 4 digit year
• %yr - 2 digit year
• %monthname - The abbreviated month name
• %month - The month number
• %dayofweek - The full name of the week day
• %day
• %hour
• %minute
• %time
• %string - A random string
• %guid

You can also insert a random number using %### with a # character for each digit. If you want a 2 digit random number use %##. If you want 6 digits, use %######.

New-RandomFileName

Create a new random file name. The default is a completely random name including the extension.

PS C:\> new-randomfilename
fykxecvh.ipw

But you can specify an extension.

PS C:\> new-randomfilename -extension dat
emevgq3r.dat

Optionally you can create a random file name using the TEMP folder or your HOME folder. On Windows platforms this will default to your Documents folder.

PS C:\> new-randomfilename -extension log -UseHomeFolder
C:\Users\Jeff\Documents\kbyw4fda.log

On Linux machines it will be the home folder.

PS /mnt/c/scripts> new-randomfilename -home -Extension tmp
/home/jhicks/oces0epq.tmp

Write-Detail

This command is designed to be used within your functions and scripts to make it easier to write a detailed message that you can use as verbose output. The assumption is that you are using an advanced function with a Begin, Process and End scriptblocks. You can create a detailed message to indicate what part of the code is being executed. The output can be configured to include a datetime stamp or just the time.

PS C:\> write-detail "Getting file information" -Prefix Process -Date
9/15/2018 11:42:43 [PROCESS] Getting file information

In a script you might use it like this:

Begin {
    Write-Detail "Starting $($myinvocation.mycommand)" -Prefix begin -time | Write-Verbose
    $tabs = "`t" * $tab
    Write-Detail "Using a tab of $tab" -Prefix BEGIN -time | Write-Verbose
} #begin

Out-VerboseTee

This command is intended to let you see your verbose output and write the verbose messages to a log file. It will only work if the verbose pipeline is enabled, usually when your command is run with -Verbose. This function is designed to be used within your scripts and functions. You either have to hard code a file name or find some other way to define it in your function or control script. You could pass a value as a parameter or set it as a PSDefaultParameterValue.

This command has an alias of Tee-Verbose.

Begin {
    $log = New-RandomFilename -useTemp -extension log
    Write-Detail "Starting $($myinvocation.mycommand)" -Prefix begin | Tee-Verbose $log
    Write-Detail "Logging verbose output to $log" -prefix begin | Tee-Verbose -append
    Write-Detail "Initializing data array" -Prefix begin | Tee-Verbose $log -append
    $data = @()
} #begin

When the command is run with -Verbose you will see the verbose output and it will be saved to the specified log file.

Out-ConditionalColor

This command is designed to take pipeline input and display it in a colorized format,based on a set of conditions. Unlike Write-Host which doesn't write to the pipeline, this command will write to the pipeline.

You can use a simple hashtable to define a color if the given property matches the hashtable key.

Or you can specify an ordered hashtable for more complex processing.

This command doesn't always work depending on the type of object you pipe to it. The problem appears to be related to the formatting system. Development and testing is ongoing.

Copy-Command

This command will copy a PowerShell command, including parameters and help to a new user-specified command. You can use this to create a "wrapper" function or to easily create a proxy function. The default behavior is to create a copy of the command complete with the original comment-based help block.

Format-Functions

A set of simple commands to make it easier to format values.

PS C:\> format-percent -Value 123.5646MB -total 1GB -Decimal 4
12.0669
PS C:\> format-string "powershell" -Reverse -Case Proper
Llehsrewop
PS C:\>  format-value 1235465676 -Unit kb
1206509

Get-PSLocation

A simple function to get common locations. This can be useful with cross-platform scripting.

Get-PowerShellEngine

Use this command to quickly get the path to the PowerShell executable. In Windows you should get a result like this:

PS C:\> Get-PowerShellEngine
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe

But PowerShell Core is a bit different:

PS /home/jhicks> Get-PowerShellEngine 
/opt/microsoft/powershell/6/pwsh

You can also get detailed information.

Results will vary depending on whether you are running Windows PowerShell or PowerShell Core.

Out-More

This command provides a PowerShell alternative to the cmd.exe MORE command, which doesn't work in the PowerShell ISE. When you have screens of information, you can page it with this function.

get-service | out-more

This also works in PowerShell Core.

Invoke-InputBox

This function is a graphical replacement for Read-Host. It creates a simple WPF form that you can use to get user input. The value of the text box will be written to the pipeline.

$name = Invoke-InputBox -Prompt "Enter a user name" -Title "New User Setup"

You can also capture a secure string.

Invoke-Inputbox -Prompt "Enter a password for $Name" -AsSecureString -BackgroundColor red

This example also demonstrates that you can change form's background color. This function will not work in PowerShell Core.

ToDo

Because this module is intended to make scripting easier for you, it adds options to insert ToDo statements into PowerShell files. If you are using the PowerShell ISE or VS Code and import this module, it will add the capability to insert a line like this:

# [12/13/2017 16:52:40] TODO: Add parameters

In the PowerShell ISE, you will get a new menu under Add-Ons

You can use the menu or keyboard shortcut which will launch an input box.

The comment will be inserted at the current cursor location.

In VS Code, access the command palette (Ctrl+Shift+P) and then "PowerShell: Show Additional Commands from PowerShell Modules". Select "Insert ToDo" from the list and you'll get the same input box. Note that this will only work for PowerShell files.

Test-Expression

The primary command can be used to test a PowerShell expression or scriptblock for a specified number of times and calculate the average runtime, in milliseconds, over all the tests.

Why?

When you run a single test with Measure-Command the result might be affected by any number of factors. Likewise, running multiple tests may also be influenced by things such as caching. The goal in this module is to provide a test framework where you can run a test repeatedly with either a static or random interval between each test. The results are aggregated and analyzed. Hopefully, this will provide a more meaningful or realistic result.

Examples

The output will also show the median and trimmed values as well as some metadata about the current PowerShell session.

PS C:\> $cred = Get-credential globomantics\administrator
PS C:\> Test-Expression {param($cred) get-wmiobject win32_logicaldisk -computer chi-dc01 -credential $cred } -argumentList $cred
   
Tests        : 1
TestInterval : 0.5
AverageMS    : 1990.6779
MinimumMS    : 1990.6779
MaximumMS    : 1990.6779
MedianMS     : 1990.6779
TrimmedMS    : 
PSVersion    : 5.1.14409.1005
OS           : Microsoft Windows 8.1 Enterprise

You can also run multiple tests with random time intervals.

PS C:\>Test-expression {param([string[]]$Names) get-service $names} -count 5 -IncludeExpression -argumentlist @('bits','wuauserv','winrm') -RandomMinimum .5 -RandomMaximum 5.5

Tests        : 5
TestInterval : Random
AverageMS    : 1.91406
MinimumMS    : 0.4657
MaximumMS    : 7.5746
MedianMS     : 0.4806
TrimmedMS    : 0.51
PSVersion    : 5.1.14409.1005
OS           : Microsoft Windows 8.1 Enterprise
Expression   : param([string[]]$Names) get-service $names
Arguments    : {bits, wuauserv, winrm}

For very long running tests, you can run them as a background job.

Graphical Testing

The module also includes a graphical command called Test-ExpressionForm. This is intended to serve as both an entry and results form.

When you quit the form the last result will be written to the pipeline including all metadata, the scriptblock and any arguments.

Find-CimClass

This function is designed to search an entire CIM repository for a class name. Sometimes, you may have a guess about a class name but not know the full name or even the correct namespace. Find-CimClass will recursively search for a given classname. You can use wildcards and search remote computers.

ConvertTo-Markdown

This command is designed to accept pipelined output and create a markdown document. The pipeline output will formatted as a text block. You can optionally define a title, content to appear before the output and content to appear after the output. You can run a command like this:

 Get-Service Bits,Winrm | Convertto-Markdown -title "Service Check" -precontent "## $($env:computername)"  -postcontent "_report $(Get-Date)_"

which generates this markdown:

# Service Check

## BOVINE320

```text

Status   Name               DisplayName
------   ----               -----------
Running  Bits               Background Intelligent Transfer Ser...
Running  Winrm              Windows Remote Management (WS-Manag...
```

_report 09/25/2018 09:57:12_

Because the function writes markdown to the pipeline you will need to pipe it to a command Out-File to create a file.

ConvertTo-WPFGrid

This command is an alternative to Out-Gridview. It works much the same way. Run a PowerShell command and pipe it to this command. The output will be displayed in a data grid. You can click on column headings to sort. You can resize columns and you can re-order columns.

get-eventlog -list -ComputerName DOM1,SRV1,SRV2 |
Select Machinename,Log,MaximumKilobytes,Overflowaction,
@{Name="RetentionDays";Expression={$_.MinimumRetentionDays}},
@{Name="Entries";Expression = {$_.entries.count}} | 
ConvertTo-WPFGrid -Title "Event Log Report"

Compatibility

Where possible these commands have been tested with PowerShell Core, but not every platform. If you encounter problems,have suggestions or other feedback, please post an issue.

last updated 25 September 2018