大力鼓励发展指引

本节介绍编写 cmdlet 时应遵循的准则。它们分为设计 cmdlet 的指南和编写 cmdlet 代码的指南。您可能会发现这些准则并不适用于所有场景。但是，如果它们确实适用并且您不遵循这些准则，则您的用户在使用您的 cmdlet 时可能会获得较差的体验。

设计指南

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

使用特定名词作为 Cmdlet 名称 (SD01)

cmdlet 命名中使用的名词需要非常具体，以便用户可以发现您的 cmdlet。在通用名词（例如“服务器”）前面加上产品名称的缩写版本。例如，如果名词指的是运行 Microsoft SQL Server 实例的服务器，请使用“SQLServer”等名词。特定名词和经过批准的动词的简短列表的组合使用户能够快速发现和预期功能，同时避免 cmdlet 名称之间的重复。

为了增强用户体验，您为 cmdlet 名称选择的名词应该是单数。例如，使用名称 Get-Process 而不是 Get-Processes。最好对所有 cmdlet 名称都遵循这一规则，即使 cmdlet 可能对多个项目执行操作也是如此。

使用 Pascal 大小写作为 Cmdlet 名称 (SD02)

参数名称使用帕斯卡大小写。换句话说，动词的第一个字母和名词中使用的所有术语都大写。例如，“Clear-ItemProperty”。

参数设计指南（SD03）

cmdlet 需要接收其必须操作的数据的参数，以及指示用于确定操作特征的信息的参数。例如，cmdlet 可能具有从管道接收数据的 Name 参数，并且 cmdlet 可能具有 Force 参数以指示可以强制 cmdlet 执行其任务。手术。 cmdlet 可以定义的参数数量没有限制。

使用标准参数名称

您的 cmdlet 应使用标准参数名称，以便用户可以快速确定特定参数的含义。如果需要更具体的名称，请使用标准参数名称，然后指定更具体的名称作为别名。例如，Get-Service cmdlet 有一个参数，该参数具有通用名称 (Name) 和更具体的别名 (ServiceName)。这两个术语都可以用来指定参数。

有关参数名称及其数据类型的详细信息，请参阅 Cmdlet 参数名称和功能指南。

使用单一参数名称

避免对值为单个元素的参数使用复数名称。这包括采用数组或列表的参数，因为用户可能提供仅包含一个元素的数组或列表。

仅在参数值始终为多元素值的情况下才应使用复数参数名称。在这些情况下，cmdlet 应验证是否提供了多个元素，并且如果未提供多个元素，则 cmdlet 应向用户显示警告。

使用帕斯卡大小写作为参数名称

参数名称使用帕斯卡大小写。换句话说，参数名称中每个单词的首字母大写，包括名称的第一个字母。例如，参数名称 ErrorAction 使用正确的大小写。以下参数名称使用了不正确的大小写：

errorAction

erroraction

采用选项列表的参数

有两种方法可以创建可以从一组选项中选择其值的参数。

• 定义指定有效值的枚举类型（或使用现有枚举类型）。然后，使用枚举类型创建该类型的参数。

• 将 ValidateSet 属性添加到参数声明中。有关此属性的更多信息，请参阅 ValidateSet 属性声明。

使用参数的标准类型

为了确保与其他 cmdlet 的一致性，请尽可能使用标准类型的参数。有关不同参数应使用的类型的详细信息，请参阅标准 Cmdlet 参数名称和类型。本主题提供了几个主题的链接，这些主题描述了标准参数组（例如“活动参数”）的名称和 .NET Framework 类型。

使用强类型 .NET Framework 类型

参数应定义为 .NET Framework 类型，以提供更好的参数验证。例如，仅限于一组值中的一个值的参数应定义为枚举类型。要支持统一资源标识符 (URI) 值，请将参数定义为 System.Uri 类型。除自由格式文本属性外，避免对所有属性使用基本字符串参数。

使用一致的参数类型

当多个 cmdlet 使用同一参数时，请始终使用相同的参数类型。例如，如果一个 cmdlet 的 Process 参数是 System.Int16 类型，则请勿将另一 cmdlet 的 Process 参数设置为 System.Uint16 类型。

