Autorest.Az

Warning Autorest.Az is not maintained. Please use aaz-dev-tools for Azure CLI code generation.

---

1. Introduction
2. How does Azure CLI Code Generator Work
  2.1. Different Generation Options
3. How to use Azure CLI Code Generator
  3.1. Preparing Environment
  3.2. Authoring Readme Files
  3.3. Generate Azure CLI Code
  3.4. Build the Generated Code
  3.5. Execute the Generated Azure CLI Commands
    a. Checks
    b. Live Tests
4. Advanced Features
  4.1. Folder Customization
  4.2. CLI User Interface Customization
    a. Add Parent Extension
    b. Customize Extension Description     c. Set Extension/Command Groups/Commands/Parameters Mode
    d. Set min-api/max-api in Command Groups/Commands/Parameters
    e. Move Command Groups/Command Layer
    f. Rename/Hide Command Groups/Commands/Parameters
    g. Client Factory Customization
    h. Parameter Specific Customization
      i. flatten a parameter
      ii. set a parameter as required
      iii. set default value for a parameter
      iv. add alias for a parameter
      v. how an action parameter is handled
      vi. set an action as positional argument
      vii. set an action as AWS shorthand syntax
  4.3. SDK Customization
    a. Flattened SDK and un-Flattened SDK
    b. Track1 SDK and Track2 SDK
  4.4. Manual Override
  4.5. Test Customization
  4.6. Special Parameter Type
  4.7. Incremental Code Generation
5. Contributing
6. Autorest Pipeline Configuration

Introduction

Azure CLI Code Generator provides the feature of Azure CLI module generation in Azure CLI extensions repository and Azure CLI main repository. In this document, we will first introduce how Azure CLI Code Generator works including the basic usage as well as some advanced features. Then, we will describe how to debug the code generator. Finally, we will show the Autorest Pipeline definitions.

Azure CLI Code Generator is mainly for Azure CLI developers and people who are interested in generating Azure CLI by themselves.

How does Azure CLI Code Generator Work

Azure CLI Code Generator is an Autorest extension which generates functional Azure CLI code for Azure services by using Swagger specifications defined in azure-rest-api-specs or azure-rest-api-specs-pr repos. It uses Autorest V3 to handle the configuration interpretation, pipeline resolving, pipeline scheduling and uses Autorest.Modelerfour as a basic code model.

Besides the Autorest.Modelerfour, Autorest.Az has two more Autorest extensions dependencies, the Autorest.Clicommon and Autorest.Python, the Autorest.Clicommon is responsiblefor handling the user defined CLI directives such as operations splitting, polymorphism, renaming, hiding etc. and marking them properly in the code model. The Autorest.Python is integrated into Autorest.Az for the Rest APIs calls. Azure CLI does not do the Rest call directly. It either call the vendored SDKs from Azure CLI Extensions or call the public released SDK from Azure CLI main repo modules.

Both the Autorest.Clicommon and Autorest.Python take the code model generated by Autorest.Modelerfour as input. Normally Autorest.Python will not flatten the code model because in Python, complex objects are naturally supported. However,in Azure CLI, there is a requirement that object nesting level could not be deeper than two, otherwise it would be difficult to express the complex objects without using a bunch of delimiters. Therefore, in Autorest.Clicommon, the code model will be flattened and in Autorest.az, different code models from Autorest.Python and Autorest.Clicommon will be merged together.

After the code model has been updated and merged, AutoRest.az will render the code model into template and finally generate the Azure CLI code.

Different Generation Options

Autorest Options

1. --use
   This --use option is to specify the download location of the package. For Azure CLI code generation, by default, we will use the latest publish Autorest.az in npmjs. Private releases are available in github releases for users who want to try out some preview features. For example: --use=https://github.com/Azure/autorest.az/releases/download/1.7.3-b.20210818.1/autorest-az-1.7.3.tgz
2. --debug
   This --debug option will show more information while generating the code. It is very helpful for user to trouble shooting the wrong configuration in readme.az.md file which would cause no code is generated in the target folder.
3. --interactive
   This --interactive option will help users to understand how the Autorest Pipeline is scheduled during runtime.

Autorest.Az Specific Options

1. --az.debugger
   The --exname.debugger option is provided by Autorest for developers to debug the Autorest extension and exname is the extension name. After you start autorest.az with --az.debugger, you could then attach the VSCode to the autorest process for step by step debugging.
2. --sdk-no-flatten
   CLI code generator supports to generate the flattened SDK or the un-flattened SDK. Users can specify --sdk-no-flatten to generate the un-flattened SDK. The current publish released autorest.az (version 1.6.2) will still generate the flattened SDK in Azure CLI extensions generation. But in our latest private release, we have change the default behavior into un-flattened SDKs for both Azure CLI extensions and Azure CLI main repo modules generation.
3. --sdk-flatten
   This --sdk-flatten option is still in private releases. It will only take effect when no --sdk-no-flatten is specified. It's useful for those RPs that was onboard with previous CLI code generator when users don't want to introduce the SDK breaking changes.
4. --generate-sdk
   This --generate-sdk has two available value "yes" or "no". By default the value is "yes" for Azure CLI extensions generation, and "no" for Azure CLI main repo modules.
5. --compatible-level
   This --generate-sdk has two available value "track1" or "track2". By default the value is "track2" for both Azure CLI extensions and main repo modules generation.
6. --extension-mode
   This --extension-mode option is to set the global extension mode for the generated modules. it has three available value 'experimental' or 'preview' or 'stable'. By default the value is 'experimental' for Azure CLI extensions generation. And 'stable' for Azure CLI main repo modules but the command groups mode will still be 'experimental' if not specified.
7. --target-mode
   This --target-mode option is a convenience option for users who working on Azure CLI main repo modules. By default Autorest.az will generate code targeting azure-cli-extensions repo. Setting --target-mode=core if you want to generate azure-cli repo command modules. It basically equals to --sdk-no-flatten --generate-sdk=no --compatible-level=track2.

Other command line options can be found in the generate with different options doc

How to Use Azure CLI Code Generator

Azure CLI code generator is integrated into the pull request of Azure rest api specs repo and users could also try it locally. The guidance on how to generate Azure CLI code in rest api specs PR pipeline can be found in rest api specs documentation. In this section, we will focus on the guidance on how to generate Azure CLI code locally.

More detailed information can be found in the how to generate doc

Prepare Environment

1. Install the last version of Node.js
   Please follow the link to download the latest version of Node.js.
   • Hint: to install NodeJS. You could install a NodeJS globally or use nvm (for l