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.)
Getting Started
Requirements
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. )
If you want an easy way to install and update Node, I recommend NVS – Node Version Switcher or NVM – Node Version Manager
- AutoRest v3 beta:
npm install -g autorest@beta - PowerShell 6.1 or greater
- .NET Core SDK 2 or greater
Using AutoRest Powershell
At a bare minimum, you can generate a PowerShell module using a Swagger or OpenAPI file and using --powershell.
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.
Features
Modules work on both Windows PowerShell and PowerShell
Due to the use of netstandard2.0 and PowerShellStandard.Library, once compiled, the cmdlets work on both Windows PowerShell 5.1 and PowerShell 6.x. PowerShell 6.x is required during development.
Generates modules from OpenAPI files without any external dependencies
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.
Cmdlets have no weird base-classes or force hierarchy
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.
An incredible number of extensibility points
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.
Many variants of cmdlets are created to offer several ParameterSets
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.
No reflection for serialization
The generated module has custom-created JSON serialization (using an embedded copy of Carbon.JSON) This significantly improves serialization performance.
FAQs
What happened to ‘PSSwagger’?
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.
Source code?
Of course! You probably should get started with the by reading the developer documentation.
Are there any PowerShell specific generation options?
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.
Known Issues
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.
Support
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.
Quick Links
- AutoRest GitHub repository
- Additional documentation will be added as we get it written.
- Developer documentation for the PowerShell generator.
Light
Dark
0 comments