取 True 和 False 的参数

如果您的参数仅采用 true 和 false，请将参数定义为 System.Management.Automation.SwitchParameter 类型。当在命令中指定开关参数时，它被视为true。如果命令中未包含该参数，Windows PowerShell 会将该参数的值视为 false。不要定义布尔参数。

如果您的参数需要区分 3 个值：$true、$false 和“未指定”，则定义 Nullable 类型的参数。当 cmdlet 可以修改对象的布尔属性时，通常会需要第三个“未指定”值。在这种情况下，“未指定”意味着不更改属性的当前值。

支持参数数组

通常，用户必须对多个参数执行相同的操作。对于这些用户，cmdlet 应接受数组作为参数输入，以便用户可以将参数作为 Windows PowerShell 变量传递到参数中。例如，Get-Process cmdlet 使用一个字符串数组来标识要检索的进程的名称。

支持PassThru参数

默认情况下，许多修改系统的 cmdlet（例如 Stop-Process cmdlet）充当对象的“接收器”并且不返回结果。这些 cmdlet 应实现 PassThru 参数以强制 cmdlet 返回对象。当指定 PassThru 参数时，cmdlet 通过调用 System.Management.Automation.Cmdlet.WriteObject 方法返回一个对象。例如，以下命令停止 Calc (CalculatorApp.exe) 并将生成的进程传递到管道。

Stop-Process -Name CalculatorApp -PassThru

在大多数情况下，Add、Set 和 New cmdlet 应支持 PassThru 参数。

支持参数集

cmdlet 旨在实现单一目的。然而，通常有不止一种方式来描述操作或操作目标。例如，进程可以通过其名称、标识符或进程对象来标识。 cmdlet 应支持其目标的所有合理表示。通常，cmdlet 通过指定一起操作的参数集（称为参数集）来满足此要求。单个参数可以属于任意数量的参数集。有关参数集的详细信息，请参阅 Cmdlet 参数集。

指定参数集时，仅将参数集中的一个参数设置为 ValueFromPipeline。有关如何声明 Parameter 属性的详细信息，请参阅 ParameterAttribute 声明。

使用参数集时，默认参数集由 Cmdlet 属性定义。默认参数集应包括最有可能在交互式 Windows PowerShell 会话中使用的参数。有关如何声明 Cmdlet 属性的详细信息，请参阅 CmdletAttribute 声明。

向用户提供反馈（SD04）

使用本节中的指南向用户提供反馈。此反馈使用户能够了解系统中发生的情况并做出更好的管理决策。

Windows PowerShell 运行时允许用户通过设置首选项变量来指定如何处理每次调用 Write 方法的输出。用户可以设置多个偏好变量，包括确定系统是否应显示信息的变量和确定系统在采取进一步操作之前是否应询问用户的变量。

支持 WriteWarning、WriteVerbose 和 WriteDebug 方法

当 cmdlet 即将执行可能产生意外结果的操作时，该 cmdlet 应调用 System.Management.Automation.Cmdlet.WriteWarning 方法。例如，如果 cmdlet 将覆盖只读文件，则该 cmdlet 应调用此方法。

当用户需要有关 cmdlet 正在执行的操作的一些详细信息时，cmdlet 应调用 System.Management.Automation.Cmdlet.WriteVerbose 方法。例如，如果 cmdlet 作者认为在某些情况下可能需要有关 cmdlet 正在执行的操作的更多信息，则 cmdlet 应调用此信息。

当开发人员或产品支持工程师必须了解是什么破坏了 cmdlet 操作时，cmdlet 应调用 System.Management.Automation.Cmdlet.WriteDebug 方法。 cmdlet 不必在调用 System.Management.Automation.Cmdlet.WriteVerbose 方法的同一代码中调用 System.Management.Automation.Cmdlet.WriteVerbose 方法，因为 Debug 参数同时提供这两种方法信息集。

支持WriteProgress处理耗时较长的操作

