Azure PowerShell 文档样式指南

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

• azure-docs-powershell
• azure-powershell

版本

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

如果文章引用预览模块中的 cmdlet，则必须显式安装该模块，除非已安装 AzPreview 模块。 这是因为 Az PowerShell 模块仅包含正式版 （GA） 模块。

先决条件

始终先满足 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 cmdlet 的参数应按 cmdlet 帮助定义的顺序显示。 cmdlet 可以通过多种方式提供所需的参数。 执行该作时，请遵循要演示的用法的参数集。 Connect-AzAccount 是具有多种调用方法的 cmdlet 的示例。

Variables

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

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

为新资源随机分配密码

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

如果文章中的 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 。 例如， Install-AzAksCliTool Cloud Shell 不支持该 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 。