## 1. Project Overview & Quickstart (Azure/azure-cli) # Microsoft Azure CLI [](https://pypi.python.org/pypi/azure-cli) [](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=246&branchName=dev) [](https://azurecli.slack.com) A great cloud needs great tools; we're excited to introduce *Azure CLI*, our next generation multi-platform command line experience for Azure. Take a test run now from [Azure Cloud Shell](https://portal.azure.com/#cloudshell)! ## Installation Please refer to the [install guide](https://learn.microsoft.com/cli/azure/install-azure-cli) for detailed install instructions. A list of common install issues and their resolutions are available at [install troubleshooting](https://github.com/Azure/azure-cli/blob/dev/doc/install_troubleshooting.md). ### Developer installation (see below) - [Docker](#docker) - [Edge Builds](#edge-builds) - [Developer Setup](#developer-setup) ## Usage ```bash $ az [ group ] [ subgroup ] [ command ] {parameters} ``` ### Get Started Please refer to the ["get started" guide](https://learn.microsoft.com/cli/azure/get-started-with-az-cli2) for in-depth instructions. For usage and help content, pass in the `-h` parameter, for example: ```bash $ az storage -h $ az vm create -h ``` ### Highlights Here are a few features and concepts that can help you get the most out of the Azure CLI. The following examples are showing using the `--output table` format, you can change your default using the `az configure` command. #### Tab completion We support tab-completion for groups, commands, and some parameters ```bash # looking up resource group and name $ az vm show -g [tab][tab] AccountingGroup RGOne WebPropertiesRG $ az vm show -g WebPropertiesRG -n [tab][tab] StoreVM Bizlogic $ az vm show -g WebPropertiesRG -n Bizlogic ``` #### Query You can use the `--query` parameter and the [JMESPath](http://jmespath.org/) query syntax to customize your output. ```bash $ az vm list --query "[?provisioningState=='Succeeded'].{ name: name, os: storageProfile.osDisk.osType }" Name Os ---------------------- ------- storevm Linux bizlogic Linux demo32111vm Windows dcos-master-39DB807E-0 Linux ``` #### Exit codes For scripting purposes, we output certain exit codes for differing scenarios. |Exit Code |Scenario | |---|---| |0 |Command ran successfully. | |1 |Generic error; server returned bad status code, CLI validation failed, etc. | |2 |Parser error; check input to command line. | |3 |Missing ARM resource; used for existence check from `show` commands. | ### Common scenarios and use Azure CLI effectively Please check [Tips for using Azure CLI effectively](https://learn.microsoft.com/en-us/cli/azure/use-cli-effectively). It describes some common scenarios: - [Output formatting (json, table, or tsv)](https://learn.microsoft.com/en-us/cli/azure/use-cli-effectively#output-formatting-json-table-or-tsv) - [Pass values from one command to another](https://learn.microsoft.com/en-us/cli/azure/use-cli-effectively#pass-values-from-one-command-to-another) - [Async operations](https://learn.microsoft.com/en-us/cli/azure/use-cli-effectively#async-operations) - [Generic update arguments](https://learn.microsoft.com/en-us/cli/azure/use-cli-effectively#generic-update-arguments) - [Generic resource commands - `az resource`](https://learn.microsoft.com/en-us/cli/azure/use-cli-effectively#generic-resource-commands---az-resource) - [REST API command - `az rest`](https://learn.microsoft.com/en-us/cli/azure/use-cli-effectively#rest-api-command---az-rest) - [Quoting issues](https://learn.microsoft.com/en-us/cli/azure/use-cli-effectively#quoting-issues) - [Work behind a proxy](https://learn.microsoft.com/en-us/cli/azure/use-cli-effectively#work-behind-a-proxy) - [Concurrent builds](https://learn.microsoft.com/en-us/cli/azure/use-cli-effectively#concurrent-builds) ### More samples and snippets For more usage examples, take a look at our [GitHub samples repo](http://github.com/Azure/azure-cli-samples) or [https://learn.microsoft.com/cli/azure/overview](https://learn.microsoft.com/cli/azure/overview). ### Write and run commands in Visual Studio Code With the [Azure CLI Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.azurecli) Visual Studio Code extension, you can create `.azcli` files and use these features: - IntelliSense for commands and their arguments. - Snippets for commands, inserting required arguments automatically. - Run the current command in the integrated terminal. - Run the current command and show its output in a side-by-side editor. - Show documentation on mouse hover. - Display current subscription and defaults in status bar. - To enable IntelliSense for other file types like `.ps1` or `.sh`, see [microsoft/vscode-azurecli#48](https://github.com/microsoft/vscode-azurecli/issues/48). ## Data Collection The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices. ### Telemetry Configuration Telemetry collection is on by default. To opt out, please run `az config set core.collect_telemetry=no` to turn it off. ## Reporting issues and feedback If you encounter any bugs with the tool please file an issue in the [Issues](https://github.com/Azure/azure-cli/issues) section of our GitHub repo. To provide feedback from the command line, try the `az feedback` command. \[Microsoft internal] You may contact the developer team via azpycli@microsoft.com. ## Developer installation ### Docker We maintain a Docker image preconfigured with the Azure CLI. See our [Docker tags](https://mcr.microsoft.com/v2/azure-cli/tags/list) for available versions. ```bash $ docker run -u $(id -u):$(id -g) -v ${HOME}:/home/az -e HOME=/home/az --rm -it mcr.microsoft.com/azure-cli: ``` ### Edge builds If you want to get the latest build from the `dev` branch, you can use our "edge" builds. You can download the latest builds by following the links below: | Package | Link | |:-----------------:|:-------------------------------------------| | MSI | https://aka.ms/InstallAzureCliWindowsEdge | | Homebrew Formula | https://aka.ms/InstallAzureCliHomebrewEdge | | Ubuntu Bionic Deb | https://aka.ms/InstallAzureCliBionicEdge | | Ubuntu Focal Deb | https://aka.ms/InstallAzureCliFocalEdge | | Ubuntu Jammy Deb | https://aka.ms/InstallAzureCliJammyEdge | | RPM el8 | https://aka.ms/InstallAzureCliRpmEl8Edge | On Windows, you need to uninstall the official version before installing the edge build. (See https://github.com/Azure/azure-cli/issues/25607#issuecomment-1452855212) You can easily install the latest Homebrew edge build with the following command: ```bash # You need to uninstall the stable version with `brew uninstall azure-cli` first curl --location --silent --output azure-cli.rb https://aka.ms/InstallAzureCliHomebrewEdge brew install --build-from-source azure-cli.rb ``` You can install the edge build on Ubuntu Jammy with the following command: ```bash curl --location --silent --output azure-cli_jammy.deb https://aka.ms/InstallAzureCliJammyEdge && dpkg -i azure-cli_jammy.deb ``` And install the edge build with rpm package on RHEL 8 or CentOS Stream 8: ```bash dnf install -y $(curl --location --silent --output /dev/null --write-out %{url_effective} https://aka.ms/InstallAzureCliRpmEl8Edge) ``` Here's an example of installing edge builds with pip3 in a virtual environment. The `--upgrade-strategy=eager` option will install the edge builds of dependencies as well. ```bash $ python3 -m venv env $ . env/bin/activate $ pip3 install --pre azure-cli --extra-index-url https://azurecliprod.blob.core.windows.net/edge --upgrade-strategy=eager ``` To upgrade your current edge build pass the `--upgrade` option. The `--no-cache-dir` option is also recommended since the feed is frequently updated. ```bash $ pip3 install --upgrade --pre azure-cli --extra-index-url https://azurecliprod.blob.core.windows.net/edge --no-cache-dir --upgrade-strategy=eager ``` The edge build is generated for each PR merged to the `dev` branch as a part of the Azure DevOps Pipelines. ### Get builds of arbitrary commit or PR If you would like to get builds of arbitrary commit or PR, see: [Try new features before release](doc/try_new_features_before_release.md) ## Developer setup If you would like to setup a development environment and contribute to the CLI, see: [Configuring Your Machine](https://github.com/Azure/azure-cli/blob/dev/doc/configuring_your_machine.md) [Authoring Command Modules](https://github.com/Azure/azure-cli/tree/dev/doc/authoring_command_modules) [Code Generation](https://github.com/Azure/aaz-dev-tools) ## Contribute code This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. If you would like to become an active contributor to this project please follow the instructions provided in [Microsoft Open Source Guidelines](https://opensource.microsoft.com/collaborate). ## 2. Official Technical Reference & Guides (Azure/aaz-dev-tools) ## File: README.md # Microsoft Atomic Azure CLI Dev Tools The *aaz-dev* tool is designed to generate atomic Azure CLI commands from OpenAPI specifications. For more information, please refer to [document](https://azure.github.io/aaz-dev-tools/) and [video](https://microsoft.sharepoint.com/teams/AzureCLITools237/_layouts/15/embed.aspx?UniqueId=97905452-69c2-4f7c-8c6b-b411c7fd0013&embed=%7B%22ust%22%3Atrue%2C%22hv%22%3A%22CopyEmbedCode%22%7D&referrer=StreamWebApp&referrerScenario=EmbedDialog.Create). ## Installation Currently, we can install it with a [.whl file](https://github.com/Azure/aaz-dev-tools/releases). Later on, we'll publish it to PyPI to support *pip install* way of installation. ## Setting up your development environment ### 1 Code repos Please `Fork` the following repos in your github account and `Clone` them in your local disk: - [Azure CLI](https://github.com/Azure/azure-cli) - [Azure CLI Extension](https://github.com/Azure/azure-cli-extensions) - [AAZ](https://github.com/Azure/aaz): Used to upload the command model generated. - [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs) or [azure-rest-api-specs-pr](https://github.com/Azure/azure-rest-api-specs-pr) After clone you can add `upstream` for every repos in your local clone by using `git remote add upstream`. ### 2 Setup python #### 2.1 Install python Please install python with version >= 3.10 and <= 3.14 in your local machine. - For windows: You can download and run full installer from [Python Download](https://www.python.org/downloads/). - For linux: You can install python from Package Manager or build a stable relase from source code Check the version of python, make use it's not less than 3.10. - For windows: You can run: ```PowerShell C:\Users\{xxxx}\AppData\Local\Programs\Python\Python3{xxxx}\python --version ``` `C:\Users\{xxxx}\AppData\Local\Programs\Python\Python3{xxxx}` is the python installation path. - For linux: ```bash python --version ``` You can also specify the version number when you have multiple versions installed. For example if you want to run version 3.12 ```bash python3.12 --version ``` #### 2.2 Setup a python virtual environment You can use venv to create virtual environments, optionally isolated from system site directories. Each virtual environment has its own Python binary (which matches the version of the binary that was used to create this environment) and can have its own independent set of installed Python packages in its site directories. You can run the following command to create a new virtual environment: - For windows: ```PowerShell C:\Users\{xxxx}\AppData\Local\Programs\Python\Python3{xxxx}\python -m venv {some path}\{venv name} ``` - For linux: ```bash python3.12 -m venv {some path}/{venv name} ``` ### 3 Active existing virtual environment You should __always__ active the virtual environment for azure-cli development. - For Windows: - Powershell ```powershell {some path}\{venv name}\Scripts\Activate.ps1 ``` - Command Prompt ```Command Prompt {some path}\{venv name}\Scripts\activate.bat ``` - For Linux: ```bash source {some path}/{venv name}/bin/activate ``` After active the virtual environment, the `python` command will always be the one creates this virtual environment and you can always use `python` ``` python --version ``` ### 4 Install tools for azure-cli development #### 4.1 Install aaz-dev-tools - For Windows - Powershell ``` pip install aaz-dev ``` - Command Prompt ``` pip install aaz-dev ``` - For linux ```bash pip install aaz-dev ``` #### 4.2 Set up build env - For linux users, set up python3 build tools would avoid other unseen installation issues ``` Ubuntu: apt-get install python3-dev build-essential Centos: yum install python3-devel ``` ### 5. Code repos setup #### 5.1 azure-cli Before start to the development task, you should always sync the code in the `dev` branch of `upstream`(Azure/Azure-cli). If your commands will generated to azure-cli repo, you should checkout a new branch with `feature-` prefix. #### 5.2 azure-cli-extensions If your commands will generated to azure-cli-extension repo, you should sync the code in the `main` branch of `upstream`(Azure/Azure-cli-extensions), and checkout a new branch with `feature-` prefix. #### 5.3 aaz Before start to the development task, you should always sync the change in the `main` branch of `upstream`, and checkout a new branch with `feature-` prefix. #### 5.4 run `azdev setup` You should always run the following command everytime you sync `azure-cli` code of `upstream`. ``` azdev setup --cli {path to azure-cli} --repo {path to azure-cli-extensions} ``` ### 6 Run aaz-dev-tools ```bash aaz-dev run -c {path to azure-cli} -e {path to azure-cli-extensions} -s {path swagger or swagger-pr} -a {path to aaz} ``` ## Before using generated commands 1. Make sure you have logined by `az login`. 2. Make sure you have switched to the subscription for test by `az account set -s {subscription ID for test}` 3. If your commands are in extensions, make sure you have loaded this extension by `azdev extension add {your extension name}` ## Other documentations - [extension](https://github.com/Azure/azure-cli/blob/dev/doc/extensions/README.md) - [command guidelines](https://github.com/Azure/azure-cli/blob/dev/doc/command_guidelines.md) - [authoring tests](https://github.com/Azure/azure-cli/blob/dev/doc/authoring_tests.md) - [shorthand syntax](https://github.com/Azure/azure-cli/blob/dev/doc/shorthand_syntax.md): Azure cli shorthand syntax can help cli users to pass complicated argument values. Only the arguments of AAZ(Atomic Azure CLI) commands generated by aaz-dev tool support shorthand syntax. ## Submit code and command models After finish the development, you should push the change in your forked repos first, and the create a Pull Request to upstream repos. - azure-cli: create a Pull Request to `dev` branch of `Azure/azure-cli` - azure-cli-extensions: create a Pull Request to `main` branch of `Azure/azure-cli-extensions` - aaz: create a Pull Request to `main` branch of `Azure/azz` ## Reporting issues and feedback If you encounter any bugs with the tool please file an issue in the [Issues](https://github.com/Azure/aaz-dev-tools/issues) section of our GitHub repository. ## License ``` MIT License Copyright (c) Microsoft Corporation. All rights reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ""Software""), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` --- ## File: docs/README.md --- layout: page title: Introduction permalink: / --- _AAZDev is a tool that helps Azure CLI developers generate Atomic CLI commands from REST API Specifications._ ## Background ### What is Azure CLI? The full name of Azure CLI is Azure command-line interface. It's a set of commands used to create and manage Azure resources. Below is a common CLI command that will create an azure virtual network. ```bash az network vnet create --name my-vnet --resource-group my-resource-group ``` Every CLI command consists of 2 parts: - Command name: There are thousands of commands in CLI, which are organized into a tree. Its nodes are command groups, and its leaves are commands. ``` az (root) |> network (group) |> vnet (group) |> create (command) ``` We call `network vnet` the command group name and `create` the command operation name. - Argument: CLI user can pass in various types of arguments. In addition to the primitive types, users can also pass object, array and dict. For more information, please review [CLI/Argument](assets/cli/argument.md). There are two repos to maintain Azure CLI commands： - [Azure CLI](https://github.com/Azure/azure-cli) - [Azure CLI Extension](https://github.com/Azure/azure-cli-extensions) ### What is REST API Specifications? Azure uses swagger(OpenAPI) or TypeSpec to define REST API specifications. Most of files are maintained in the following two repos: - [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs) - [azure-rest-api-specs-pr](https://github.com/Azure/azure-rest-api-specs-pr) Swagger Specification (or known as OpenAPI Specification) is an API description format for REST APIs. An OpenAPI file, can be written in YAML or json, allows developers to describe the entire API. TypeSpec (tsp) is a language for defining cloud service APIs and models. It is a highly extensible language with primitives that can describe APIs using REST, gRPC, and other protocols. The definition of API in swagger or TypeSpec is required before using AAZDev tool. ### What is Atomic CLI Command? _An Atomic CLI Command operate on one azure resource without dependencies on other things, such as SDK or other commands._ Azure api is designed to be restful. So usually one Atomic CLI command operates on one API. But there is an exception, there are multiple APIs that list the same kind of resource in difference scopes. In that case, one list Atomic command operates on multiple APIs. Atomic CLI commands do not depend on the SDK or other commands. This brings several advantages to CLI: - State of truth: An Atomic CLI command has all required information in its model and code, so its current state tells how it works without the influence by the change in SDK or other commands. This feature can be used for breaking change detection or other command analysis tasks. - Flexible: Atomic CLI commands are decoupled from others commands, so it's easy to add, modify, upgrade and release an Atomic CLI command without influence other commands. And the change can be refined down to the API level instead of SDK level. The degree of coupling between commands relay on SDK can be seen from the following PR. The SDK packages a batch of APIs, and when one API has new change and is released in a new SDK version, we have to test and update the commands that use the whole batch of APIs in SDK instead of the one API we care about. Each time we bump up an SDK, hundreds of tests need to rerun in live and their recording files need to be updated, we also need to fix other commands that are broken by new SDK. It wasted a lot of time and created a lot of hidden problems. By applying Atomic CLI commands, we can avoid them. ## Overview AAZDev Tool consists of 4 parts: - API Translators: They are responsible for translating the API specification into a command model. We've implemented both swagger 2.0 and Typespec translator which can support to translate the API specs in [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs) repo and [azure-rest-api-specs-pr](https://github.com/Azure/azure-rest-api-specs-pr) repo. - Model Editors: They are used to edit command models. Currently, _Workspace Editor_ is implemented. More details are introduced in _Workspace_ paragraph. - Command Models: The command models generated from translators and modified in editors will be persisted in a repo called AAZ. The persistence of models can be useful in many ways. More details are introduced in _AAZ Repo_ paragraph. - Code Generators: They are used to generator code from command models. The _CLI Generator_ is implemented to generate code into [Azure CLI](https://github.com/Azure/azure-cli) repo and _CLI Extension Generator_ is for [Azure CLI Extension](https://github.com/Azure/azure-cli-extensions) For CLI Developers, they edit command models in Model Editors and select command models for Code Generators. ## Swagger V2 Translator A Resource can be translated into a single command or multiple commands under a command group. ### Group part naming Swagger V2 translator uses the `valid part` of url to generate the group part of a command. The `valid part` of url is the url suffix starts by its Resource Provider with parameter placeholders replaced by `{}` and locations segment removed. The table below show some examples with valid part highlighted. | Resource Provider | Resource Url | valid part of url | | ---- | ---- | ---- | | Microsoft.EdgeOrder | /subscriptions/{subscriptionId}/providers/**Microsoft.EdgeOrder/addresses** | Microsoft.EdgeOrder/addresses | | Microsoft.EdgeOrder | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/**Microsoft.EdgeOrder/addresses** | Microsoft.EdgeOrder/addresses | | Microsoft.EdgeOrder | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/**Microsoft.EdgeOrder/addresses/{addressName}** | Microsoft.EdgeOrder/addresses/{} | | Microsoft.EdgeOrder | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/**Microsoft.EdgeOrder**/locations/{location}**/orders/{orderName}** | Microsoft.EdgeOrder/orders/{} | | Microsoft.Network | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/**Microsoft.Network/virtualNetworks/{virtualNetworkName}/subnets/{subnetName}** | Microsoft.Network/virtualNetworks/{}/subnets/{} | | Microsoft.Consumption | /providers/Microsoft.Management/managementGroups/{managementGroupId}/providers/Microsoft.Billing/billingPeriods/{billingPeriodName}/**Microsoft.Consumption/aggregatedcost** | Microsoft.Consumption/aggregatedcost | Each segments of valid part corresponds to a group name. The parameter segments are ignored by default. And `Microsoft.` prefix in resource provider segment is ignored too. The singular values of the remaining segments are converted to snake case with `-` as separator. For example `Microsoft.Network/virtualNetworks/{}/subnets/{}` has three segments: `Microsoft.Network`, `virtualNetworks`, `subnets` and they correspond to `network`, `virtual-network` and `subnet`. So the full command group name will be `network virtual-network subnet` ### Operation part naming Swagger V2 translator use the HTTP methods to generate the operation part of a command. The table below show the mapping relationship between the common command operation name and the resource HTTP methods. | Common Command Operation Name | Resource HTTP Method | | ---- | ---- | | show | GET | | list | GET | | create | PUT | | delete | DELETE | | update (by generic) | GET + PUT | | update (by patch) | PATCH | For example if a resource has the following properties: ```yaml resource_id: '/subscriptions/{}/resourcegroups/{}/providers/microsoft.edgeorder/addresses/{}' methods: - GET - DELETE - PUT - PATCH ``` This resource will be translated into four commands under `az edge-order address` command group: ```yaml az data-bricks workspace: - show - delete - create - update ``` The `show`, `delete`, `create` commands call `GET`, `DELETE`, `PUT` methods respectively. The `update` command will either use a combination of `GET`+`PUT` methods or a single `PATCH` method. When all three methods exist in a resource, `Generic First` operation will use `GET`+`PUT` combination, and `Patch First` will use `PATCH` method. Translators will also detect a `GET` method should be named as `show` or `list` based on its url and response schema. For example the following two resources will generate `list` command of `az edge-order address`. ```yaml resource_id: '/subscriptions/{}/providers/microsoft.edgeorder/addresses' methods: - GET ``` ```yaml resource_id: '/subscriptions/{}/resourcegroups/{}/providers/microsoft.edgeorder/addresses' methods: - GET ``` Translators will automatically merge them into one `list` commands if their response schemas are the same. If their response schemas are different, a special suffix will be added after `list` operation name to distinguish two commands. And the name can be renamed in editor. The `POST` method is special. If a resource has `POST` method only and the last segment of valid part is not a parameter segment, that segment will be used as operation name, else a temporary name will be generated, which can be renamed in editor later. ## TypeSpec API Translator - `typespec-aaz` `typespec-aaz` translates an interface under a specific namespace from typespec specification into a resource url aligned with swagger api, with defined data models translated into the input and output parameters. | Namespace | Interface | resource url | | ---- | ---- | ---- | | Microsoft.Community | CommunityTrainings | /subscriptions/{subscriptionId}/providers/**microsoft.community/communitytrainings** | The data models defined in typespec will be translated into aaz models. For example, The model value defined as below ```typespec @doc("The name of the Community Training Resource") @pattern("^[a-zA-Z0-9-]{3,24}$") @key("communityTrainingName") @segment("communityTrainings") @path name: string; ``` would be tranlsated into a parameter object below: ``` { format: {pattern: "^[a-zA-Z0-9-]{3,24}$"}, pattern: "^[a-zA-Z0-9-]{3,24}$", name: "communityTrainingName", required: true, type: "string" } ``` `typespec-aaz` translates the typespec api into aaz models and then the following steps keep the same as swagger specifications. ## Workspace Before developers finish customizing the command models and export them in AAZ repo for persistence, the draft is saved in a workspace. Workspaces are like containers, they are isolated so that changes in one do not affect the others. Therefore, developers can create as many workspaces as needed for different purposes. It's possible to add resources from different resource providers, but they should be in the same plane. Currently, we only support Management plane. Another note is that a workspace don't allow to add a resource multiple times in different versions. For example, if virtual network resource('/subscriptions/{}/resourcegroups/{}/providers/microsoft.network/virtualnetworks/{}') of version 2021-05-01 is added in a workspace, it's not allowed to add other versions of this resource in this workspace. Please jump to [Workspace Editor](pages/usage/workspace_editor.md) for more details. ## AAZ Repo The name __AAZ__ comes from the abbreviation of Atomic Azure. This repo is to maintain Atomic Azure Cli command models. You can access this repo by [link](https://github.com/Azure/aaz/tree/main). There are two folders in the root of AAZ: - Commands: This folder provides an index of command models available in AAZ. They are organized in a command tree. - Resources: This folder save command models in xml files which is called command configurations. Those files are separated by resources. ### Command Tree The data of command tree is in [Commands/tree.json](https://github.com/Azure/aaz/blob/main/Commands/tree.json). Json files are hard to read, so the data is also rendered as Markdown files in a tree hierarchy. Each folder represents each node of the tree and also represents a command group. Its readme.md file shows the summary, subgroups and commands of this group. And the links in the file help us to browse quickly. Each Markdown files starts with '_' represents each leaf of the tree which also represents a command. Its contains the summary, versions and examples of this command. And each version links to a command configuration in Resources folder. ### Command Configuration The format of command configuration file path is: ``` Resources/{plane}/{base64(resource_id)}/{api_version}.xml ``` A command configuration file contains more than one commands, which are generated from the same resource. The diagram below show the structure of command configuration file. The commands in a configuration file organized in hierarchy. There are three sections in every command: - Argument Section: The arguments defined in argument section and grouped by Argument Group. - Operation Section: The operations performed by the command are defined in Operation Section. Currently, there are two kinds of operations: - HTTP Operations: This kind of operations are used to generate HTTP request. - Instance Operations: This kind of operations are used to change the data of resource instance. - Output Section: The output transformations are defined in Output Section. The data flow from Argument Section to Operation Section and then to Output Section. The arguments are linked with operations by their variant name. The operations are generated by swagger and do not support customization. The Operation Section in diagram is from a classic `update` command which use `get+put` methods. In model editors the modification of arguments and special output formats are supported. ### Verify Metadata To verify the "complicated" structure above, AAZ repo itself provides a verification workflow based on GitHub Actions. When you raise a pull request, a workflow will be automatically triggered, and we don't need to pay much attention on that. But when the workflow fails, we should know how to fix it. A typical failure is as follows: When you click to view the details, you will see: What does "Please pull the latest main branch, and Export your command model again." mean? Actually, there is a set of Git commands behind that: 1. Run `git reset --hard` to revert all your previous changes. 2. Run `git pull main` to pull the latest main branch. 3. Click `Export` button on the workspace editor to export your target model. 4. Now you can commit and push your current changes. If the above steps still don't solve your problem, you can click to expand `Verify data consistency`. There must be something wrong with your current structure, please check the exception part carefully. ## CLI Generator and CLI Extension Generator ### Command Module CLI commands are separated into different command modules in Azure CLI repo or Azure CLI extension repo. So it's required to select a specific module for generators. ### Profile Azure CLI uses profiles to support Azure Stack. There are five profiles: - latest - 2020-09-01-hybrid - 2019-03-01-hybrid - 2018-03-01-hybrid - 2017-03-09-profile The `latest` profile contains a full set of commands and the rest profiles contains a sub set of commands from the `latest`. One command may call different api versions in different profiles. So its arguments and output schema may vary from profile to profile. Please jump to [CLI Generator Usage](pages/usage/cli-generator/) for more details.