​Update 1/8/2016: Azure Automation now supports native PowerShell runbooks, so the Script Converter is no longer used to convert your PowerShell scripts into PowerShell Workflows. Your PowerShell scripts can now be run as is, as runbooks in Azure Automation. See this blog post for more details.

By now you’ve probably learned about the new Azure Automation service, which recently became generally available. You’ve learned how you can use Azure Automation to automate all your management processes, take advantage of runbooks in the community gallery, and attain reliable execution in the face of failures using checkpoints. But what you may not have heard about is one of our new features we recently enabled – the Azure Automation script converter. While using Azure Automation, you may have noticed that it doesn’t actually execute PowerShell script, but instead executes PowerShell Workflow. There’s a lot of benefits to PowerShell Workflow – in addition to allowing you to leverage the semantics, modules, knowledge, content, and community around PowerShell, it also give you access to the power of Windows Workflow Foundation. That means you get the ability to checkpoint, suspend, and resume your runbooks to better handle logic, environment, or network failures, as well as the ability to easily execute things in parallel or serially. But, like with most things in life, you don’t get the good without the bad! While PowerShell Workflow is very similar to regular PowerShell, it does have some differences and limitations when compared to pure PowerShell, to allow for some of the additional features it adds. Of course, all of these can be overcome with a little education and practice – but wouldn’t it be nice if we could just take things we’ve already written as PowerShell scripts, or that we’ve grabbed from the PowerShell community, and just import them as is into Azure Automation?  

Using the Script Converter

Now you can do just that! Until recently, if you imported a PowerShell script into Azure Automation that contained anything other than a single PowerShell Workflow, the import would fail. Now, if you import a PowerShell script with no PowerShell Workflows in it, not only will import succeed, but we’ll attempt to convert the PowerShell script for you to PowerShell Workflow, so it will be able to run with little to no manual changes as an Azure Automation runbook. This lets you leverage the vast amount of content around PowerShell script out there today, as well as any existing PowerShell scripts you’ve already written, as is in Azure Automation! Let’s try it out. Here’s a little script I threw together to stop all my small-sized Azure VMs. I wrote it as a PowerShell script in the PowerShell ISE:   Even though this is a valid PowerShell script that works in the ISE, if I were to take this as is, and copy and paste it into a (PowerShell Workflow) runbook in Azure Automation, it won’t work, because I am relying on positional parameters in my script (specifically, the –FilterScript parameter of Where-Object), and positional parameters do not work in PowerShell Workflow:   Of course, I know this, so I could go and update the runbook to make the proper conversions to move this PowerShell script to be valid PowerShell Workflow (in this case, all I need to do is add the “-FilterScript” parameter name before Where-Object’s script block parameter value), but let’s pretend I don’t want to make the changes and just want to get the thing working. I can now just import this PowerShell script (rather than copy / pasting it in), and it will be converted for me:     Voilà! The Azure Automation script converter has converted my PowerShell script into a valid PowerShell Workflow that can run successfully and stop all my small VMs:     As you can see from the above screenshot of my Stop-SmallVMs runbook, the converter inserts a comment starting with “Converter:” in every place it makes a change, to let you know what changes were made from the original script. This both enables the script to work as a runbook, and also helps educate on some of the differences between workflow and scripts. In this case, all the converter had to do was wrap the original script (except its parameters) in an InlineScript activity, which runs its contents as PowerShell script instead of PowerShell Workflow, and pass the runbook’s parameters into that InlineScript using the “using:” scope modifier. While InlineScript is able to resolve many issues since it runs its contents as PowerShell script instead of workflow, the script converter also handles some other cases that InlineScript doesn’t cover and weren’t demonstrated above:

• Converting every Write-Host to a Write-Verbose
• Converting every Read-Host to a runbook parameter

  And of course, more cases will be handled over time.  

Runbook Gallery and Script Converter

One other new feature I’d like to call out — you may have noticed that the runbook gallery also recently added support for PowerShell scripts:     The Azure category on ScriptCenter contains many community and Microsoft-contributed PowerShell scripts, not designed for use in Azure Automation, but still meant to help with managing Azure. Now that Azure Automation has support for script conversion, the runbook gallery can show these PowerShell scripts as well, and convert them to PowerShell Workflow so they’ll run as runbooks when you import them!  

A word of caution

I know you’re probably very excited to start using the Azure Automation script converter, but I do want to call out a best practice – if you are going to write your runbooks in the PowerShell ISE, test them there, and then import them into Azure Automation for final testing and production operation, learning PowerShell Workflow and authoring runbooks as PowerShell Workflow is the best method. Copying something that worked as PowerShell script and pasting it into a PowerShell Workflow runbook could cause issues, as shown above, so writing in PowerShell Workflow for your local testing will help you distinguish between issues in your runbook logic, and issues between PowerShell and PowerShell Workflow. If you write something in the ISE and it works there but fails once you paste it into an Azure Automation runbook, make sure you tested that it was working in the ISE as PowerShell Workflow, not PowerShell script. Even if you are going to use the script converter — while we do attempt to do a conversion of PowerShell script to PowerShell Workflow that most of the time should work, it’s still possible we are not able to fully convert your script into something that will run perfectly in PowerShell Workflow. In addition, because the script converter wraps the original script in an InlineScript, which runs as PowerShell script rather than workflow, it also removes the ability to use workflow features in your converted runbooks, like parallel execution and checkpoints. Given these two reasons, our recommendation is that the script converter should be used to help get you started writing runbooks and using Azure Automation, and to bring existing PowerShell scripts you’ve already written into Azure Automation. But if you intend to use Automation for production-level work, learning and writing your runbooks in PowerShell Workflow, whether in the ISE or the Azure Automation authoring experience, will give you the best results. Until next time – keep calm and automate on.   Just getting started with Azure Automation?  Learn about the service here, and follow Azure Automation on Twitter. Want to get in contact with me, personally? Reach out via my blog or follow me on Twitter.