需要很长时间才能完成且无法在后台运行的 Cmdlet 操作应通过定期调用 System.Management.Automation.Cmdlet.WriteProgress 方法来支持进度报告。

使用主机接口

有时，cmdlet 必须直接与用户通信，而不是使用 System.Management.Automation.Cmdlet 类支持的各种 Write 或 Should 方法。在这种情况下，cmdlet 应从 System.Management.Automation.PSCmdlet 类派生并使用 System.Management.Automation.PSCmdlet.Host* 属性。此属性支持不同级别的通信类型，包括 PromptForChoice、Prompt 和 WriteLine/ReadLine 类型。在最具体的层面上，它还提供了读取和写入单个键以及处理缓冲区的方法。

除非 cmdlet 专门设计用于生成图形用户界面 (GUI)，否则它不应使用 System.Management.Automation.PSCmdlet.Host* 属性绕过主机。设计用于生成 GUI 的 cmdlet 的一个示例是 Out-GridView cmdlet。

笔记

Cmdlet 不应使用 System.Console API。

创建 Cmdlet 帮助文件 (SD05)

对于每个 cmdlet 程序集，创建一个包含有关 cmdlet 的信息的 Help.xml 文件。此信息包括 cmdlet 的描述、cmdlet 参数的描述、cmdlet 的使用示例等。

代码指南

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

编码参数（SC01）

通过声明用 Parameter 属性修饰的 cmdlet 类的公共属性来定义参数。参数不必是 cmdlet 的派生 .NET Framework 类的静态成员。有关如何声明参数属性的更多信息，请参阅参数属性声明。

支持 Windows PowerShell 路径

Windows PowerShell 路径是规范对命名空间的访问的机制。当您将 Windows PowerShell 路径分配给 cmdlet 中的参数时，用户可以定义充当特定路径快捷方式的自定义“驱动器”。当用户指定这样的驱动器时，可以以一致的方式使用存储的数据，例如注册表中的数据。

如果您的 cmdlet 允许用户指定文件或数据源，则它应该定义 System.String 类型的参数。如果支持多个驱动器，则类型应为数组。参数名称应为 Path，别名为 PSPath。此外，Path 参数应支持通配符。如果不需要支持通配符，请定义 LiteralPath 参数。

如果 cmdlet 读取或写入的数据必须是文件，则 cmdlet 应接受 Windows PowerShell 路径输入，并且 cmdlet 应使用 System.Management.Automation.Sessionstate.Path 属性将 Windows PowerShell 路径转换为文件系统识别。具体机制包括以下方法：

• System.Management.Automation.PSCmdlet.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PSCmdlet.GetUnresolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetUnresolvedProviderPathFromPSPath

如果 cmdlet 读取或写入的数据只是一组字符串而不是文件，则 cmdlet 应使用提供程序内容信息（Content 成员）进行读取和写入。此信息是从 System.Management.Automation.Provider.CmdletProvider.InvokeProvider 属性获取的。这些机制允许其他数据存储参与数据的读写。

支持通配符

如果可能，cmdlet 应支持通配符。 cmdlet 中的许多地方都支持通配符（特别是当参数采用字符串来标识一组对象中的一个对象时）。例如，StopProc 教程中的示例 Stop-Proc cmdlet 定义了一个 Name 参数来处理表示进程名称的字符串。该参数支持通配符，以便用户可以轻松指定要停止的进程。

当对通配符的支持可用时，cmdlet 操作通常会生成一个数组。有时，支持数组没有意义，因为用户可能一次只使用一个项目。例如，Set-Location cmdlet 不需要支持数组，因为用户仅设置单个位置。在这种情况下，cmdlet 仍然支持通配符，但它强制解析到单个位置。

有关通配符字符模式的详细信息，请参阅支持 Cmdlet 参数中的通配符。

定义对象

本节包含定义 cmdlet 对象和扩展现有对象的准则。

定义标准成员

