PowerShell: Script Template

Script_Template.ps1

#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

How would one dump the result of the function to the log on success?

You can just use the Log-Write function, so for example replace the "Completed Successfully" on line

Log-Write -LogPath $sLogFile -LineValue "Completed Successfully."

with the variable that contains the result of what you are executing. So for example lets say $Result is the variable with the data you want to output then you can simply do this:

Log-Write -LogPath $sLogFile -LineValue $Result

The If($?){...} will only execute when the function was successful.

You could also use a "trap" if you want to always get the full output of a command whether it failed or succeeded in case a stack trace doesn't help you any.

I see you use custom functions for logging. Why don't you just use the Write-Output / Write-Progress / Write-Verbose cmdlet?

Why don't you just use the Write-Output / Write-Progress / Write-Verbose cmdlets?

Creating a small custom function would allow you to prepend a time stamp to the log entry.

function Write-Log {
    param (
        [Parameter(Mandatory=$False, Position=0)]
        [String]$Entry
    )

    "$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss.fff') $Entry" | Out-File -FilePath $LogFilePath -Append
}

$ExitCode = 0
$LogFilePath = "C:\Logs\MyScript.log"

Write-Log -Entry "Script MyScript started on $(Get-Date -Format 'dddd, MMMM dd, yyyy')."
Write-Log
Write-Log -Entry "Do stuff here."
Write-Log
Write-Log -Entry "Script MyScript ended ($ExitCode)."

Which results in this:

2018-07-17 00:39:06.719 Script MyScript started on Tuesday, July 17, 2018.
2018-07-17 00:39:06.720 
2018-07-17 00:39:06.725 Do stuff here.
2018-07-17 00:39:06.726 
2018-07-17 00:39:06.727 Script MyScript ended (0).

You'll also find PowerShell custom log functions that create SCCM cmtrace-style logs.

@99to5IT, my Get-Help won't work unless I put a newline between #requires -version 2 and <#. This seems to be consistent with PowerShell on Windows 10 as well as MacOS.

This is a beautiful way of building out a script! TY!

Jsnover would be proud.

@tresf

@99to5IT, my Get-Help won't work unless I put a newline between #requires -version 2 and <#. This seems to be consistent with PowerShell on Windows 10 as well as MacOS.

I can confirm, you are correct.

Is this up to date for version 5? Or are there certain things that can be removed? Or replaced with a new v5 cmdlet or format?

I only want a snippet that do

1. when i enter "run"
2. hit tab key, It simply autocomplete the expression to "g++ -g **.cpp -o main.exe && .\main.exe"

What's the references to Log-Start, Log-Write, Log-Finish, Log-Error? There are no such cmdlets in Powershell. There are Start-Transcript and Stop-Transcript though.

Log-Start, Log-Write, Log-Finish and Log-Error are in reference to the PSLogging module which you can download from Powershell Gallery >>> https://www.powershellgallery.com/packages/PSLogging/2.5.2.

There is also more info here >>> https://9to5it.com/powershell-logging-v2-easily-create-log-files/

Why not getting the scriptname automatically?

$scriptName = $MyInvocation.MyCommand.Name
$sLogName = "$scriptName.log"