SharePoint 的 Feature（功能）

http://msdn.microsoft.com/zh-cn/magazine/cc163428.aspx

 

Ted Pattison

代码下载位置: OfficeSpaceFeature2007_05.exe (190 KB)
Browse the Code Online

 目录

“功能”是什么？
功能的结构
功能部署与激活
扩展功能
自定义应用程序页
总结

在上期 Office Space 专栏中，我讨论了 Office Open XML 文件格式。 我还特别介绍了如何使用由 Microsoft .NET Framework 3.0 提供的打包 API 编写代码隐藏的 ASP.NET 页，从而为 Microsoft® Word 生成 .docx 文件。 本期专栏中，我将在上期已经介绍的内容的基础上继续探讨如何使用 Office Open XML 文件格式。 我还将介绍如何将这些代码集成到既可在 Windows® SharePoint® Services (WSS) 3.0 中部署又可在 Microsoft Office SharePoint Server (MOSS) 2007 中部署的业务解决方案中。

本月 Office Space 专栏的重点是介绍将用于使用 WSS 和 MOSS 创建业务解决方案的基本构造块。 我会解释 WSS“功能”是什么，并介绍如何生成一个可自动创建网站内新的列表和文档库的 WSS“功能”。 在这个过程中，我会将一个自定义应用程序页添加到该自定义业务解决方案中。 其中包含了从 SharePoint 列表中的数据生成 Word 文档并将这些文档保存在 SharePoint 文档库中所需的 Visual Basic® 代码。

“功能”是什么？

开发针对 WSS 和 MOSS 的自定义业务解决方案时，需要做的第一件事是确切了解“功能”（这里所指的不是一般的功能集）。 这里的功能是指已添加到 WSS 3.0 中的一种新的以开发人员为中心的创新。 基本上来说，这提供用于定义网站元素的机制，这些网站元素可在目标网站或目标网站集合的上下文中自动激活。 功能可以定义的元素类型包括列表实例、列表类型、菜单命令、页面模板、页面实例、事件处理程序和工作流。 我在本专栏中所讨论的示例涉及一个名为 OfficeSpaceFeature 的功能，该功能用于创建列表和文档库并将自定义菜单项添加到标准 WSS“网站操作”菜单，从而使用户能够导航到自定义应用程序页。

任何功能都包含一个在每个前端 Web 服务器文件系统的专用 WSS 系统目录中创建的目录。 该功能目录包含一个或多个基于 XML 的文件（该文件使用协作应用程序标记语言 (CAML)）。 按照惯例，每个功能目录都包含一个名为 feature.xml 的清单文件。此文件用于定义功能的高级属性，如其 ID 及其用户友好的 Title。

除 feature.xml 文件外，每个功能通常还都包含一个或多个额外的 XML 文件（例如 elements.xml），用于定义构成该功能的实际元素。 该目录还可能包含针对列表定义和页面模板等内容以及针对图像、级联样式表和 JavaScript 等资源的其他类型的文件。 我的示例中的功能目录还包含了一个用作文档库文档模板的文件。

帮助您迅速了解功能的一个好方法是研究基本 WSS 安装所包含的标准功能集。 图 1 显示的就是安装 WSS 后的 FEATURES 目录外观的一个示例。 可以看到，每个功能都有自己的目录。 安装 MOSS 后，FEATURES 目录将有很大相同，因为其中将包含 100 多个功能。

图 1 标准 FEATURES 目录 (单击该图像获得较大视图)

创建了包含构成功能的所有文件的目录后，您必须使用 WSS 在服务器场级范围安装该目录。 使用 WSS 安装某一功能后，即可使用一个可通过“网站设置”页面访问的管理页面在网站或网站集合上下文中激活该功能。

本专栏的下载中包含了一个名为 OfficeSpaceFeature 的 Visual Studio® 项目，其中包含了一个同名的功能。 图 2 显示了一个解决方案资源管理器视图，借此您可以了解在通过创建 Visual Studio 项目来开发自定义的 WSS 或 MOSS 功能时会涉及哪些类型的文件。 本专栏中的示例是作为 Visual Basic DLL 项目创建的。 当然，如果您愿意，也可以使用 C# DLL 项目。 程序集 DLL 中的托管代码必须使用强名称进行编译，并且必须安装在全局程序集缓存 (GAC) 中，以便能够用于功能的事件处理程序。

