你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

Azure PowerShell 文档风格指南

本文重点介绍以下 GitHub 存储库中提供的 Azure PowerShell 概念和参考内容:

版本

与大多数 Microsoft Learn 文档不同,azure-docs-powershell 存储库中的 Azure PowerShell 内容支持多个受支持的版本。 有关支持的版本的详细信息,请参阅 Azure PowerShell 支持生命周期

如果文章引用预览模块中的 cmdlet,则必须显式安装该模块,除非已安装 AzPreview 模块。 这是因为,只有一般可用(GA)模块才包含在 Az PowerShell 模块。

重要

请勿在文章中使用来自 AzureRM PowerShell 模块的命令。 AzureRM 已弃用。

先决条件

始终先满足 Azure 服务先决条件,然后遵循 Azure PowerShell 和 Azure Cloud Shell 说明进行操作。 例如,“你必须具有 Microsoft.Authorization/roleAssignments/write 权限才能完成本教程中的说明”应该排在第一位。

如果所有命令都与 Cloud Shell 不兼容,请指示用户在本地安装 Az PowerShell 模块。 请在 H2 先决条件部分中加入以下文本。

- This tutorial requires that you run Azure PowerShell locally:
  - [Install the latest version of the Az PowerShell module](/powershell/azure/install-azure-powershell).
  - Connect to your Azure account using the
    [Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount) cmdlet.

段落中语法元素的格式化

按照 PowerShell-Docs 样式指南编辑检查清单,在 Azure PowerShell 文档中格式化命令语法元素。

在段落中提及 cmdlet 名称时,请勿链接到 cmdlet 文档。 相反,用反引号将 cmdlet 名称括起来,这是内联代码 ('') 的样式。 在页面底部添加参考部分。 在引用部分列出 cmdlet 名称,并链接到其关联的参考文章。 例如:

This is an example of using the `Connect-AzAccount` and `Get-AzVM` cmdlets within a
paragraph.

## References

- [Connect-AzAccount](/powershell/module/az.accounts/connect-azaccount)
- [Get-AzVM](/powershell/module/az.compute/get-azvm)

注释

不要在超链接的方括号内设置文本的格式。 有关链接到 Azure PowerShell 内容的详细信息,请参阅链接到其他文档

参数顺序

Azure PowerShell cmdlet 的参数应按 cmdlet 帮助定义的顺序显示。 cmdlet 可以通过多种方式提供所需的参数。 执行该操作时,请遵循要演示的用法的参数集。 Connect-AzAccount 是具有多种调用方法的 cmdlet 示例。

变量

避免在多个代码块之间重用变量。

读者可能会在不同时间段完成文章的步骤。 如果变量设置不正确,在代码块中使用变量可能会导致错误。 如果必须跨步骤使用变量,请明确说明在后续步骤中重复使用变量。

为新资源随机分配密码

如果要创建具有与之关联的密码的资源,则不要使用硬编码的密码。 将密码签入源代码管理(甚至示例)是一种安全风险。

如果文章中的 Azure 资源需要纯文本密码,请使用 Read-Host 允许用户定义其密码。 MaskInput 参数可防止在 PowerShell 历史记录中记录密码。

$password = Read-Host 'Enter a Password' -MaskInput

避免命名冲突

某些 Azure 资源(如 Azure 容器注册表和 Key Vault)具有与域名关联的资源。 这些资源必须具有全局唯一的名称。 因此,当需要唯一性时,请使用随机值作为名称的一部分。 否则,当多个用户运行这些资源时,脚本无法创建所需的资源。 随机性不会阻止冲突,但可以缓解冲突。

使用 Get-Random 将随机数添加到名称中,例如:

$newAcrName = "myacr-$(Get-Random)"

交互式代码片段

何时使用交互式代码片段

如果 Cloud Shell 支持文章中的每个 Azure PowerShell 命令,请使用 azurepowershell-interactive 标记代码块,以将打开 Cloud Shell 按钮添加到代码片段:

```azurepowershell-interactive
Get-AzResourceGroup | Select-Object -Property ResourceGroupName, Location
```

何时不使用交互式代码片段

如果文章包含azurepowershell-interactive在 Cloud Shell 中不起作用的 Azure PowerShell 命令,请不要使用 。 仅使用 azurepowershell。 例如,Cloud Shell 不支持 Install-AzAksCliTool cmdlet:

Install-AzAksCliTool

如果将 Cloud Shell 功能命令与在 Cloud Shell 中不起作用的命令混合使用,当只有一些命令起作用时,可能会让客户感到沮丧。 相反,请坚持在所有代码块中使用 azurepowershell 语言标记,以避免混淆。

由于用户已在登录到 Cloud Shell 时进行身份验证,因此不要对仅包含 azurepowershell-interactive 的代码块使用 Connect-AzAccount 标记。 请改用 azurepowershell 语言标记。

将 AzureRM 更新到 Az PowerShell 模块

有关如何将使用 AzureRM PowerShell 模块的命令更新到 Az PowerShell 模块的信息,请参阅将 Azure PowerShell 从 AzureRM 迁移到 Az