定义标准成员以扩展自定义 Types.ps1xml 文件中的对象类型（使用 Windows PowerShell Types.ps1xml 文件作为模板）。标准成员由名为 PSStandardMembers 的节点定义。这些定义允许其他 cmdlet 和 Windows PowerShell 运行时以一致的方式处理您的对象。

定义用作参数的对象成员

如果您正在为 cmdlet 设计对象，请确保其成员直接映射到将使用它的 cmdlet 的参数。此映射允许将对象轻松发送到管道并从一个 cmdlet 传递到另一个 cmdlet。

cmdlet 返回的现有 .NET Framework 对象经常缺少脚本开发人员或用户所需的一些重要或方便的成员。这些缺失的成员对于显示和创建正确的成员名称尤其重要，以便可以将对象正确传递到管道。创建自定义 Types.ps1xml 文件来记录这些必需的成员。创建此文件时，我们建议采用以下命名约定：.Types.ps1xml。

例如，您可以将 Mode 脚本属性添加到 System.IO.FileInfo 类型，以更清楚地显示文件的属性。此外，您可以向 System.Array 类型添加 Count 别名属性，以允许一致使用该属性名称（而不是 Length）。

实现 IComparable 接口

在所有输出对象上实现 System.IComparable 接口。这使得输出对象可以轻松地通过管道传输到各种排序和分析 cmdlet。

更新显示信息

如果对象的显示未提供预期结果，请为该对象创建自定义 <YourProductName>.Format.ps1xml 文件。

支持明确定义的管道输入 (SC02)

管道中间的实施

实现一个 cmdlet，假设将从管道中间调用该 cmdlet（即，其他 cmdlet 将生成其输入或消耗其输出）。例如，您可能假设 Get-Process cmdlet 因为生成数据而仅用作管道中的第一个 cmdlet。但是，由于此 cmdlet 是为管道中间设计的，因此此 cmdlet 允许管道中的先前 cmdlet 或数据指定要检索的进程。

支持来自管道的输入

在 cmdlet 的每个参数集中，至少包含一个支持管道输入的参数。对管道输入的支持允许用户检索数据或对象，将它们发送到正确的参数集，并将结果直接传递到 cmdlet。

如果 Parameter 属性在其声明中包含 ValueFromPipeline 关键字、ValueFromPipelineByPropertyName 关键字属性或同时包含这两个关键字，则参数接受来自管道的输入。如果参数集中的任何参数均不支持 ValueFromPipeline 或 ValueFromPipelineByPropertyName 关键字，则该 cmdlet 无法有意义地放置在另一个 cmdlet 后面，因为它将忽略任何管道输入。

支持ProcessRecord方法

要接受管道中前面的 cmdlet 中的所有记录，您的 cmdlet 必须实现 System.Management.Automation.Cmdlet.ProcessRecord 方法。 Windows PowerShell 会多次调用此方法，对于发送到您的 cmdlet 的每条记录调用一次。

将单个记录写入管道 (SC03)

当 cmdlet 返回对象时，cmdlet 应在生成对象时立即写入对象。 cmdlet 不应保存它们以便将它们缓冲到组合数组中。然后，接收对象作为输入的 cmdlet 将能够立即处理、显示或处理并显示输出对象。一次生成一个输出对象的 cmdlet 应调用 System.Management.Automation.Cmdlet.WriteObject 方法。批量生成输出对象的 cmdlet（例如，因为底层 API 返回输出对象数组）应调用 System.Management.Automation.Cmdlet.WriteObject 方法，并将其第二个参数设置为 true 。

使 Cmdlet 不区分大小写并保留大小写 (SC04)

默认情况下，Windows PowerShell 本身不区分大小写。然而，由于它处理许多预先存在的系统，Windows PowerShell 确实保留了大小写，以便于操作和兼容性。换句话说，如果以大写字母提供字符，Windows PowerShell 会将其保留为大写字母。为了使系统正常工作，cmdlet 需要遵循此约定。如果可能的话，它应该以不区分大小写的方式运行。但是，它应该保留稍后在命令或管道中出现的 cmdlet 的原始大小写。

参见

所需的开发指南

咨询开发指南

编写 Windows PowerShell Cmdlet