图 2 OfficeSpaceFeature 

功能的结构

在研究 feature.xml 文件之前，要注意此功能的文件必须部署在名为 FEATURES 的 WSS 系统目录下它们各自的专用目录中。 FEATURES 目录位于名为 TEMPLATE 的另一个 WSS 系统目录中，如图 1 所示。 鉴于功能部署要求，有必要在用于开发 WSS 功能的 Visual Studio 项目中创建一个并行的文件夹层次结构。 这样可以更轻松地将功能文件复制到正确位置并在开发时对它们进行测试。

首先要将一个名为 TEMPLATE 的文件夹添加当前项目的根目录中。 然后在 TEMPLATE 中另外创建一个名为 FEATURES 的目录。 最后，在 FEATURES 目录中再创建一个以功能项目名称命名的目录。这样，项目和目录的名称都是 OfficeSpaceFeature，如图 2 所示。

现在我们来看 feature.xml 文件中的 CAML 内容。 feature.xml 文件用作功能清单，您可以在此指定功能本身的高级属性的定义信息。 我的示例功能的 feature.xml 文件如图 3 所示。

可以看到，定义功能的 Feature 元素包含 Id、Title、Description、Version、Scope、Hidden 和 ImageUrl 等多个属性。 而您必须为 Id 属性创建新的 GUID，才能唯一标识该功能。 您可以使用用户友好文本创建功能的 Title 和 Description 属性。 这些属性在 WSS 管理页面上直接显示给用户，WSS 管理页面用于激活和停用功能。

Scope 定义了可以激活和停用功能的上下文。 我正在创建的功能的范围等于 Web，这意味着可以在网站的上下文中激活和停用该功能。 不过，如果将 Scope 值指定为 Site，则可以在网站集合范围内激活和停用功能。 另外两个可用于定义功能的范围是 WebApplication 范围和 Farm 范围。

可以看到，Hidden 属性的值为 FALSE。 这意味着在服务器场内安装功能后，可能需要激活该功能的用户才能够看到它。 如果将所创建功能的 Hidden 属性值设置为 TRUE，则该功能在显示给用户的可用功能列表中将被隐藏。 必须通过自定义代码或通过另一个功能的激活依赖项，从命令行激活隐藏功能。

您可能已经注意到 ImageUrl 属性值指向了基本 WSS 安装中的一个图形图像。 此图像在 UI 中将显示在该功能旁边。

图 3 中所显示的 feature.xml 文件的最后一部分是 ElementManifests 元素。 该元素包含内部 ElementManifest 元素，这些元素会引用用于定义功能构成元素的其他 XML 文件。 在这种情况下，只有一个 ElementManifest 元素使用位置属性来指向名为 element.xml 的文件。

请注意，在基于 CAML 的文件（如 feature.xml 和 elements.xml）中添加和修改 XML 时，需要添加对 XML 架构驱动的 IntelliSense® 的支持。 TEMPLATE 目录中有一个名为 XML 的目录，其中包含了若干个 XML 架构，并且有一个架构名为 wss.xsd。如果将此架构文件与 feature.xml 和 elements.xml 等功能文件相关联，Visual Studio 将提供 IntelliSense，从而更容易创建自定义功能。

现在我们将详细探讨 element.xml 文件中的内容。 假定每当激活功能时，您都需要实例化文档库。则可以创建一个类似于图 4 所示的 elements.xml 文件。

 Figure 4 Elements.xml 示例文件

复制代码

<Elements xmlns=”http://schemas.microsoft.com/sharepoint/”>
            <ListInstance
            FeatureId=”00BFEA71-E717-4E80-AA17-D0C71B360101”
            TemplateType=”101”
            Id=”CustomerLetters”
            Description=”Letters sent to customers”
            OnQuickLaunch=”True”
            Title=”Customer Letters”
            Url=”CustomerLetters”>
            </ListInstance>
            <Module Name=”LetterTemplate” List=”101” Url=”CustomerLetters/Forms”>
            <File Url=”LetterTemplate.docx” Type=”GhostableInLibrary” />
            </Module>
            <!-- more elements to come... -->
            </Elements>
            

