所需的开发指南

编写 cmdlet 时必须遵循以下准则。它们分为设计 cmdlet 的指南和编写 cmdlet 代码的指南。如果您不遵循这些准则，您的 cmdlet 可能会失败，并且您的用户在使用您的 cmdlet 时可能会获得较差的体验。

在这个主题中

设计指南

• 仅使用批准的动词 (RD01)

• Cmdlet 名称：无法使用的字符 (RD02)

• 不能使用的参数名称（RD03）

• 支持确认请求 (RD04)

• 交互式会话的支持力参数 (RD05)

• 文档输出对象 (RD06)

代码指南

• 派生自 Cmdlet 或 PSCmdlet 类 (RC01)

• 指定 Cmdlet 属性 (RC02)

• 覆盖输入处理方法 (RC03)

• 指定输出类型属性 (RC04)

• 不保留输出对象的句柄 (RC05)

• 稳健地处理错误 (RC06)

• 使用 Windows PowerShell 模块部署 Cmdlet (RC07)

设计指南

设计 cmdlet 时必须遵循以下准则，以确保使用您的 cmdlet 和其他 cmdlet 之间的用户体验一致。当您找到适用于您的情况的设计指南时，请务必查看代码指南以获取类似的指南。

仅使用批准的动词 (RD01)

Cmdlet 属性中指定的动词必须来自 Windows PowerShell 提供的可识别动词集。它不能是禁止的同义词之一。使用以下枚举定义的常量字符串来指定 cmdlet 动词：

• 系统.管理.自动化.VerbsCommon

• 系统.管理.自动化.VerbsCommunications

• 系统.管理.自动化.VerbsData

• 系统.管理.自动化.动词诊断

• 系统.管理.自动化.VerbsLifeCycle

• 系统.管理.自动化.VerbsSecurity

• 系统.管理.自动化.动词其他

有关批准的动词名称的详细信息，请参阅 Cmdlet 动词。

用户需要一组可发现且预期的 cmdlet 名称。使用适当的动词，以便用户可以快速评估 cmdlet 的功能并轻松发现系统的功能。例如，以下命令行命令获取系统上名称以“start”开头的所有命令的列表：get-command start-*。使用 cmdlet 中的名词将您的 cmdlet 与其他 cmdlet 区分开来。该名词表示将对其执行操作的资源。操作本身由动词表示。

Cmdlet 名称：无法使用的字符 (RD02)

命名 cmdlet 时，请勿使用以下任何特殊字符。

数字符号

逗号

括号

大括号

括号

与号

连字符 注意： 连字符可用于分隔动词和名词，但不能在名词或动词内使用。

斜线标记

反斜杠

美元符号

插入符

分号

冒号

双引号

单引号

尖括号

竖条

问号

在标志处

后勾（重音）

星号

百分号

加号

等号

波形符

不能使用的参数名称（RD03）

Windows PowerShell 为所有 cmdlet 提供通用参数集以及在特定情况下添加的其他参数。设计自己的 cmdlet 时，不能使用以下名称：Confirm、Debug、ErrorAction、ErrorVariable、OutBuffer、OutVariable、WarningAction、WarningVariable、WhatIf、UseTransaction 和 Verbose。有关这些参数的更多信息，请参阅通用参数名称。

支持确认请求 (RD04)

对于执行修改系统操作的 cmdlet，它们应调用 System.Management.Automation.Cmdlet.ShouldProcess* 方法来请求确认，并在特殊情况下调用 System.Management.Automation.Cmdlet.ShouldContinue* 方法。 （仅应在调用 System.Management.Automation.Cmdlet.ShouldProcess* 方法后才调用 System.Management.Automation.Cmdlet.ShouldContinue* 方法。）

要进行这些调用，cmdlet 必须通过设置 Cmdlet 属性的 SupportsShouldProcess 关键字来指定它支持确认请求。有关设置此属性的详细信息，请参阅 Cmdlet 属性声明。

笔记

