Recently the Beta of the AutoRest for PowerShell Generator has been made available. At the recent Microsoft MVP Summit in Seattle Garrett Serack gave those that were interested a 1 hr corridor session on getting started with AutoRest for PowerShell.
AutoRest is a tool that generates client libraries for accessing RESTful web services. Microsoft are moving towards using AutoRest to generate SDK’s for the API’s in the standard languages they provide SDK’s for. In addition the AutoRest for PowerShell generator aims to automate the generation of PowerShell Modules for Azure API’s.
In this post I’ll give an intro to getting started with AutoRest to generate PowerShell modules using an AutoRest example and then an Azure Function based API.
AutoRest for PowerShell Prerequisites
AutoRest is designed to be cross-platform. As such its dependencies are NodeJS, PowerShell Core and Dotnet Core.
- NodeJS LTS 10.15+
- PowerShell Core 6.1+
- download from the link above or once you have Node installed
- npm install -g pwsh
- download from the link above or once you have Node installed
- Dotnet Core 2.1+
- download from the link above or once you have Node installed
- npm install -g dotnet-sdk-2.1
- download from the link above or once you have Node installed
AutoRest for PowerShell Installation
Installation is done via command line once you have NodeJS installed and configured
npm install -g autorest@beta
if you have previously installed AutoRest you will want to update to the latest version as updates and fixes are coming regularly
autorest --reset
Building your first AutoRest for PowerShell Module
The AutoRest documentation has a couple of examples that are worth using initially to get to know the process and the expected output from AutoRest.
From a PowerShell Core command prompt (type pwsh in a command window) make the following Invoke-WebRequest (IWR) to retrieve the XKCD Swagger/OpenAPI file. I pre-created a sub-directory named XKCD under the directory where I ran the following command.
iwr https://raw.githubusercontent.com/Azure/autorest/master/docs/powershell/samples/xkcd/xkcd.yaml -outfile ./xkcd/xkcd.yaml
We can now start the process to generate the PowerShell module. Change directory to the directory where you put the xkcd.yaml file and run the following command.
autorest --powershell --input-file:./xkcd.yaml
Following a successful run a generated folder will be created. We can now build the PowerShell Module. We can add the -test flag so that at the end of Generating the Module, Pester will be used to test it. First run PowerShell Core pwsh then build-module
pwsh ./generated/build-module.ps1 -test
With the module built and the tests passed we can run it. We need to load the module and look to see the cmdlets that have been built for the API.
.\generated\run-module.ps1 xkcd.psm1 get-command -module xkcd
Using the Get-ComicForToday cmdlet we can query the XKCD API and get the Comic of the Day.
Get-XkcdComicForToday | fl
Taking it one step further we can download the comic of the day and open it, with this PowerShell one-liner.
invoke-webrequest (Get-XkcdComicForToday).img -outfile image.png ; & ./image.png
Let’s Create a Simple API – BOFH Excuse Generator
I created an HTTP Trigger based PowerShell API Function that takes GET requests and returns a BOFH – Bastard Operator from Hell (warning link has audio) style excuse. For those that haven’t been in the industry for 20+ years or aren’t familiar with the Bastard Operator from Hell, it is essentially a set of (semi) fictional transcripts of user interactions from a Service Desk Operator (from Hells’) perspective set in a University environment. Part the schtick is an Excuse of the Day. My API when queried returns a semi plausible Excuse of the Day.
Here is my HTTP Trigger PowerShell Azure Function (v1). A simple random excuse generator.
I configured the function for anonymous, GET operations only and the route to be excuse
Testing the Function from my local machine showed it was working and returning an excuse.
Now it’s time to generate the OpenAPI Spec. Select the Azure Function App => Platform Features => API definition
Select Generate API definition template and the basics of the OpenAPI spec for the new API will be generated. I then updated it with the output application/json and what the API returns as shown in the highlighted sections below. Select Save 
Now we can test it out and we see that we have success.
Taking the OpenAPI Spec (YAML format file) for our BOFH Excuse API we go through the steps to successfully generate the PowerShell Module using AutoRest. Running the freshly baked cmdlet from the BOFH PowerShell Module returns a BOFH Excuse. Awesome.
Summary
Using AutoRest it is possible to generate PowerShell Modules for our API’s. Key to the successful generation is the definition of the OpenAPI Spec for our API. In my example above, obviously if you don’t define what the API call returns then the resulting cmdlet will query the API, but won’t return the result.