编写 PowerShell Cmdlet 帮助

PowerShell cmdlet 可能很有用，但除非您的帮助主题清楚地解释了 cmdlet 的用途以及如何使用它，否则该 cmdlet 可能不会被使用，甚至更糟糕的是，它可能会让用户感到沮丧。基于 XML 的 cmdlet 帮助文件格式增强了一致性，但要提供出色的帮助还需要更多。

如果您从未编写过 cmdlet 帮助，请查看以下准则。下节介绍了创作 cmdlet 帮助主题所需的 XML 架构。从创建 Cmdlet 帮助文件开始。该主题包括顶级 XML 节点的描述。

Cmdlet 帮助的编写指南

写得好

没有什么可以取代写得好的主题。如果您不是专业作家，请寻找作家或编辑来帮助您。另一种选择是将帮助文本复制到 Microsoft Word 中，并使用语法和拼写检查来改进您的工作。

写简单

使用简单的单词和短语。避免行话。考虑到许多读者只配备了一本外语词典和您的帮助主题。

书写一致

相关 cmdlet 的帮助应该类似（例如，Get-Content 和 Set-Content）。使用标准参数的标准描述，例如 Force 和 InputObject。 （从核心 cmdlet 的帮助中复制它们。）使用标准术语。例如，使用“参数”而不是“参数”，使用“cmdlet”而不是“命令”或“command-let”。

以动词开始概要

摘要字段告知用户 cmdlet 的作用，而不是它是什么或它如何工作。动词创建一个基于任务的语句，通知用户此 cmdlet 是否满足他们的要求。使用简单的动词，如“获取”、“创建”和“更改”。避免使用“设置”，它可能是像“修改”这样模糊而花哨的词。

聚焦于物体

大多数“get”cmdlet 都会显示一些内容，但它们的主要功能是获取对象。在帮助中，重点关注对象，以便用户了解默认显示只是众多显示之一，并且他们可以以不同的方式使用您为他们检索的对象的方法和属性。

写详细的描述

在详细说明中简要列出 cmdlet 可以执行的所有操作。如果主要功能是更改一个属性，但 cmdlet 可以更改所有属性，请在详细说明中列出。

使用常规语法

使用 Windows 和 UNIX 命令行帮助中常见的标准 Backus-Naur 格式。

使用 Microsoft .NET 类型作为参数值

参数值的占位符（在语法和参数描述中）显示参数将接受的对象的 .NET Framework 类型。 PowerShell 团队开发此约定是为了帮助用户了解 .NET Framework。

编写完整的参数说明

参数描述必须告知用户两件事：参数的作用（其效果）以及他们必须为参数值键入什么。

写实际例子

这些示例应该展示如何使用所有参数，但最重要的是展示如何在实际任务中使用 cmdlet。从一个简单的示例开始，然后编写越来越复杂的示例。在最后一个示例中，展示如何在管道中使用 cmdlet。

使用注释字段

使用注释字段解释用户需要理解 cmdlet 的概念。您还可以使用注释来帮助用户避免常见错误。避免使用发生变化的 URL。相反，为用户提供搜索词。

测试你的帮助

就像测试代码一样测试帮助。让朋友和同事阅读您的帮助内容并提供反馈。您还可以从新闻组征求反馈。

参见

• 如何创建 Cmdlet 帮助文件
• 如何将 Cmdlet 名称和概要添加到 Cmdlet 帮助主题
• 如何向 Cmdlet 帮助主题添加详细说明
• 如何向 Cmdlet 帮助主题添加语法
• 如何向 Cmdlet 帮助主题添加参数
• 如何将输入类型添加到 Cmdlet 帮助主题
• 如何将返回值添加到 Cmdlet 帮助主题
• 如何向 Cmdlet 帮助主题添加注释
• 如何向 Cmdlet 帮助主题添加示例
• 如何将相关链接添加到 Cmdlet 帮助主题
• Windows PowerShell SDK