Generic PowerShell Template #1

I am an organizational nut.  I believe a well-organized and properly documented Generic PowerShell Template will work better.  To that end, when I create scripts, I make sure I follow the same organizational structure every time.

Each section is cleanly identified in the script and can be easily followed and changed by others.  PowerShell has made great improvements in documenting and organizing scripts.  Following a clean structure has never been easier.  All we need is a good PowerShell Template and some basic instructions on how it works.  This post will accomplish both.

This script is divided into several sections.  All the sections can be collapsed to make managing larger scripts easier.  I also use functions to be used freely.  The top section used comment based help as well as each function area.  It is critical to add as many comments as possible throughout the script.  This is to help others (as well as yourself) work through issues and find sections easily.

Script Basics

The first line calls for the minimal version of PowerShell that is needed for the commands you are using.  The next section is the Comment Based Help section and you should fill in all details as completely as possible to make the script helpful to others.

The third section is important.  It cannot have any commands or spaces above it (Comments OK).  It is pulling in line inputs from the command line and making them available for use within the script.  Often this will be replaced with file inputs which I will get into on another post.

For troubleshooting and early script development, you should comment out the error actions line.  This will suppress errors and continue the script.

The rest of this section declares any variables used in the script.  In my designs, I only use this section if a variable is used for every part of the script.  If there are variables just used in a special function, I would declare them in that function so I would have the ability to pull functions out and reuse them elsewhere.  In this script, the declare section mostly has my basics like date and time variables as well as log file setup.

If you notices I use “#region” and “#endregion” comments just as a way to reduce sections for readability.  This is one of the few items in PowerShellI have learned are case sensitive and these commands will not work if caps are put in.  In these regions I setup special commands that are used for special calls.  For example, connections to databases or files, connections to external servers, or any other prep work that may be needed.

Script Functions

The next 2 sections are functions with standard comment, begin, process, and end sections.  Please learn about functions and each section because that have different purposes and limitations within the script.

The execution section is the hub to the script where the main processing gets done calling in each function or command to meet the needs of the admin. This will be the largest part of the script and can also be reduces with the region sections.  The script closes out with more commends to a log file.

That’s it.  I will be making updates to this over time and create other special template but this one so far as served me well.  Please comment and let me know what you think or ways it can be improved.  Over time with the help of other system admins, this template will improve and become a great tool for others to use.

Please excuse the code display.  I use to use a great plugin that displayed the code with many more features but that plugin has not been updated in several years and I can no longer trust it is secure and safe to use.  I will continue to look for better ways to display my scripts.  If you know of a great way to display them, please leave a note in the comment section and I can try it out.

Let me know what you think of this generic PowerShell template and what sections you think I Should add to it?  Comment below if you have found this useful or if you have any ideas to make it better.  IF you want to receive new scripts in the future, just add your email to the signup script and I will let you know when I post new stuff.

#requires -version 2
<#
.SYNOPSIS
  <Overview of script>

.DESCRIPTION
  <Brief description of script>

.PARAMETER <Parameter_Name>
    <Brief description of parameter input required. Repeat this attribute if required>

.INPUTS
  <Inputs if any, otherwise state None>

.OUTPUTS
  <Outputs if any, otherwise state None - example: Log file stored in C:\Windows\Temp\<name>.log>

.NOTES
  Version:        1.0
  Author:         <Name>
  Creation Date:  <Date>
  Purpose/Change: Initial script development
  
.EXAMPLE
  <Example goes here. Repeat this attribute for more than one example>
#>
 
#---------------------------------------------------------[Initialisations]--------------------------------------------------------
 
#Set Error Action to Silently Continue
$ErrorActionPreference = "SilentlyContinue"
 
#Dot Source required Function Libraries
. "C:\Scripts\Functions\Logging_Functions.ps1"
 
#----------------------------------------------------------[Declarations]----------------------------------------------------------
 
#Script Version
$sScriptVersion = "1.0"
 
#Log File Info
$sLogPath = "C:\Windows\Temp"
$sLogName = "<script_name>.log"
$sLogFile = Join-Path -Path $sLogPath -ChildPath $sLogName
 
#-----------------------------------------------------------[Functions]------------------------------------------------------------
 
<#

Function <FunctionName>{
  Param()
  
  Begin{
    Log-Write -LogPath $sLogFile -LineValue "<description of what is going on>..."
  }
  
  Process{
    Try{
      <code goes here>
    }
    
    Catch{
      Log-Error -LogPath $sLogFile -ErrorDesc $_.Exception -ExitGracefully $True
      Break
    }
  }
  
  End{
    If($?){
      Log-Write -LogPath $sLogFile -LineValue "Completed Successfully."
      Log-Write -LogPath $sLogFile -LineValue " "
    }
  }
}

#>
 
#-----------------------------------------------------------[Execution]------------------------------------------------------------
 
#Log-Start -LogPath $sLogPath -LogName $sLogName -ScriptVersion $sScriptVersion
#Script Execution goes here
#Log-Finish -LogPath $sLogFile