Creating / Troubleshooting Runbooks

Developing locally

You can develop and debug an Azure automation runbook locally using Visual Studio Code, for example. To customize or troubleshoot the runbooks provided in this guide, change the Authentication section of the PowerShell script to authorise your own user account instead of as a managed identity or runas account. This assumes that your user account has at least the same permissions that you have granted to the managed identity of your automation account.

In the Authentication section of the script, simply replace the existing code with the following as an example. Make sure the accessToken variable is set to the script scope so it can be used within the functions.

####################
## AUTHENTICATION ##
####################
# To authenticate with Microsoft Graph:
# Install-Module Microsoft.Graph.Intune -Force
$script:accessToken = Connect-MSGraph -PassThru
# If you need to access the Azure storage account:
# Install-Module Az.Accounts -Force
# Install-Module Az.Storage -Force
$null = Connect-AzAccount # Optional: -Subscription "<my-subscription>" -Tenant "<my-tenant-id>"

Once you have developed or finished debugging your script, simply change the Authentication section back to the original code and update the runbook in the automation account.

Logging output

While you are developing or testing your script locally, you can use, for example, Write-Host, Write-Output, Write-Warning, Write-Verbose to return output to the PowerShell host.

When executing the runbook, however, you can't use Write-Host. You can use Write-Output but the recommended way is to use Write-Verbose and set the $VerbosePreference variable to Continue so that the output will display.

Bear in mind that using Write-Output inside a function that returns to a variable will send the output to that variable and not to the output stream.

More details on using output in a runbook and general troubleshooting advice can be found in the articles below.

Runbook Output and MessagesMicrosoftLearn

Troubleshoot Azure Automation runbook issuesMicrosoftLearn