如果 cmdlet 类的 Cmdlet 属性指示 cmdlet 支持调用 System.Management.Automation.Cmdlet.ShouldProcess* 方法，并且 cmdlet 无法调用 System.Management.Automation.Cmdlet.ShouldProcess* 方法，用户可能会意外地修改系统。

使用 System.Management.Automation.Cmdlet.ShouldProcess* 方法进行任何系统修改。用户首选项和 WhatIf 参数控制 System.Management.Automation.Cmdlet.ShouldProcess* 方法。相反，System.Management.Automation.Cmdlet.ShouldContinue* 调用会对潜在危险的修改执行额外检查。此方法不受任何用户首选项或 WhatIf 参数控制。如果您的 cmdlet 调用 System.Management.Automation.Cmdlet.ShouldContinue* 方法，则它应该具有一个 Force 参数，该参数会绕过对这两个方法的调用并继续执行操作。这很重要，因为它允许您的 cmdlet 在非交互式脚本和主机中使用。

如果您的 cmdlet 支持这些调用，用户可以确定是否应实际执行该操作。例如，Stop-Process cmdlet 在停止一组关键进程（包括 System、Winlogon 和 Spoolsv 进程）之前调用 System.Management.Automation.Cmdlet.ShouldContinue* 方法。

有关支持这些方法的更多信息，请参阅请求确认。

交互式会话的支持力参数 (RD05)

如果您的 cmdlet 以交互方式使用，请始终提供 Force 参数来覆盖交互操作，例如提示或读取输入行。这很重要，因为它允许您的 cmdlet 在非交互式脚本和主机中使用。交互主机可以实现以下方法。

• 系统.管理.自动化.主机.PSHostUserInterface.提示*

• System.Management.Automation.Host.Pshostuserinterface.PromptForChoice

• System.Management.Automation.Host.Ihostui支持多项选择.PromptForChoice

• System.Management.Automation.Host.Pshostuserinterface.PromptForCredential*

• System.Management.Automation.Host.Pshostuserinterface.ReadLine*

• System.Management.Automation.Host.Pshostuserinterface.ReadLineAsSecureString*

文档输出对象 (RD06)

Windows PowerShell 使用写入管道的对象。为了让用户能够利用每个 cmdlet 返回的对象，您必须记录返回的对象，并且必须记录这些返回对象的成员的用途。

代码指南

编写 cmdlet 代码时必须遵循以下准则。当您找到适用于您的情况的代码指南时，请务必查看设计指南以获取类似的指南。

派生自 Cmdlet 或 PSCmdlet 类 (RC01)

cmdlet 必须从 System.Management.Automation.Cmdlet 或 System.Management.Automation.PSCmdlet 基类派生。从 System.Management.Automation.Cmdlet 类派生的 Cmdlet 不依赖于 Windows PowerShell 运行时。它们可以直接从任何 Microsoft .NET Framework 语言调用。从 System.Management.Automation.PSCmdlet 类派生的 Cmdlet 依赖于 Windows PowerShell 运行时。因此，它们在运行空间内执行。

您实现的所有 cmdlet 类都必须是公共类。有关这些 cmdlet 类的详细信息，请参阅 Cmdlet 概述。

指定 Cmdlet 属性 (RC02)

为了使 Windows PowerShell 能够识别 cmdlet，其 .NET Framework 类必须使用 Cmdlet 属性进行修饰。此属性指定 cmdlet 的以下功能。

• 标识 cmdlet 的动词和名词对。

• 指定多个参数集时使用的默认参数集。当 Windows PowerShell 没有足够的信息来确定要使用哪个参数集时，将使用默认参数集。

• 指示 cmdlet 是否支持调用 System.Management.Automation.Cmdlet.ShouldProcess* 方法。此方法在 cmdlet 对系统进行更改之前向用户显示一条确认消息。有关如何发出确认请求的更多信息，请参阅请求确认。

• 指示与确认消息关联的操作的影响级别（或严重性）。在大多数情况下，应使用默认值“中”。有关影响级别如何影响向用户显示的确认请求的更多信息，请参阅请求确认。

有关如何声明 cmdlet 属性的详细信息，请参阅 CmdletAttribute 声明。