此处显示的第一个元素（ListInstance 元素）用于创建列表或文档库的实例。 请注意，ListInstance 包含了一个 FeatureId 和 TemplateType，用于指向特定列表类型和定义该列表类型的功能的 ID。 在本例中，我使用的是标准 WSS 文档库类型，其 TemplateType 标识符为 101，用于创建标题为 Customer Letters 的新文档库。 ListInstance 元素下还有一个 Module 元素，它包含一个内部 File 元素。 此 File 元素用于为文档库提供文档模板。 更准确地说，此 File 元素为 WSS 提供了用于将功能目录中名为 LetterTemplate.docx 的文件复制到 WSS 网站的指令。 这将使用户可以访问该文件。

尽管 elements.xml 中的声明性逻辑为您创建 WSS 网站内元素提供了很大帮助，但与此同时经常还需要辅以编程逻辑。 例如，我创建了一个新的文档库并提供一个文件作为文档模板。 但是，若要将文档模板与文档库相关联，还需要提供一些针对 WSS 对象模型进行编程的额外代码。

在我的 feature.xml 文件中，您会注意到 Feature 元素包含两个名称分别为 ReceiverAssembly 和 ReceiverClass 的属性。 这些属性被配置为指向一个称为功能接收器的托管类，该托管类将提供事件处理程序。 在安装或激活功能以及卸载或停用功能时，将会激发功能接收器类中的事件处理程序。 通过创建从 SPFeatureReceiver 类继承的类来创建功能接收器，如图 5 所示。

 Figure 5 从 SPFeatureReceiver 继承的类

复制代码

Imports Microsoft.SharePoint
            Public Class FeatureReceiver : Inherits SPFeatureReceiver
            Public Overrides Sub FeatureActivated( _
            ByVal properties As SPFeatureReceiverProperties)
            ‘*** fires when feature is activated
            End Sub
            Public Overrides Sub FeatureDeactivating( _
            ByVal properties As SPFeatureReceiverProperties)
            ‘*** fires when feature is deactivated
            End Sub
            Public Overrides Sub FeatureInstalled( _
            ByVal properties As SPFeatureReceiverProperties)
            ‘*** fires when feature is installed
            End Sub
            Public Overrides Sub FeatureUninstalling( _
            ByVal properties As SPFeatureReceiverProperties)
            ‘*** fires when feature is uninstalled
            End Sub
            End Class
            

在示例中，我只提供了 FeatureActivated 事件处理程序中的代码。 这些代码使用 WSS 对象模型将文档模板与 Customer Letters 文档库相关联。 在该事件处理程序中，此关联是通过获得对当前网站的 SPWeb 引用然后获得对目标文档库的 SPDocumentLibrary 引用而实现的。 这样一来，就可以通过调用 Update 方法来修改 DocumentTemplateUrl 属性并保存所做的修改，如下所示：

复制代码

Public Overrides Sub FeatureActivated( _
            ByVal properties As SPFeatureReceiverProperties)
            Dim site As SPWeb = CType(properties.Feature.Parent, SPWeb)
            Dim libLetterTemplates As SPDocumentLibrary
            libLetterTemplates = CType(site.Lists(“Customer Letters”), _
            SPDocumentLibrary)
            Dim templateUrl As String = _
            “CustomerLetters/Forms/LetterTemplate.docx”
            libLetterTemplates.DocumentTemplateUrl = templateUrl
            libLetterTemplates.Update()
            End Sub
            

功能部署与激活

创建 feature.xml 文件和 elements.xml 文件之后，接下来需要安装我的功能以便进行测试。 安装我的功能需要四个步骤。 首先，必须将名为 OfficeSpaceFeature.dll 的程序集文件安装到 GAC 中。 然后必须将 OfficeSpaceFeature 目录复制到 WSS 系统的 FEATURES 目录。 再下一步是运行 Stsadm.exe，以便使用 WSS 来安装功能。 最后需要在 WSS 网站上下文中激活该功能。

