SharePoint Foundation Cmdlet 的开发准则
上次修改时间： 2010年3月24日
适用范围： SharePoint Foundation 2010
为 SharePoint 编写 Windows PowerShell cmdlet（即从 SPCmdlet 基类派生的自定义 cmdlet）时，请务必使用特定于 SharePoint 的设计方针以确保您的 cmdlet 与 SharePoint cmdlet 库中的核心 cmdlet（在 SharePoint Management Shell 中公开）完全兼容。此外，SharePoint Foundation 还推荐了设计模式，以确保与您的 SharePoint 部署具有全面的互操作性。
用于创建 SharePoint Cmdlet 的方法
设计特定于 SharePoint cmdlet 时，请始终执行以下操作：
定义 cmdlet 名词。
定义 cmdlet 名词属性。
定义 cmdlet 动词和参数。
定义 cmdlet 错误、进度和管道。
如果遵循此流程，您将为要开发的组件或功能定义一个完善的 cmdlet 集。
定义 cmdlet 名词
定义 cmdlet 名词时，务必清楚您的功能将管理的内容。将名词视为系统管理员将管理的项。它们可能是 SharePoint 对象（如 SPSite 或 SPWeb 对象），也可能是已安装的功能（如 SPFeature 对象）、表单模板或 Web 部件。
作为一般规则，最好多使用具有较少属性的名词，少使用具有很多属性的名词。建议不要使用属性个数超过 15 个的任何名词。
确定要向系统管理员公开的非永久性运行时状态信息。还要确定必须返回给系统管理员的可能是非永久性的状态信息（例如，服务的运行状态）。
评估是否应将新定义的名词拆分为两个或多个不同的名词。为语义上不同的项创建不同的名词。使用功能或组件规范来确定名词是否涉及多个概念或功能。
如果名词涉及多个数据源（物理或逻辑），请将该名词沿数据源边界拆分。仅确定单个数据库或 SharePoint 对象中逻辑独立的永久性属性子集。大多数情况下，此子集应成为单独的名词，但前提是：生成的名词是逻辑独立的，而且可以将这些名词明确地理解为不同的实体（即，可以轻松区分它们），而不会使系统管理员感到困惑。
对于由多个名词使用的每个永久性的数据源对象，请将这些名词统一为一个名词。同时，还要统一那些主要区别是具有不同生命周期的名词，原因是可以单独管理这些名词的创建和删除。
定义 Cmdlet 名词属性
定义 Identity 属性。所有名词必须具有 Identity 属性，该属性的值唯一且不可变，例如 GUID。
为名词创建管道绑定。该管道绑定应绑定可以唯一标识该对象的所有属性。
为名词定义完整的公共属性集。将名词定义视为公共 API。返回名词的实例时，将在命令行中公开所有相关的公共属性。
定义每个属性的数据类型。属性应为强类型，以便可以将格式验证代码附加到属性类型而不是附加到名词。例如，表示电子邮件地址的属性应为 EmailAddress 类型而不是 String 类型。
标识非典型的大型属性。确保将非常大的属性（超过 10 KB）拆分为两个或多个属性。
标识具有很多元素的属性的集合（例如，包含 100 多个元素的集合）。删除这种大型属性集合，并将元素拆分为多个名词。然后，为新名词定义 New、Remove、Get 和 Set 动词。
例如，请考虑这种情况：Users 是 SPWeb 对象的一个属性，该属性可能具有很多元素。为了避免出现问题，请创建一个名为 SPUser 的单独名词来代表列表中的一个元素，然后添加关联的 New、Remove、Get 和 Set 动词。
定义 Cmdlet 动词和参数
确定对名词应用哪些基本动词（Get、Set、New 和 Remove）。系统管理员至少必须能够获取设置并能够更改（或 Set）设置。此外，管理员可能还需要创建新实例 (New) 以及删除现有实例 (Remove)。
定义 Get cmdlet 的行为
如果不指定参数，动词 Get 必须检索所有实例，并且必须通过将实例写入 Windows PowerShell 管道来实现此操作。但是，任何可能返回大型结果集的操作都应包含一个指定了默认限制的 Limit 参数。当然，如果通过此方式限制结果集，则必须提醒用户受限制的结果集中可能排除了额外的结果。
动词 Get 必须具有 Identity 参数。如果指定该参数，相应的 cmdlet 必须仅返回与该标识相关联的实例。如果指定的标识不唯一，cmdlet 应返回具有指定标识值的所有实例。
动词 Get 可以具有其他可选筛选参数。例如，cmdlet Get-SPSite 可以具有 ContentDatabase 参数，以将结果集限制为指定内容数据库中的网站集。此外，如果 cmdlet 返回本地（即特定于计算机的）配置信息，动词 Get 必须具有 Server 参数。
定义 Set cmdlet 的行为
动词 Set 必须具有 Identity 参数以标识要更改的实例。该参数必须能够接受标识（如 GUID）或名称。如果指定了名称，并且该名称与多个实例匹配，则 cmdlet 必须返回错误。
Set cmdlet 的 Identity 参数必须接受管道输入。
动词 Set 必须公开使用相应的 Get cmdlet 接收的名词的所有可写属性，不包括那些设置时产生负面影响的属性。
动词 Set 必须具有可选 Instance 参数，以表示这种名词类型的完整实例。Instance 参数必须接受管道输入（按值）。
定义 New cmdlet 的行为
动词 New 必须接受名词的可写属性的受限子集作为参数。其余属性应设置为默认值。此外，New cmdlet 必须将新创建的实例对象返回到管道，以便管道中更深的 cmdlet 可以作用于新实例。
定义 Remove cmdlet 的行为
Remove cmdlet 必须具有可以使用标识值或名称的 Identity 参数。如果指定了名称，并且该名称与多个实例匹配，cmdlet 必须返回错误。
Identity 参数必须接受管道输入。此外，任何破坏性的操作都必须支持 Confirm 和 WhaIf 参数。做到这一点很容易，因为 Windows PowerShell 和 SharePoint Foundation 2010 的基类提供了支持这些参数的手段。
为名称确定和定义其他动词。
例如，名词 SPContentDatabase 可能需要动词 Mount 来支持安装指定的数据库。使用经过测试的管理方案和使用案例来支持选择适当的动词。
请记住，所有其他 cmdlet 都必须具有接受管道输入的 Identity 参数。Identity 参数必须接受对象的标识（管道绑定）。此外，任何破坏性的操作都必须支持 Confirm 和 WhaIf 参数。
确定具有潜在负面影响的属性。
具有潜在负面影响的属性可能需要其他操作来缓解负面影响。这些额外的缓解 cmdlet 必须具有接受管道输入的 Identity 参数。
对于您定义的每个 cmdlet，请执行以下操作：
(a) 确定 cmdlet 的先决条件列表。例如，如果某个 cmdlet 只能在某些系统状态下执行，则该 cmdlet 必须验证满足所有状态先决条件后才会执行。
(b) 确定操作列表。指定 cmdlet 能够执行的操作的完整列表。cmdlet 必须执行这些操作，然后验证它们。此操作列表包含 cmdlet 的功能细目。
定义 Cmdlet 错误、进度和管道
确定所有错误情况和错误状态行为。即，列出 cmdlet 可能出错的所有情况。然后描述针对每种错误情况的可能行为。cmdlet 必须提供基本的错误管理。
发生错误时，cmdlet 必须清除部分更改，并且必须返回有意义的错误消息（如果有本地化版本则返回本地化的错误信息）。此外，cmdlet 必须确定并显示系统管理员如何从任何错误情况恢复。
区分终止错误和非终止错误。
标识长期运行的操作。如果 cmdlet 完成某项操作的时间预期平均超过 20 秒，则 cmdlet 必须提供进度信息以避免出现被挂起的操作。
确保 cmdlet 将其返回对象直接写入管道。避免将检索的对象缓存到内部数组。写入管道将允许下游 cmdlet 作用于管道中前面的对象，而不出现延迟。
组合类似参数。将 cmdlet 限制为 16 个参数（不包括 Identity 和 Name 参数）。如果很少调用对象方法，并且存在对象模型方法，则不需要 cmdlet 参数。如果可以将很多参数组合在一起，则可以编写一个接受该组对象的参数。