Rules to Better Powershell

​​​

Hold on a second! How would you like to view this content?
Just the title! A brief blurb! Gimme everything!
  1. Do you use Comment-Based Help in PowerShell functions and scripts?

    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

  2. Do you use configuration files for PowerShell scripts?

    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.

    You can check a sample PSD1 file here: https://gist.github.com/ssg/a8e31af18ae8e03dcdc0f23e02793eca#file-sample-psd1

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

    1. We can write comments;
    2. We can use lots of data types, like int, float, bool, string, array...
    3. We don't need to use quotes around field names like JSON;
    4. 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.png
    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.​​

  3. Do you use the best PowerShell automation platform?

    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:

    1. Create webpages and dashboards with PowerShell commands;
    2. Orchestrate PowerShell script execution, together with auditing;
    3. 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.png
    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.png
    Figure: Bad Example - Running commands by hand directly

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