覆盖输入处理方法 (RC03)

为了使 cmdlet 参与 Windows PowerShell 环境，它必须至少重写以下输入处理方法之一。。

System.Management.Automation.Cmdlet.BeginProcessing 此方法被调用一次，用于提供预处理功能。

System.Management.Automation.Cmdlet.ProcessRecord 此方法被多次调用，用于提供逐条记录的功能。

System.Management.Automation.Cmdlet.EndProcessing 此方法被调用一次，用于提供后处理功能。

指定输出类型属性 (RC04)

OutputType 属性（在 Windows PowerShell 2.0 中引入）指定 cmdlet 返回到管道的 .NET Framework 类型。通过指定 cmdlet 的输出类型，您可以使其他 cmdlet 更容易发现您的 cmdlet 返回的对象。有关使用此属性修饰 cmdlet 类的详细信息，请参阅 OutputType 属性声明。

不保留输出对象的句柄 (RC05)

您的 cmdlet 不应保留传递给 System.Management.Automation.Cmdlet.WriteObject* 方法的对象的任何句柄。这些对象将传递到管道中的下一个 cmdlet，或者由脚本使用。如果保留对象的句柄，则两个实体将拥有每个对象，这会导致错误。

稳健地处理错误 (RC06)

管理环境本质上会检测您正在管理的系统并对其进行重要更改。因此，cmdlet 正确处理错误至关重要。有关错误记录的详细信息，请参阅 Windows PowerShell 错误报告。

• 当错误阻止 cmdlet 继续处理更多记录时，即为终止错误。该 cmdlet 必须调用引用 System.Management.Automation.ErrorRecord 对象的 System.Management.Automation.Cmdlet.ThrowTerminateError* 方法。如果 cmdlet 未捕获异常，Windows PowerShell 运行时本身会引发包含较少信息的终止错误。

• 对于不会停止对来自管道的下一条记录（例如，由不同进程生成的记录）进行操作的非终止错误，cmdlet 必须调用 System.Management.Automation.Cmdlet.WriteError* 方法引用 System.Management.Automation.ErrorRecord 对象。非终止错误的一个示例是特定进程未能停止时发生的错误。调用 System.Management.Automation.Cmdlet.WriteError* 方法允许用户一致地执行请求的操作并保留失败的特定操作的信息。您的 cmdlet 应尽可能独立地处理每条记录。

• System.Management.Automation.Cmdlet.ThrowTerminateError* 和 System.Management.Automation.Cmdlet.WriteError* 方法引用的 System.Management.Automation.ErrorRecord 对象在其核心需要一个异常。确定要使用的异常时，请遵循 .NET Framework 设计准则。如果错误在语义上与现有异常相同，则使用该异常或从该异常派生。否则，直接从 System.Exception 类型派生新的异常或异常层次结构。

System.Management.Automation.ErrorRecord 对象还需要一个为用户分组错误的错误类别。用户可以通过将 $ErrorView shell 变量的值设置为 CategoryView 来查看基于类别的错误。可能的类别由 System.Management.Automation.ErrorCategory 枚举定义。

• 如果 cmdlet 创建一个新线程，并且该线程中运行的代码引发未处理的异常，Windows PowerShell 将不会捕获该错误并将终止该进程。

• 如果对象的析构函数中的代码导致未处理的异常，Windows PowerShell 将不会捕获该错误并将终止该进程。如果对象调用导致未处理异常的 Dispose 方法，也会发生这种情况。

使用 Windows PowerShell 模块部署 Cmdlet (RC07)

创建 Windows PowerShell 模块来打包和部署 cmdlet。 Windows PowerShell 2.0 中引入了对模块的支持。您可以将包含 cmdlet 类的程序集直接用作二进制模块文件（这在测试 cmdlet 时非常有用），也可以创建引用 cmdlet 程序集的模块清单。 （使用模块时，您还可以添加现有的管理单元程序集。）有关模块的详细信息，请参阅编写 Windows PowerShell 模块。

参见

大力鼓励发展指引

咨询开发指南

编写 Windows PowerShell Cmdlet