可以通过在我的 OfficeSpaceFeature 项目的根目录中创建一个名为 install.bat 的批处理文件并添加图 6 中所示的命令行指令自动执行前三步。 如果我愿意，也可以通过使用 Stsadm.exe 实用工具运行 ActivateFeature 操作来自动执行第四步。 但是，我没有在示例中这样做，因为我想让您了解手动激活功能的过程，用户将在 WSS 用户界面中完成这些操作。

 Figure 6 用于实现自动安装的命令

复制代码

@SET TEMPLATEDIR=”c:\Program Files\Common Files\Microsoft Shared\
            web server extensions\12\TEMPLATE”
            @SET STSADM=”c:\Program Files\Common Files\Microsoft Shared\
            web server extensions\12\bin\stsadm.exe”
            @SET GACUTIL=”c:\Program Files\Microsoft Visual Studio 8\
            SDK\v2.0\Bin\gacutil.exe”
            Echo Installing OfficeSpaceFeature.dll in GAC
            %GACUTIL% -if bin\debug\OfficeSpaceFeature.dll
            Echo Copying source files to WSS \TEMPLATE directory
            xcopy /e /y TEMPLATE\* %TEMPLATEDIR%
            Echo Installing feature with WSS
            %STSADM% -o installfeature -filename  OfficeSpaceFeature\feature.xml -force
            Echo Restarting IIS worker process
            IISRESET
            

在将指令添加到 install.bat 文件之后，我对 Visual Studio 进行了配置，使它在我每次重新生成 OfficeSpaceFeature 项目时运行该文件。 配置过程是：先转到“项目属性”中的“生成事件”选项卡，然后添加以下生成后事件命令行指令：

复制代码

cd $(ProjectDir)
            Install.bat
            

第一行用于将当前目录更改为项目目录的当前目录。 第二行用于运行批处理文件，以便将功能文件复制到正确位置，然后使用命令行 Stsadm.exe 实用工具的 InstallFeature 操作来安装功能。

现在已经正确地安装了该功能，接下来就可以在网站上下文中激活它了。 通过导航到“网站设置”页面，您可以在 WSS 或 MOSS 服务器场中的任何网站中激活该功能。 在“网站管理”部分下，单击名为“网站功能”的链接。此时您应进入如图 7 所示的一个页面。 请注意，装有 MOSS 的服务器场中的功能会比只装有 WSS 的服务器场中的功能多很多。

图 7 激活和停用网站功能 (单击该图像获得较大视图)

OfficeSpaceFeature 的标题和描述会显示在“网站功能”页上，因此可以轻松找到 OfficeSpaceFeature 并单击“激活”按钮。 此时，当前网站应提供在 elements.xml 中使用声明性逻辑定义的所有元素。 接下来，WSS 会从 GAC 中加载接收器程序集，创建接收器类的一个实例，并执行接收器类的 FeatureActivated 方法。

我的示例相当简单。 不过，如果希望，您也可以在 FeatureActivated 中更加复杂地组合声明性 CAML 元素和 WSS 对象模型代码。

扩展功能

如果仔细检查 elements.xml 文件，您会发现另一个 ListInstance 元素。 该元素用于通过内置的 WSS Contacts 列表类型创建名为 Customers 的列表。 该 ListInstance 还说明了如何向列表添加几个默认项从而提供某些示例客户数据。

至此我已经介绍了如何使用声明性 CAML 逻辑来创建列表和文档库。 现在我需要指出的是，您也可以在针对 WSS 对象模型进行编程的功能激活事件中使用自定义代码创建列表或文档库。

示例功能在 FeatureActivated 事件处理程序中包含的代码，可用于从名为 Letter Templates 的标准 WSS 自定义列表类型创建另一个列表。 从标准 WSS 自定义列表类型创建新的列表时，该列表会自动包含一个名为 Title 的字段。 我的代码还会创建一个名为 Body 的列，该列会使用 WSS 对象模型来添加一些列表项，这些列表项提供必要数据作为创建 Customer Letters 的模板。相应的代码如图 8 所示。

 Figure 8 创建列表和添加新列

复制代码

