通过

为 SharePoint Management Shell 编写 Cmdlet 的关键概念

  • 项目

上次修改时间： 2009年10月1日

适用范围： SharePoint Foundation 2010

本文内容
Cmdlet 参数
管道和传输
PipeBind 对象

有些重要概念对编写 Windows PowerShell cmdlet for SharePoint 会有所帮助。以下内容对支持 Windows PowerShell for SharePoint 实现的一些重要概念进行概述。

Cmdlet 参数

虽然用户以字符串的形式输入参数值，但 Windows PowerShell 会根据参数定义尝试将这些字符串值转换为其正确类型。因此，编写的 cmdlet 必须提供一种方法来验证传递到 cmdlet 中的参数值是否为有效数据类型。

避免传递字符串类型或整数类型的参数，除非该类型的所有值对于参数都有效。相反，应定义一个用于对参数的范围和格式做出进一步限制的类。此外，可以通过使用参数类型的 Parse(String) 方法来验证参数。Windows PowerShell 支持使用 Parse() 方法将字符串类型转换为其他数据类型。

管道和传输

除了 Cmd.exe 的功能之外，Windows PowerShell 提供的最重要的改进之一是，Windows PowerShell 本身具有将一系列简单 cmdlet 合并为一个管道 的能力。管道是一系列命令或一个命令序列。利用管道，可以将一个命令的输出对象作为输入对象传递（或传输）给后续命令。利用命令管道，cmdlet 开发人员能够创建复杂而灵活的命令管道，可以对其输出对象进行保存和重用。

传输过程依赖于 cmdlet 的行为，在此过程中，输出对象将写入到由 Windows PowerShell 控制的对象管道。这将使 Windows PowerShell 能够尝试将管道中的对象与后续 cmdlet 的参数相匹配。

若要进行传输，前面的 cmdlet 的输出与后面的 cmdlet 的输入之间必须存在明确的相关性。此相关性可以处于对象级别，其中管道中的前面的对象与后续 cmdlet 的参数相匹配。（这一过程称作按值传输。）或者，相关性可以处于属性级别，其中管道中的前面的对象单词属性与后续 cmdlet 的参数相匹配。

按值传输

按值传输是指下游 cmdlet 将通过管道使用整个对象，前提是该对象属于正确类型。按值传输通常是使用 Set cmdlet 来执行的，在此过程中，将传递整个对象来保存从数据源进行的读取操作；也可以使用支持克隆的 New cmdlet 来执行此过程。当下游 cmdlet 无法重新读取由上游 cmdlet 输出的对象时，也可以使用按值传输。

PipeBind 对象

PipeBind 对象是 Windows PowerShell for SharePoint 特有的特殊对象，这些对象提供为 SharePoint Foundation 优化的专用参数集的第二个层。

在将 SharePoint Foundation 2010 对象用作 cmdlet 参数时，应使用适当的 PipeBind 对象来代替 SharePoint 对象。这样做非常重要，因为这可让 cmdlet 的用户按照适当的方式指定参数的值。PipeBind 对象实际表示一个位于参数的用户输入与参数对象本身之间的层。

例如，使用了 SPSite 参数的 cmdlet 可以采用 SPSite 对象本身，或该网站集的 GUID 标识符或 URL。这是 SPSitePipeBind 对象的作业，用于确保向实际 SPSite 对象呈现 cmdlet 本身，不管 Windows PowerShell 运行时呈现了哪一种表示形式。

备注

PipeBind 类不应绑定到特定的 cmdlet，而是应在所有 cmdlet 之间共享。在编写 PipeBind cmdlet 时，请确保它不会对 cmdlet 实施者有任何特定的要求。

实现 PipeBind 对象

在实现 PipeBind 对象时，必须从 SPCmdletPipeBind<TCmdletObject> 基类派生。若要实现此类，请执行以下操作：

  1. 实现类构造函数。

  2. 重写对象的 Read() 方法。

PipeBind 类应至少具有一个构造函数，但它可以具有多个构造函数。当 Windows PowerShell 尝试绑定参数时，它会循环访问指定参数的公共构造函数集并会尝试将参数输入与 PipeBind 构造函数相匹配。这意味着，对于表示参数的输入的每种可能类型，都必须有与之对应的构造函数。

SPCmdletPipeBind<TCmdletObject> 对象的 Read() 方法将返回 SharePoint Foundation 对象模型中定义的对象类型：public virtual TCmdletObject Read()。

请注意，必须为每个 PipeBind 对象实现重写 Read() 方法，以确保正确检索到对象模型对象。可以根据需要创建对 Read() 方法的附加重写以提供所需参数。

Cmdlet 标识和原子性

Cmdlet 必须具有一个 Identity 参数，该参数指定对其执行操作的对象。在编写 cmdlet 时，必须指定一个唯一标识符作为 Identity 参数的值。但请注意，新的 cmdlet 最初不具有标识符；它仅在实例化对象后具有标识符。

Cmdlet 执行应模拟原子性。也就是说，cmdlet 要么成功并使系统进入更改后的状态，要么完全失败并将系统返回执行前所具有的状态。换言之，cmdlet 必须提供一种方法，以便在发生故障时还原系统状态。