function Write-Log {
    param(
        [string]$Message,
        [string]$EntryType = "Info",
        [string]$ObjectContext,
        [string]$CodeContext,
        [string]$Details,
        $LogName = "output.log",
        $LogPath
    )
    try {
        if ([string]::IsNullOrEmpty($LogPath)) {
            $LogPath = $pwd.path
        }
        if (!(Test-Path $LogPath\$LogName -ErrorAction SilentlyContinue)) {
            "Timestamp,EntryType,Message,ObjectContext,CodeContext,Details" | Out-File -FilePath $LogPath\$LogName
        }
        foreach ($paramInfo in $MyInvocation.BoundParameters.Keys) {
            #If parameter passed in contains a comma, wrap the entry in quotes to not break CSV delimiters.
            $parameterData = $MyInvocation.BoundParameters[$paramInfo].ToString()
            if ($parameterData.Contains(",")) {
                Set-Variable "$paramInfo" -Value $parameterData.Replace(
                    "$parameterData","`"$parameterData`"")
            }
        }
        "$([DateTime]::Now.ToString("MM-dd HH:mm:ss")),$EntryType,$Message,$ObjectContext,$CodeContext,$Details".Replace("\n",";") | `
            Out-File -Append -FilePath "$LogPath\$LogName"
    }
    catch {
        Write-Warning "Unexpected error occured while executing $((Get-PSCallStack)[0].Command) with exception: $($_.Exception)"
        Write-Warning "Command: `'$($_.InvocationInfo.Line.Trim())`'"
    }
}

Write-Warning "Unexpected error occurred while executing $((Get-PSCallStack)[0].Command) with exception: $($_.Exception.Message)"

Write-Warning "Command: `'$($_.InvocationInfo.Line.Trim())`'"

I’ll usually have some error handling for specific conditions such as unexpected object state/data which usually results in a return from the function, so if we actually hit a catch block, something is REALLY not right.  If you have a script with several hundred lines, a dozen functions and you suddenly hit an unexpected error, it can be tedious to figure out where the error actually came from.  In the past, I’ve gone back to my scripts, added a bunch of ‘Write-Host “Just passed this section of code”’ or similar debug lines.  I very rarely have to perform this level of debugging with my current catch block reporting.

Let’s break down what is happening here and take a look at some sample output.  Get-PSCallStack was designed to be used with the PowerShell debugger. It works inside scripts and functions.  Here we are looking at the first item in the call stack, getting the command and displaying the exception message.  This is the function name, or script name if you’re not in a function.  The second line takes a look at the InvocationInfo property of our exception. The InvocationInfo has a property called Line which contains the text from the line of the script or function that generated the error. Another option in this scenario instead of collecting the Line property is to collect the MyCommand.Name property which will return the cmdlet that generated the error. Given the context of the caller and the line or name of the cmdlet, it will be easier to determine where the error is occurring.

Seen below, we have some sample information from a function called Get-FileInformation, which is throwing an error when calling the Test-Path cmdlet with a null value.

In the output, we have a lot more information about what caused the error, and where we should start looking for the problem.

I want to know which color you want to make your background.  Let’s say my script respects only red, green and blue.  You could have some code looking similar to the following:

$userColor = read-host “Enter the color (red, green or blue)”

if ($userColor –eq “red”) {

}

if ($userColor –eq “green”) {

}…etc

Another option would be:

if ($userColor –match “red|green|blue”) {

$Background.Color = $userColor

}

else {

#error or pick default color

}

In either scenario, if the user provides bad input you can either default to some color or you would be forced to set up a loop to prompt the user again.  When I wrote this function, my goal was to remove a bit of the headache for the script author on which code path could possibly taken depending on who is running the console.

Here is the function, and example for our background color scenario:

function Confirm-UserInput {
    param(
        $Message = "Enter one of the following choices.",
        [string[]]$Choices = @("&Yes","&No","&Cancel")
    )
    $ListChoices = @()
    foreach ($Choice in $Choices) {
        $ListChoices += [System.Management.Automation.Host.ChoiceDescription]$Choice
    }
    return $Choices[$Host.UI.PromptForChoice(`
        "Confirm",$Message,$ListChoices,0)].Replace("&","")
}

$Background.Color = (Confirm-UserInput –Message “Choose a valid color.” –Choices “&Blue”,”&Green”,”&Red”)

Once this command executes, I know I can immediately assign the return to the Color property, as the return has to be one of the choices I defined.

$ConfirmPrompt = Read-Host "Are you sure you want to SHUT DOWN the above servers in the listed site(s)?  Type 'Yes' to continue"

if ($ConfirmPrompt -ne 'Yes') {
    Write-Warning "Confirm failed.  Script will quit."
    Exit
}

Obviously in this case the administrator has to explicitly type “Yes” in the prompt or the script will exit.  This is not very reliable.  What happens if the user wants to type in “Y” or does not spell the keyword properly?  The script would exit and the user would have to re-run the entire script because of a mistake.  In the first part of this two part post, I want to show a function I wrote to approve a yes/no command like this one.  To me, it feels a bit more ‘native PowerShell’, without having to build your own loop.

Function Approve-Action {
    param(
        $Message = "Are you sure you want to perform this action?"
    )
    [string[]]$Choices = @("&Yes","&No")
    $ListChoices = @()
    foreach ($Choice in $Choices) {
        $ListChoices += [System.Management.Automation.Host.ChoiceDescription]$Choice
    }
    $Results = $Host.ui.PromptForChoice("Confirm", $Message, $ListChoices, 0)
    return ($Choices[$Results] -match "Yes")
}

This function uses PowerShell’s built-in PromptForChoice method, which has it’s own input validation mechanism.  If the user types “Cancel” – the validation realizes this is not a valid option and will prompt the user again until a valid option is selected.  Worth mentioning is the “&” at the beginning of each choice input will allow the user to type the following letter to select that choice:

The implementation is simple:

if (Approve-Action “OK to reboot this computer?”) {
    Restart-Computer
}

In part 2, I will cover a different implementation showing custom choices instead of a simple yes/no.

-You must specify a source and a log (Application, System, etc) to write to.  An example of a source would be “Windows Error Reporting” in the Application log.

- A source can only be associated with one event log.  If you attempt to write an event using the source “Windows Error Reporting” to the System log, you will get the following error: The source 'Windows Error Reporting' is not registered in log 'System'. (It is registered in log 'Application'.)

Since the Write-EventLog cmdlet makes you specify the log to write to with the mandatory –LogName parameter, this can be problematic because you have to know which log the source is associated with.  From a programmatic perspective, you can’t guarantee all computers everywhere have the source “AutomationLogs” registered, and you also can’t guarantee which event log this is registered to.

I developed the following function to assist me in writing to the event logs that I plan to implement in a lot of my scripts moving forward.  I wanted to be able to call a command and specify what I want to write and not have to worry about sources, log locations, registering new event logs if needed, and so on.

The function first checks to see if the source is already registered with an existing log.  If the source exists, the function leverages the static method LogNameFromSourceName from the System.Diagnostics.EventLog class to determine which log to write to.  If the return from this function is null or an empty string, we know the source does not exist and will have to register a new event source to the desired log (as passed in by the caller). 

This function requires administrative access in an elevated command prompt, because it needs to check the Security log, and this access is also required when registering new sources.

According to the MSDN documentation regarding creation of event sources – after registering a new event source, it should not be immediately used.  I am not sure exactly how long we should wait but I assumed 5 seconds is ample time for whatever replication/post-processing tasks need to happen on the back end before we use this.

I have tested this on Server 2012 and 2012 R2, but any machine with PowerShell 3 or later should be able to leverage the function.  The function is below and can also be found on the TechNet Script Gallery here.

function Log-Event {
    param(
        [Parameter(Mandatory=$true)]
        [ValidateNotNullorEmpty()]
        [String]$Message,

        [ValidateNotNullorEmpty()]
        [String]$Source = "ScriptOutput",

        [int32]$EventID = 1,

        $LogName = "Application",

        [System.Diagnostics.EventLogEntryType]$Type = "Information"
    )
    try {
        $SourceLogName = [System.Diagnostics.EventLog]::LogNameFromSourceName($source, ".")
        if (![string]::IsNullOrEmpty($SourceLogName)) {
            Write-EventLog -LogName $SourceLogName -Source $Source -Message $Message -EntryType $Type -EventId $EventID
        }
        else {
            New-EventLog -Source $Source -LogName $LogName
            #After register new event source, do not use right away, accoring to MSDN:
            #http://msdn.microsoft.com/en-us/library/2awhba7a(v=vs.110).aspx
            Sleep 5
            Write-EventLog -LogName $LogName -Source $Source -Message $Message -EntryType $Type -EventId $EventID
        }
    }
    catch {
        Write-Warning "Unexpected error occured while attempting to write to log."
        Write-Warning "Caller command: $((Get-PSCallStack)[1].Command)"
        Write-Warning "Error: $($_.exception.message)"
    }
}

The script will identify servers by site and optionally by server name as well.  The script leverages WinRM to stop services remotely on multiple servers, so WinRM must be enabled and firewall rules must be opened.  The advantage is this can be executed on any number of servers and should take generally around the same time to complete.

After the script identifies which servers need to be shut down, it will dismount any databases that are mounted and stop the cluster service on DAG nodes, as well as stopping the msExchangeADTopology service (and dependent services).  Once all services are stopped, the script will initiate a shutdown of each server.

Here is the script in action:

As a reminder, all servers will need to be manually powered back on; in addition, all databases that were dismounted will need to be mounted after the servers are brought back online.

*Edit* - The script can be found here.

Since the Export-Clixml cmdlet retains the data type in the XML file, we can perform actions on the objects in memory that are type-specific without having to cast the objects.  This means if we have an integer value, we can increment the count by calling the ++ operator.  Likewise, if we have a DateTime object, we can call type-specific methods such as .ToUniversalTime().  I think this is very cool and I wish I’d discovered this sooner. 

Loading the XML back into memory couldn’t be easier:

$DBCache = Import-Clixml C:\DatabaseCache.xml

Using the data created in part 1, let’s assume we just created a new mailbox on Database-1.  With the below code, we can easily take the objects in memory and increment the count to show the new updated mailbox number.  Another example would be adding time to the Timestamp attribute before we save .

($DBCache | where {$_.DatabaseName –eq “Database-1”}).UserCount++

foreach ($DBItem in $DBCache) { $DBItem.Timestamp.AddHours(3) }

Once the objects are modified, simply overwrite the XML file with the updated data:

$DBCache | Export-Clixml “C:\DatabaseCache.xml”

I realize this is a very simple example but the principal applies to any class and any of those class methods.

So let’s take a look at something LDAP we could cache.  Let’s say I have an array of objects in memory representing Exchange databases with current number of mailboxes (I like to query LDAP for this data - see this post).  The objects could be anything – but the concept is straightforward as we will cache the data to disk using XML.  For this example, let’s create some fake data with custom PSObjects.  I chose to use different types (string, int, datetime) on purpose here to show how this really shines compared to using something like export/import –csv, which only recognizes strings without doing type casting or conversion.

$DBs = @()
$DBs += New-Object psobject -Property @{DatabaseName="Database-1"; UserCount = 3800; Timestamp=(Get-Date)}
$DBs += New-Object psobject -Property @{DatabaseName="Database-2"; UserCount = 2600; Timestamp=(Get-Date)}

Once the array of custom objects is created, we can simply export it using the built in Export-Clixml cmdlet.

$DBs | Export-Clixml .\DatabaseCache.xml

This will save all of our data to an XML file and retain associated type information, etc.  Here is what the raw XML data looks like.

To use this data again, simply use the Import-Clixml cmdlet and you will have the exact same array of objects you previously exported.  Stay tuned as my next post will show some examples of how to update the cache.

This month’s post will be a short one – and there’s not much code to this topic, it’s just an observation.  When I write scripts, I like the idea of adding some output to track what my script is doing, especially if there’s an issue with the script.  It’s so much easier to find bugs or performance issues if I can see the last task that completed successfully – I then know where to start looking for the issue in my code.  However, it is important to understand as more output is added, your script will slow down.  It may not seem like much but when you are calling write-host multiple times for thousands of objects, overall script performance will be impacted.

Let’s take an example script I wrote and assume the script will call a function in a foreach loop processing thousands of objects.  I’ll also add a write-host in my foreach loop each time I enter and exit a function.  That’s a lot of text but it could be meaningful if there is an issue.  Let’s run the following code:

function foo {
    Write-Host "Entering function 'foo'"
    # Some code
    Write-Host "Completed function 'foo'"
}

$startTime = Get-Date
write-host "script started at $starttime"
$Cycles = 10000

1..$Cycles | % {
    foo
}
Write-Host "Done"

$endTime = Get-Date
($endTime - $startTime).totalseconds

This takes about 10 seconds to execute on my computer, which is significant since the only thing running is the write-host command.  After commenting out the write-host commands, the script completes in about 1 second.  In my personal experience, I have seen scripts where over 30 minutes have been saved by removing write-host output.

My suggestion and what I do for most of my scripts: as an alternative to write-host, you can use write-verbose for output, and when you need to see what your script is doing you can call the script with the –verbose parameter.  Your script will execute faster under normal circumstances, and you will still be able to output diagnostic information when you need it - with no code changes.

When I set out to write this, I wanted a function I can just drop into a script if I feel it’s necessary, with minimal code changes.  The function I came up with makes the following assumptions:

• Each processing task takes relatively the same amount of time to execute
• You must know how many items you are processing.  I’m not sure mathematically how to solve this without knowing both how many items we have looped through and how many more we have left to process
• If one or several of the processing tasks takes significantly longer than the other processing tasks (such as a network timeout), the estimated time remaining will be skewed

After adding the function I created to a script, all I need to add is this code to my foreach loop (where $cycles is an integer representing the total objects to process):

$i++
ShowExecutionTime -TotalObjectsToProcess $Cycles

Here is the script in action:

The script in the repository also has a –ShowCalculatedTimes parameter which will document each time the function estimates the script completion time, then will display how many times we guessed each specific completion time.  Below are the results of the script with –ShowCalculatedTimes enabled:

The sample script containing the function can be found here.