Dim template As SPListTemplate = site.ListTemplates(“Custom List”)
            Dim listLetterTemplatesID As Guid
            listLetterTemplatesID = site.Lists.Add(“Letter Templates”, “”, template)
            Dim listLetterTemplates As SPList = site.Lists(listLetterTemplatesID)
            listLetterTemplates.Fields.Add(“Body”, SPFieldType.Text, True)
            listLetterTemplates.OnQuickLaunch = False
            listLetterTemplates.Update()
            Dim newLetterTemplate As SPListItem
            newLetterTemplate = listLetterTemplates.Items.Add()
            newLetterTemplate(“Title”) = “Initial Greeting”
            newLetterTemplate(“Body”) = “Thanks for your recent interest in Litware.”
            newLetterTemplate.Update()
            newLetterTemplate = listLetterTemplates.Items.Add()
            newLetterTemplate(“Title”) = “Follow Up”
            newLetterTemplate(“Body”) = “Thanks for your recent purchase.”
            newLetterTemplate.Update()
            

自定义应用程序页

了解功能的概念以及如何使用功能很重要，但还需要了解一个用于设计和开发 WSS 和 MOSS 解决方案的基本构造块。 WSS 体系结构支持一种特殊类型的页，即应用程序页。 标准的“网站设置”页 (settings.aspx) 就是应用程序页的一个典型例子。 对于每个前端 Web 服务器都部署一次 settings.aspx 页，但它可以通过 WSS 服务器场中的任何网站进行访问。

应用程序页部署在前端 Web 服务器的文件系统上，作为物理文件，其所在目录的路径为：

复制代码

%PROGRAMFILES%\common files\microsoft shared
            \web server extensions\12\TEMPLATE\LAYOUTS
            

每当 WSS 提供新的 Web 应用程序时，它都会将实际的 LAYOUTS 目录映射到名为 _layouts 的虚拟目录。 利用这一映射方案以及一些附加的处理逻辑，WSS 运行时使用户可以在服务器场内任一网站的上下文中访问各个应用程序页。 例如，假定 WSS 服务器场中有三个可通过以下三个 URL 访问的不同网站：

复制代码

http://Litwareinc.com
            http://Litwareinc.com/sites/Vendors
            http://Litwareinc.com:1001/sites/Accounting
            

通过将 _layouts 目录中某应用程序页的相对路径添加到网站 URL 的末尾，即可访问该应用程序页。 例如，可以使用以下任何一个 URL 访问“网站设置”页：

复制代码

http://Litwareinc.com/_layouts/settings.aspx
            http://Litwareinc.com/sites/Vendors/_layouts/settings.aspx
            http://Litwareinc.com:1001/sites/Accounting/_layouts/settings.aspx
            

由于服务器场级应用程序页只有一个版本，因此可将其编译为一个 DLL 并一次加载到内存中。 您始终都不用担心不同网站的某个应用程序页会有不同的版本。 此外，应用程序页不易受到来自有权限自定义网页的用户的攻击。 因此，WSS 不会禁止这些用户包含内联代码。

WSS 团队广泛使用应用程序页来提供用于设置和管理网站及其内部元素的众多标准功能。 WSS 还支持为自定义业务解决方案自定义应用程序页。 本月的专栏示例中包含了一个名为 LetterGenerator.aspx 的自定义应用程序页，其部署与 LAYOUTS 目录中任何其他应用程序页的部署没有什么不同。

请注意，LetterGenerator.aspx 不直接部署在 LAYOUTS 目录中，而是部署在 LAYOUTS 目录中一个名为 OfficeSpace 的目录中。 最好是在 LAYOUTS 目录中创建您自己的目录来承载自定义应用程序页，这样可以避免任何可能的命名冲突。

应用程序页是一种特殊类型的 ASP.NET 页，通常从名为 LayoutsPageBase 的基类继承并链接到 WSS 团队创建的名为 application.master 的标准母版页。 图 9 给出了经典的 Hello World 自定义应用程序页的一个示例。

 Figure 9 Hello World 自定义应用程序页

复制代码

