网站搜索

如何添加 Cmdlet 描述

笔记

手动编写基于 XML 的帮助非常困难。 PlatyPS 模块允许您在 Markdown 中编写帮助，然后将其转换为基于 XML 的帮助。这使得编写和维护帮助变得更加容易。 PlatyPS 还可以为您创建可更新的帮助包。有关详细信息，请参阅使用 PlatyPS 创建基于 XML 的帮助。

本部分介绍如何添加 cmdlet 帮助的DESCRIPTION部分中显示的内容。在帮助文件中，此内容被添加到每个 cmdlet 的 Command 节点。

笔记

要完整查看帮助文件，请打开位于 PowerShell 安装目录中的 dll-Help.xml 文件之一。例如，Microsoft.PowerShell.Commands.Management.dll-Help.xml 文件包含多个 PowerShell cmdlet 的内容。

添加描述

  • 首先更详细地解释 cmdlet 的基本功能。在许多情况下，您可以解释 cmdlet 名称中使用的术语并通过示例说明不熟悉的概念。例如，如果 cmdlet 将数据附加到文件，请说明它将数据添加到现有文件的末尾。

  • 要查找 cmdlet 的所有功能，请查看参数列表。描述 cmdlet 的主要功能，然后包括其他功能和特性。例如，如果 cmdlet 的主要功能是更改一个属性，但 cmdlet 可以更改所有属性，请在详细描述中如此说明。如果 cmdlet 参数允许用户以不同方式获取信息，请进行解释。

  • 除了明显的用途之外，还包括有关用户使用 cmdlet 的方式的信息。例如，您可以使用 Get-Host cmdlet 检索的对象来更改 Windows PowerShell 命令窗口中文本的颜色。

    示例：“Get-Acl cmdlet 获取表示文件或资源的安全描述符的对象。安全描述符包含资源的访问控制列表 (ACL)。ACL 指定用户的权限用户组必须访问该资源。”

  • 详细描述应描述 cmdlet，但不应描述 cmdlet 使用的概念。将概念定义放在附加注释中。

参见

Windows PowerShell SDK

相关文章