Microsoft Atomic Azure CLI Dev Tools

aaz-dev 工具旨在从OpenAPI规范生成原子Azure CLI命令。有关更多信息，请参阅文档和视频。

安装

目前，我们可以使用.whl文件安装它。以后，我们将将其发布到PyPI以支持pip install安装方式。

设置开发环境

1 代码仓库

请在你的github账户中Fork以下仓库，并在本地磁盘上Clone它们

• Azure CLI
• Azure CLI扩展
• AAZ：用于上传生成的命令模型。
• azure-rest-api-specs或azure-rest-api-specs-pr

克隆后，你可以使用git remote add upstream命令在本地克隆的每个仓库中添加upstream。

2 设置 Python 环境

2.1 安装 Python

请在本地计算机上安装版本 >= 3.8 且 <= 3.12 的 Python。

• 对于 Windows 系统：您可以从 Python 下载页面 下载并运行完整安装程序。
• 对于 Linux 系统：您可以从软件包管理器安装 Python，或者从源代码构建一个稳定的发行版。

检查 Python 版本，确保其不低于 3.8。

• 对于 Windows 系统：

  C:\Users\{xxxx}\AppData\Local\Programs\Python\Python3{xxxx}\python --version
  

  C:\Users\{xxxx}\AppData\Local\Programs\Python\Python3{xxxx} 是 Python 的安装路径。
• 对于 Linux 系统：

  python --version
  

  如果您安装了多个版本，您也可以指定版本号。例如，如果您想运行 3.12 版本：

  python3.12 --version
  

2.2 设置 Python 虚拟环境

您可以使用 venv 来创建虚拟环境，这些环境可以与系统 site 目录隔离。每个虚拟环境都有其自己的 Python 二进制文件（与创建该环境的二进制文件版本匹配），并且可以在其 site 目录中拥有自己的独立 Python 包集。

您可以使用以下命令创建一个新的虚拟环境：

• 对于 Windows 系统：

  C:\Users\{xxxx}\AppData\Local\Programs\Python\Python3{xxxx}\python -m venv {some path}\{venv name}
  

• 对于 Linux 系统：

  python3.12 -m venv {some path}/{venv name}
  

3 激活现有的虚拟环境

在开发 azure-cli 时，您应该始终激活虚拟环境。

• 对于 Windows 系统：
  • PowerShell

  {some path}\{venv name}\Scripts\Activate.ps1
  

  • 命令提示符

  {some path}\{venv name}\Scripts\activate.bat
  

• 对于 Linux 系统：

source {some path}/{venv name}/bin/activate

激活虚拟环境后，python 命令将始终指向创建该虚拟环境的二进制文件，您始终可以使用 python。

python --version

4 安装 azure-cli 开发工具

4.1 安装 azure-cli-dev-tools

适用于 Windows 和 Linux 系统

pip install azdev

4.2 安装 aaz-dev-tools

• 对于 Windows 系统：
  • PowerShell

  pip install aaz-dev
  

  • 命令提示符

  pip install aaz-dev
  

• 对于 Linux 系统：

  pip install aaz-dev
  

4.3 设置构建环境

• 对于 Linux 用户，设置 python3 构建工具可以避免其他未知的安装问题。

  Ubuntu: apt-get install python3-dev build-essential
  Centos: yum install python3-devel
  

4.4 可能遇到的问题

• 对于 Windows 用户，依赖 python-levenshtein 的安装可能会遇到问题。开发者可能需要下载 .whl 文件并手动安装（参考 链接）。

5 代码库设置

5.1 azure-cli

在开始开发任务之前，您应该始终同步 upstream（Azure/Azure-cli）中 dev 分支的代码。如果您的命令将生成到 azure-cli 代码库，您应该检出以 feature- 为前缀的新分支。

5.2 azure-cli-extensions

如果您的命令将生成到 azure-cli-extension 代码库，您应该同步 upstream（Azure/Azure-cli-extensions）中 main 分支的代码，并检出以 feature- 为前缀的新分支。

5.3 aaz

在开始开发任务之前，您应该始终同步 upstream 中 main 分支的更改，并检出以 feature- 为前缀的新分支。

5.4 运行 azdev setup

每次同步 upstream 中的 azure-cli 代码时，您都应该运行以下命令。

azdev setup --cli {path to azure-cli} --repo {path to azure-cli-extensions}

6 运行 aaz-dev-tools

aaz-dev run -c {path to azure-cli} -e {path to azure-cli-extensions} -s {path swagger or swagger-pr} -a {path to aaz}

在使用生成的命令之前

1. 请确保您已通过 az login 登录。
2. 请确保您已通过 az account set -s {测试订阅 ID} 切换到测试订阅。
3. 如果您的命令在扩展中，请确保您已通过 azdev extension add {您的扩展名称} 加载此扩展。

其他文档

• 扩展
• 命令指南
• 编写测试
• 缩写语法：Azure CLI 的缩写语法可以帮助 CLI 用户传递复杂的参数值。只有由 aaz-dev 工具生成的 AAZ（原子 Azure CLI）命令的参数支持缩写语法。

提交代码和命令模型

开发完成后，您应首先将更改推送到您的分叉仓库，然后向上游仓库创建一个拉取请求。

• azure-cli: 向 dev 分支的 Azure/azure-cli 创建拉取请求
• azure-cli-extensions: 向 main 分支的 Azure/azure-cli-extensions 创建拉取请求
• aaz: 向 main 分支的 Azure/azz 创建拉取请求

报告问题和反馈

如果您在工具中发现任何错误，请在我们的 GitHub 仓库的 问题 部分提交问题。

许可证

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.