{"id":17366,"date":"2019-02-22T08:09:08","date_gmt":"2019-02-22T16:09:08","guid":{"rendered":"http:\/\/devblogs.microsoft.com\/powershell\/?p=17366"},"modified":"2022-02-23T09:30:13","modified_gmt":"2022-02-23T17:30:13","slug":"cmdlets-via-autorest","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/cmdlets-via-autorest\/","title":{"rendered":"Generating PowerShell Cmdlets from OpenAPI\/Swagger with AutoRest"},"content":{"rendered":"<p>Today, we&#8217;re announcing beta support for PowerShell in\u00a0<a href=\"https:\/\/aka.ms\/autorest\" rel=\"nofollow\">AutoRest<\/a>, so that you can now generate PowerShell modules from Swagger\/OpenAPI JSON documents.<\/p>\n<blockquote>\n<p style=\"padding-left: 30px;\"><a href=\"http:\/\/github.com\/Azure\/autorest\">AutoRest<\/a>\u00a0is the SDK generation tool that we use in Azure to produce SDKS for 90+ management services across 7+ languages.\nIts 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\u00a0<a href=\"https:\/\/www.npmjs.com\/package\/vscode-jsonrpc\" rel=\"nofollow\">JSON-RPC<\/a>\u00a0protocol that\u00a0<a href=\"https:\/\/code.visualstudio.com\/\" rel=\"nofollow\">Visual Studio Code uses<\/a>\u00a0)<\/p>\n<\/blockquote>\n<p>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.)<\/p>\n<h3><a id=\"user-content-getting-started\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#getting-started\"><\/a>Getting Started<\/h3>\n<h4><a id=\"user-content-requirements\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#requirements\"><\/a>Requirements<\/h4>\n<p>Use of the beta version of\u00a0<code>autorest.powershell<\/code>\u00a0requires the following:<\/p>\n<ul>\n<li><a href=\"https:\/\/nodejs.org\/\" rel=\"nofollow\">Node.js LTS<\/a>\u00a0(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. )<\/li>\n<\/ul>\n<blockquote><p>If you want an easy way to install and update Node, I recommend\u00a0<a href=\"https:\/\/github.com\/Azure\/autorest\/blob\/main\/docs\/install\/installing-via-nvs.md\">NVS &#8211; Node Version Switcher<\/a>\u00a0or\u00a0<a href=\"https:\/\/github.com\/Azure\/autorest\/blob\/main\/docs\/install\/installing-via-nvm.md\">NVM &#8211; Node Version Manager<\/a><\/p><\/blockquote>\n<ul>\n<li><a href=\"https:\/\/aka.ms\/autorest\" rel=\"nofollow\">AutoRest<\/a>\u00a0v3 beta:\n<code>npm install -g autorest@beta\n<\/code><\/li>\n<li><a href=\"https:\/\/aka.ms\/pscore6\">PowerShell 6.1 or greater<\/a><\/li>\n<li><a href=\"https:\/\/dotnet.microsoft.com\/download\">.NET Core SDK 2 or greater<\/a><\/li>\n<\/ul>\n<h4><a id=\"user-content-using-autorest-powershell\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#using-autorest-powershell\"><\/a>Using AutoRest Powershell<\/h4>\n<p>At a bare minimum, you can generate a PowerShell module using a Swagger or OpenAPI file and using\u00a0<code>--powershell<\/code>.<\/p>\n<p>The output will be in the\u00a0<code>.\/generated<\/code>\u00a0folder by default:<\/p>\n<p><code>autorest --powershell --input-file:&lt;path-to-swagger-file&gt; [...options]<\/code><\/p>\n<p>Be sure to check out\u00a0<a href=\"https:\/\/github.com\/Azure\/autorest\/blob\/master\/docs\/powershell\/samples\/readme.md\">these additional samples that use the PowerShell generator<\/a>.<\/p>\n<h3><a id=\"user-content-features\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#features\"><\/a>Features<\/h3>\n<h4><a id=\"user-content-modules-work-on-both-windows-powershell-and-powershell\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#modules-work-on-both-windows-powershell-and-powershell\"><\/a>Modules work on both Windows PowerShell and PowerShell<\/h4>\n<p>Due to the use of\u00a0<code>netstandard2.0<\/code>\u00a0and\u00a0<code>PowerShellStandard.Library<\/code>, once compiled, the cmdlets work on both Windows PowerShell 5.1 and PowerShell 6.x. <em>PowerShell 6.x is required during development.<\/em><\/p>\n<h4><a id=\"user-content-generates-modules-from-openapi-files-without-any-external-dependencies\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#generates-modules-from-openapi-files-without-any-external-dependencies\"><\/a>Generates modules from OpenAPI files without any external dependencies<\/h4>\n<p>Most language SDKs generated with AutoRest required the use of at least a &#8216;client runtime&#8217; package, and often pulls in a few other libraries (ie,\u00a0<code>JSON.NET<\/code>) that are required to compile the output of the generator.<\/p>\n<p>The new PowerShell generator creates modules that require\u00a0<em>no dependencies<\/em>\u00a0outside of\u00a0<code>netstandard2.0<\/code>\u00a0and the\u00a0<code>PowerShellStandard.Library<\/code>\u00a0which drastically reduces the chances of having assembly loading conflicts.<\/p>\n<h4><a id=\"user-content-cmdlets-have-no-weird-base-classes-or-force-hierarchy\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#cmdlets-have-no-weird-base-classes-or-force-hierarchy\"><\/a>Cmdlets have no weird base-classes or force hierarchy<\/h4>\n<p>All the generated cmdlets inherit\u00a0<code>PSCmdlet<\/code>\u00a0and are fairly straightforward. For ARM resources, we already support generating\u00a0<code>-AsJob<\/code>\u00a0support for long-running-operations, and this can be expanded in the future to support more patterns.<\/p>\n<h4><a id=\"user-content-an-incredible-number-of-extensibility-points\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#an-incredible-number-of-extensibility-points\"><\/a>An incredible number of extensibility points<\/h4>\n<p>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&#8217;ll be posting some documentation on how to do that in the near future.<\/p>\n<h4><a id=\"user-content-many-variants-of-cmdlets-are-created-to-offer-several-parametersets\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#many-variants-of-cmdlets-are-created-to-offer-several-parametersets\"><\/a>Many variants of cmdlets are created to offer several\u00a0<code>ParameterSets<\/code><\/h4>\n<p>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\u00a0<code>.ps1<\/code>scripts or C# classes.<\/p>\n<h4><a id=\"user-content-no-reflection-for-serialization\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#no-reflection-for-serialization\"><\/a>No reflection for serialization<\/h4>\n<p>The generated module has custom-created JSON serialization <em>(using an embedded copy of\u00a0<a href=\"https:\/\/github.com\/carbon\/Data\/tree\/master\/Carbon.Json\">Carbon.JSON<\/a>)<\/em> This significantly improves serialization performance.<\/p>\n<h3><a id=\"user-content-faqs\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#faqs\"><\/a>FAQs<\/h3>\n<h4><a id=\"user-content-what-happened-to-psswagger\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#what-happened-to-psswagger\"><\/a>What happened to &#8216;PSSwagger&#8217;?<\/h4>\n<p>In order to get to the point where we can generate the\u00a0<a href=\"https:\/\/azure.microsoft.com\/en-us\/blog\/azure-powershell-az-module-version-1\/\" rel=\"nofollow\">Az<\/a>\u00a0modules 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&#8217;ve discontinued work on PSSwagger.<\/p>\n<h4><a id=\"user-content-source-code\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#source-code\"><\/a>Source code?<\/h4>\n<p><a href=\"https:\/\/github.com\/azure\/autorest.powershell\">Of course<\/a>! You probably should get started with the by reading\u00a0<a href=\"https:\/\/github.com\/Azure\/autorest\/tree\/main\/docs\/developer\">the developer documentation.<\/a><\/p>\n<h4><a id=\"user-content-are-there-any-powershell-specific-generation-options\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#are-there-any-powershell-specific-generation-options\"><\/a>Are there any PowerShell specific generation options?<\/h4>\n<p>Yes! You can modify the entire output folder layout, and tweak the way it generates cmdlets, including cmdlet names, parameters, etc. (Check out\u00a0<a href=\"https:\/\/github.com\/Azure\/autorest.powershell\/blob\/main\/docs\/options.md\">our additional documentation on these options<\/a>). If you have feedback about these code generation options, feel free to post an issue on the\u00a0<a href=\"https:\/\/github.com\/Azure\/autorest\/issues\">AutoRest GitHub repo<\/a>.<\/p>\n<h3><a id=\"user-content-known-issues\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#known-issues\"><\/a>Known Issues<\/h3>\n<p>As with all\u00a0<code>beta<\/code>\u00a0software, there are bound to be a few glitches or things that are not working.<\/p>\n<p>We&#8217;ve cataloged some\u00a0<a href=\"https:\/\/github.com\/Azure\/autorest.powershell\/blob\/main\/docs\/release-notes.md#caveats-and-known-issues\">known issues<\/a>\u00a0with this first beta we encourage you to read before reporting any issues you experience.<\/p>\n<h3><a id=\"user-content-support\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#support\"><\/a>Support<\/h3>\n<p>We&#8217;re working as fast as we can to finish up the generator, as we have a lot of modules to generate internally.<\/p>\n<p>I should also have deeper design documentation over the next month or two, explaining a bit more of the <em>&#8220;why-does-it-work-this-way?&#8221;\u00a0<\/em>category.<\/p>\n<p>General feedback can be left in the <a href=\"https:\/\/github.com\/Azure\/autorest\/issues\/3140\">PowerShell Generator thread<\/a> in the github repo.<\/p>\n<p>If you run into problems, feel free to post an issue on the\u00a0<a href=\"https:\/\/github.com\/Azure\/autorest\/issues\">github repo<\/a>\u00a0and tag it with the\u00a0<code>powershell<\/code>\u00a0label, and we&#8217;ll try to take a look.<\/p>\n<h2><a id=\"user-content-quick-links\" class=\"anchor\" href=\"https:\/\/github.com\/Azure\/autorest\/blob\/announcements\/docs\/posts\/announcing-powershell-generator.md#quick-links\"><\/a>Quick Links<\/h2>\n<ul>\n<li><a href=\"https:\/\/github.com\/Azure\/autorest\">AutoRest GitHub repository<\/a><\/li>\n<li><a href=\"https:\/\/github.com\/Azure\/autorest.powershell\/tree\/main\/docs\">Additional documentation<\/a>\u00a0will be added as we get it written.<\/li>\n<li><a href=\"https:\/\/github.com\/Azure\/autorest.powershell\/blob\/main\/docs\/development.md\">Developer documentation<\/a>\u00a0for the PowerShell generator.<a href=\"https:\/\/github.com\/Azure\/autorest\/raw\/master\/docs\/images\/logo.png\" target=\"_blank\" rel=\"noopener noreferrer\"><img decoding=\"async\" class=\"aligncenter\" src=\"https:\/\/github.com\/Azure\/autorest\/raw\/master\/docs\/images\/logo.png\" align=\"center\" \/><\/a><\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>Announcing the availability of the beta version of our new PowerShell cmdlet generator for AutoRest.<\/p>\n","protected":false},"author":277,"featured_media":13641,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[746,748,747],"class_list":["post-17366","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","tag-autorest","tag-cmdlet-generator","tag-rest"],"acf":[],"blog_post_summary":"<p>Announcing the availability of the beta version of our new PowerShell cmdlet generator for AutoRest.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/17366","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/users\/277"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/comments?post=17366"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/17366\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media\/13641"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media?parent=17366"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/categories?post=17366"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/tags?post=17366"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}