<%@ Assembly Name=”[Full assembly name for Microsoft.SharePoint]” %>
            <%@ Page Language=”VB” MasterPageFile=”~/_layouts/application.master”
            Inherits=”Microsoft.SharePoint.WebControls.LayoutsPageBase” %>
            <%@ Import Namespace=”Microsoft.SharePoint” %>
            <script runat=”server”>
            Protected Overrides Sub OnLoad(e As EventArgs)
            MyBase.OnLoad(e)
            ‘*** get current site and web objects through WSS object model
            Dim siteCollection As SPSite = SPContext.Current.Site
            Dim site As SPWeb = SPContext.Current.Web
            ‘*** now program against WSS objects within the current site
            lblDisplay.Text = “Current site: “ & site.Title
            End Sub
            </script>
            <asp:Content ID=”Main” runat=”server”
            contentplaceholderid=”PlaceHolderMain” >
            <!-- ADD HTML elements and controls here for page content -->
            <asp:Label ID=”lblDisplay” runat=”server” />
            </asp:Content>
            

可以看到，您可以创建包含标准 ASP.NET 控件以及标准 ASP.NET 页重写（如 OnLoad）代码的应用程序页。 您还可以添加程序集引用。 如果向 Microsoft.SharePoint.dll 中添加引用，则可以通过 SPContext 类获得引用，然后针对当前网站集合和当前网站进行编程，如图 9 中所示。

将自定义应用程序页添加到解决方案后，您需要为用户提供导航到该解决方案方法。 通过将 CustomAction 元素添加功能中，您可以提供链接或菜单项。 下面是 OfficeSpaceFeature 示例中用于将菜单项添加到“网站操作”下拉菜单中的 CustomAction 元素示例：

复制代码

<CustomAction
            Id=”OfficeSpaceLetterGenerator”
            GroupId=”SiteActions”
            Location=”Microsoft.SharePoint.StandardMenu”
            Sequence=”1001”
            Title=”OfficeSpace Letter Generator”
            Description=”Create letter using Open XML”
            ImageUrl=”/_layouts/images/crtpage.gif” >
            <UrlAction Url=”~site/_layouts/OfficeSpace/LetterGenerator.aspx”/>
            </CustomAction>
            

该 CustomAction 元素用于将自定义菜单项添加到标准“网站操作”菜单。 CustomAction 元素中的 UrlAction 元素提供了一个 Url 属性，其中带有我的自定义应用程序页的相对路径。 分配给 Url 属性的字符串值具有一个 ~site 形式的动态标记。 运行时 WSS 会将它替换为当前网站的实际路径。

用户选择自定义菜单项时，他们会被重定向到名为 LetterGenerator.aspx 的自定义应用程序页，该页显示图 10 中所示的用户界面。 此页 OnLoad 方法中的代码用所需的客户和信类型填充两个列表框；使用 WSS 对象模型从在功能激活过程中创建的两个列表中提取数据。 此外还有两个命令按钮，通过它们可以使用我在上期 Office Space 专栏中讨论的代码以两种不同的方法将 Customer Letters 创建为 .docx 文件。

图 10 自定义应用程序页 (单击该图像获得较大视图)

用户单击其中任一命令按钮时，事件处理程序都会运行代码并生成使用 Office Open 文件格式的信。 这里的代码与我在上期专栏中所述的代码几乎完全相同。 唯一不同的是用于命名该文件并以 Customer Letters 为名将该文件保存在 WSS 文档库中的代码。

此示例阐释了使用 Office Open XML 文件格式自动创建 Customer Letters 的方法以及 WSS 和这些文件格式之间的协同。

创建新的 .docx 文件后，需要将其放在某个地方。 WSS 为存储文档提供了一个好场所，在协作环境中工作的团队可在此对其进行版本控制和访问。 图 11 显示了已激活我的 OfficeSpaceFeature 的某个网站中的 Customer Letters 文档库。

图 11 Customer Letters 文档库 (单击该图像获得较大视图)

总结

本月的专栏介绍了功能和自定义应用程序页 — 用于设计和实施 WSS 和 MOSS 解决方案的两个基本构造块。 此时，您应该清楚如何开始进行开发和测试了。 在下期的 Office Space 专栏中，我将讨论如何打包解决方案（例如我刚刚描述的那个解决方案）以便在生产环境中进行部署。

将您想向 Ted 询问的问题和提出的意见发送至 instinct@microsoft.com instinct@microsoft.com.

Ted Pattison 是一名作家、培训师以及 SharePoint MVP，住在美国佛罗里达州的坦帕。Ted 刚为 Microsoft Press 撰写完《Inside Windows SharePoint Services 3.0》一书