Rules to Better Powershell

In PowerShell, you can use Comment-Based Help snippets to better define what your function or script is doing, its examples, inputs, and outputs.

When you are building functions in PowerShell, you can use Comment-Based Help snippets at the beginning of the function body, at the end of the function body or before the Function keyword.

If you do this, the Get-Help cmdlet will show the information contained in the code for your function (making it super easy for anyone to use and understand it!).

You can use it like this (beginning of the Function body):

function Get-Function
{
  <#
    .<help keyword>
    <help content>
  #>

  # function logic
}

Figure: Good example - Using Comment-Based Help for Functions

Or like this (before the function keyword):

<#
  .<help keyword>
  <help content>
#>
function Get-Function { }

Figure: Good example - Using Comment-Based Help for Function

You can do the same with scripts, with a little difference - you need to place the snippet at the beginning or end of the script file:

#Accept input parameters
param(
    [switch]$FullAccess,
    [switch]$SendAs,
    [switch]$SendOnBehalf,
    [switch]$UserMailboxOnly,
    [switch]$AdminsOnly,
    [string]$MBNamesFile,
    [string]$UserName,
    [string]$Password,
    [switch]$MFA
)

Figure: Bad example - Script not using any Comment-Based Help snippet

<#
.SYNOPSIS
Gets THE IP addresses in a file and checks if they are on blacklists across the web.

.DESCRIPTION
Gets THE IP addresses in a file and checks if they are on blacklists across the web. If they are, add them to the final blacklist file that will be used by the firewall.

.EXAMPLE
PS C:\> Check-Blacklist -File "FileWithNewIPs" -BaseFile "BaseBlacklistFile" -Logfile "LogfileLocation"
Checks the newly-generated blacklist file to see if any IPs are blacklisted, if yes, adds them to the final blacklist file.

.NOTES
Created by Kiki Biancatti for SSW.

#>
Param(
[Parameter(Position = 0, Mandatory = $true)]
[string] $File,
[Parameter(Position = 1, Mandatory = $true)]
[string] $BaseFile,
[Parameter(Position = 2, Mandatory = $true)]
[string] $LogFile
) ...

Figure: Good example - Using Comment-Based Help at the beginning of a script file

You can check some good PowerShell examples in SSW's GitHub:

In PowerShell, you can easily create variables without explicitly typing them and that leads to some hardcoded "magic" strings.

Instead of using XML, JSON, YAML, or TXT files, PowerShell "accidentally" created a very nice configuration file format, PSD1.

PSD1 us the filename extension for PowerShell module descriptions, and this file contains metadata for that module. You can, however, load any kind of data from a PSD1 file using a simple cmdlet.

Import-PowerShellDataFile.

Some of the things we can do in a PSD1 file:

We can write comments;
We can use lots of data types, like int, float, bool, string, array...
We don't need to use quotes around field names like JSON;
And more.

Instead of keeping all your important URLs and FQDNs inside your PowerShell script, you should keep the script itself clean and "sanitized" from those hard-coded variables, so it can be freely shared on GitHub without any security concerns for you or your company. It also makes the script much more maintainable, where you can easily change the variables in the .PSD1 file without needing to change your core script.Don't forget to add the configuration file to .gitignore!

bad script variables — Figure: Bad Example - Your script variables are in the script itself, making it insecure to share outside

Credits to: PowerShell Accidentally Created A Nice Configuration Format.

PowerShell Universal is a platform to make websites, dashboards, and scripts using only PowerShell commands, without the need to have any web development knowledge, perfect for your SysAdmins.

PowerShell Universal is a platform built by Ironman Software that allows you to:

Create webpages and dashboards with PowerShell commands;
Orchestrate PowerShell script execution, together with auditing;
Use its API to communicate with the scripts and dashboards.

For example, SSW uses PowerShell Universal Dashboards to automate repeating SysAdmin tasks and create a nice user interface to run them:

automated standard — Figure: Good Example - Dashboard to automate employee's leaving standard

Running commands directly in the PowerShell CLI without data, schedule or a nice UI is a thing of the past, and you should be using the capabilities of PowerShell Universal to keep your scripts well maintained.

running commands hand — Figure: Bad Example - Running commands by hand directly

You can read its full documentation at https://docs.ironmansoftware.com.

Rules to Better Powershell - 3 Rules

Do you use Comment-Based Help in PowerShell functions and scripts?

Do you use configuration files for PowerShell scripts?

Do you use the best PowerShell automation platform?