Using a customer application event log to debug a Powershell Script

  • Article

Often, when I am debugging a developer’s PowerShell script, the only symptom I get is that the script is not working. In general, it is fairly easy to debug a small script even when you have little information but when given complex script, it can be difficult to navigate your way around especially when you are not familiar with its design.

As part of troubleshooting, I would ask for the last successful call or command that was executed, however, in most cases, this information is unavailable as they are executed from a task scheduler where there aren't any user interaction. What would help is if you have a trail that you can follow to identify the first point of failure. This is where I would recommend the developer to add a form of instrumentation to document the status of the code at different points during the script's execution. One of such method is to write information to the Application Event log.

In order to write to the event log, one can use the Write-EventLog cmdlet but there are mandatory parameters needed to write the event log information. These are:

  • LogName
  • Source
  • EventID
  • Message

If you want to create an entry log message “Format was called” into the Application Log and store this into your custom source “MyScript” with a custom event ID like “3001”, you will need to type it as:

   1: Write-EventLog -LogName Application -Source MyScript -EventId 3001 -Message "Format was called"

   2:

If you have not registered your custom event source, you will encounter an error like below:

 PS C:\windows\system32> Write-EventLog -LogName Application -Source MyScript -EventId 3001 -Message "Format was called"

 Write-EventLog : The source name "MyScript" does not exist on computer "localhost".

 At line:1 char:15

 + Write-EventLog <;<<<  -LogName Application -Source MyScript -EventId 3001 -Message "Format was called"

     + CategoryInfo          : InvalidOperation: (:) [Write-EventLog], InvalidOperationException

     + FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteEventLogCommand

In order to register a custom event source, you will need to call the New-EventLog cmdlet like the example below:

   1: New-EventLog -LogName Application -Source MyScript

   2:

It is only necessary to call New-EventLog once to register the new event source for the target machine where the event logs will be written. Once the event source is registered, you do not have to call this cmdlet again.

You can then sprinkle the Write-EventLog cmdlets throughout your script like so:

   1: .\Format.ps1

   2: Write-EventLog -LogName Application -Source MyScript -EventId 3001 -Message "Format was called"

   3: .\Register.ps1

   4: Write-EventLog -LogName Application -Source MyScript -EventId 3001 -Message "Register was called"

   5:

Now, when you review your custom event logs, you can easily check and compare them against your script to determine the last successful command that executed. It will help you narrow down where to focus your efforts and hopefully get you closer to solving the problem.