Generating PowerShell Cmdlets from OpenAPI/Swagger with AutoRest
Today, we’re announcing beta support for PowerShell in AutoRest, so that you can now generate PowerShell modules from Swagger/OpenAPI JSON documents.
AutoRest is the SDK generation tool that we use in Azure to produce SDKS for 90+ management services across 7+ languages.
Its pluggable architecture allows fine-grained control over the generation process, and allows extensions to be written in any language that can read/write JSON via stdin/stdout (we use the JSON-RPC protocol that Visual Studio Code uses )
Along the way, we had to go back and make some updates to the core of AutoRest (to begin support of OpenAPI 3, and introduce some changes to support generating multiple API versions with Azure Profiles.)
Use of the beta version of
autorest.powershell requires the following:
- Node.js LTS (10.15.x LTS preferred. Will not function with a Node version less than 10.x. Be wary of 11.x builds as they may introduce instability or breaking changes. )
At a bare minimum, you can generate a PowerShell module using a Swagger or OpenAPI file and using
The output will be in the
./generated folder by default:
autorest --powershell --input-file:<path-to-swagger-file> [...options]
Be sure to check out these additional samples that use the PowerShell generator.
Due to the use of
PowerShellStandard.Library, once compiled, the cmdlets work on both Windows PowerShell 5.1 and PowerShell 6.x. PowerShell 6.x is required during development.
Most language SDKs generated with AutoRest required the use of at least a ‘client runtime’ package, and often pulls in a few other libraries (ie,
JSON.NET) that are required to compile the output of the generator.
The new PowerShell generator creates modules that require no dependencies outside of
netstandard2.0 and the
PowerShellStandard.Library which drastically reduces the chances of having assembly loading conflicts.
All the generated cmdlets inherit
PSCmdlet and are fairly straightforward. For ARM resources, we already support generating
-AsJob support for long-running-operations, and this can be expanded in the future to support more patterns.
After generation of a module, the developer may wish to augment the module in many ways (custom work when the module loads, changing the HTTP pipeline, adding additional variants of cmdlets, and more). The generated cmdlets offer number of ways to be customized and enhanced, and we’ll be posting some documentation on how to do that in the near future.
Behind-the-scenes, many different flavors of a cmdlet can get created, and these are tied together into a single cmdlet with multiple parameter sets. These can be joined with manually written cmdlets that are written in
.ps1scripts or C# classes.
The generated module has custom-created JSON serialization (using an embedded copy of Carbon.JSON) This significantly improves serialization performance.
In order to get to the point where we can generate the Az modules for all the Azure management services, we needed more control in the fine-grained details of the resulting cmdlets. After consulting with the PowerShell team, the decision was made to integrate more closely with the existing mechanism for generating Azure SDKs (AutoRest) and build a full-featured generator extension to create PowerShell cmdlets. All future work to generate cmdlets be done in the AutoRest PowerShell generator, as we’ve discontinued work on PSSwagger.
Yes! You can modify the entire output folder layout, and tweak the way it generates cmdlets, including cmdlet names, parameters, etc. (Check out our additional documentation on these options). If you have feedback about these code generation options, feel free to post an issue on the AutoRest GitHub repo.
As with all
beta software, there are bound to be a few glitches or things that are not working.
We’ve cataloged some known issues with this first beta we encourage you to read before reporting any issues you experience.
We’re working as fast as we can to finish up the generator, as we have a lot of modules to generate internally.
I should also have deeper design documentation over the next month or two, explaining a bit more of the “why-does-it-work-this-way?” category.
General feedback can be left in the PowerShell Generator thread in the github repo.
If you run into problems, feel free to post an issue on the github repo and tag it with the
powershell label, and we’ll try to take a look.
- AutoRest GitHub repository
- Getting Started with the AutoRest PowerShell Generator
- Additional documentation will be added as we get it written.
- Developer documentation for the PowerShell generator.