可以通过在 Visual Studio 2010 中创建自己的项目项类型来扩展 SharePoint 项目系统。 在本演练中,您将创建一个项目项,然后可将此项目项添加到 SharePoint 项目中以便在 SharePoint 网站上创建一个自定义操作。 该自定义操作可将一个菜单项添加到 SharePoint 网站的**“网站操作”**菜单中。
本演练将演示以下任务:
创建一个 Visual Studio 扩展,该扩展为自定义操作定义了新类型的 SharePoint 项目项。 新的项目项类型将实现以下几个自定义功能:
用作与项目项相关的其他任务(如显示 Visual Studio 中用于自定义操作的设计器)的起始点的快捷菜单。
当开发人员更改项目项及其所在的项目的某些属性时运行的代码。
**“解决方案资源管理器”**中显示在项目项旁边的自定义图标。
为项目项创建 Visual Studio 项目模板。
生成 Visual Studio 扩展 (VSIX) 包以部署项目项模板和扩展程序集。
调试并测试项目项。
这是一个独立的演练。 完成本演练后,可以向项模板添加向导来增强项目项。 有关更多信息,请参见演练:使用项模板创建自定义操作项目项(第 2 部分)。
提示
可从以下位置下载一个示例,该示例包含此演练的已完成项目、代码和其他文件:https://go.microsoft.com/fwlink/?LinkId=191369。
系统必备
您需要在开发计算机上安装以下组件才能完成本演练:
支持的 Microsoft Windows、SharePoint 和 Visual Studio 版本。 有关更多信息,请参见开发 SharePoint 解决方案的要求。
Visual Studio 2010 SDK。 本演练使用 SDK 中的**“VSIX 项目”**模板来创建 VSIX 包以部署项目项。 有关更多信息,请参见扩展 Visual Studio 中的 SharePoint 工具。
了解以下概念很有用,但对于完成本演练并不是必需的:
SharePoint 中的自定义操作。 有关更多信息,请参见 Custom Action(自定义操作)。
Visual Studio 中的项模板。 有关更多信息,请参见 Visual Studio 模板介绍。
创建项目
若要完成本演练,您需要创建以下三个项目:
一个 VSIX 项目。 该项目创建 VSIX 包以部署 SharePoint 项目项。
一个项模板项目。 该项目创建一个可用于向 SharePoint 项目添加 SharePoint 项目项的项模板。
一个类库项目。 该项目实现定义 SharePoint 项目项的行为的 Visual Studio 扩展。
从创建项目开始本演练。
创建 VSIX 项目
启动 Visual Studio。
在**“文件”菜单上指向“新建”,再单击“项目”**。
在**“新建项目”对话框顶部的组合框中,确保选择“.NET Framework 4”**。
在**“新建项目”对话框中,展开“Visual C#”或“Visual Basic”节点,然后单击“扩展性”**节点。
提示
只有在安装 Visual Studio 2010 SDK 之后,“扩展性”节点才可用。 有关更多信息,请参见前面的系统必备部分。
单击**“VSIX 项目”**模板。
在**“名称”**框中键入 CustomActionProjectItem。
单击**“确定”**。
Visual Studio 会将**“CustomActionProjectItem”项目添加到“解决方案资源管理器”**中。
创建项模板项目
在**“解决方案资源管理器”中,右击解决方案节点,单击“添加”,再单击“新建项目”**。
提示
在 Visual Basic 项目中,仅当在“选项”对话框 ->“项目和解决方案”->“常规”中选中“总是显示解决方案”复选框时,解决方案节点才会出现在“解决方案资源管理器”中。
在**“新建项目”对话框顶部的组合框中,确保选择“.NET Framework 4”**。
在**“新建项目”对话框中,展开“Visual C#”或“Visual Basic”节点,然后单击“扩展性”**节点。
在项目模板列表中,选择**“C# 项模板”或“Visual Basic 项模板”**。
在**“名称”**框中键入 ItemTemplate。
单击**“确定”**。
Visual Studio 将**“ItemTemplate”**项目添加到解决方案中。
创建扩展项目
在**“解决方案资源管理器”中,右击解决方案节点,单击“添加”,再单击“新建项目”**。
在**“新建项目”对话框顶部的组合框中,确保选择“.NET Framework 4”**。
在**“新建项目”对话框中,展开“Visual C#”或“Visual Basic”节点,然后单击“Windows”**节点。
选择**“类库”**项目模板。
在**“名称”**框中键入 ProjectItemDefinition。
单击**“确定”**。
Visual Studio 将**“ProjectItemDefinition”**项目添加到解决方案中,并打开默认的 Class1 代码文件。
从项目中删除 Class1 代码文件。
配置扩展项目
在编写代码以定义 SharePoint 项目项类型之前,您必须将代码文件和程序集引用添加到扩展项目中。
配置项目
在 ProjectItemDefinition 项目中,添加名为 CustomAction 的代码文件。
在**“项目”菜单上,单击“添加引用”**。
在**“.NET”选项卡上,按住 Ctrl 的同时单击下列程序集,然后单击“确定”**:
Microsoft.VisualStudio.SharePoint
System.ComponentModel.Composition
System.Windows.Forms
定义新的 SharePoint 项目项类型
创建一个类,该类实现 ISharePointProjectItemTypeProvider 接口以定义新项目项类型的行为。 每当需要定义新类型的项目项时,就要实现此接口。
定义新的 SharePoint 项目项类型
在 ProjectItemDefinition 项目中,打开 CustomAction 代码文件。
将此文件中的代码替换为以下代码。
Imports System Imports System.Diagnostics Imports System.ComponentModel Imports System.ComponentModel.Composition Imports Microsoft.VisualStudio.SharePoint Namespace Contoso.SharePointProjectItems.CustomAction ' Export attribute: Enables Visual Studio to discover and load this extension. ' SharePointProjectItemType attribute: Specifies the ID for this new project item type. This string must ' match the value of the Type attribute of the ProjectItem element in the .spdata file for ' the project item. ' SharePointProjectItemIcon attribute: Specifies the icon to display with this project item in Solution Explorer. ' CustomActionProjectItemTypeProvider class: Defines a new type of project item that can be used to create a custom ' action on a SharePoint site. <Export(GetType(ISharePointProjectItemTypeProvider))> _ <SharePointProjectItemType("Contoso.CustomAction")> _ <SharePointProjectItemIcon("ProjectItemDefinition.CustomAction_SolutionExplorer.ico")> _ Partial Friend Class CustomActionProjectItemTypeProvider Implements ISharePointProjectItemTypeProvider Private WithEvents projectItemTypeDefinition As ISharePointProjectItemTypeDefinition ' Configures the behavior of the project item type. Private Sub InitializeType(ByVal projectItemTypeDefinition As ISharePointProjectItemTypeDefinition) _ Implements ISharePointProjectItemTypeProvider.InitializeType projectItemTypeDefinition.Name = "CustomAction" projectItemTypeDefinition.SupportedDeploymentScopes = _ SupportedDeploymentScopes.Site Or SupportedDeploymentScopes.Web projectItemTypeDefinition.SupportedTrustLevels = SupportedTrustLevels.All Me.projectItemTypeDefinition = projectItemTypeDefinition End Sub Private Const DesignerMenuItemText As String = "View Custom Action Designer" Private Sub ProjectItemMenuItemsRequested(ByVal Sender As Object, _ ByVal e As SharePointProjectItemMenuItemsRequestedEventArgs) _ Handles projectItemTypeDefinition.ProjectItemMenuItemsRequested Dim viewDesignerMenuItem As IMenuItem = e.ViewMenuItems.Add(DesignerMenuItemText) AddHandler viewDesignerMenuItem.Click, AddressOf MenuItemClick End Sub Private Sub MenuItemClick(ByVal Sender As Object, ByVal e As MenuItemEventArgs) Dim projectItem As ISharePointProjectItem = CType(e.Owner, ISharePointProjectItem) Dim message As String = String.Format("You clicked the menu on the {0} item. " & _ "You could perform some related task here, such as displaying a designer " & _ "for the custom action.", projectItem.Name) System.Windows.Forms.MessageBox.Show(message, "Contoso Custom Action") End Sub Private Sub ProjectItemNameChanged(ByVal Sender As Object, ByVal e As NameChangedEventArgs) _ Handles projectItemTypeDefinition.ProjectItemNameChanged Dim projectItem As ISharePointProjectItem = CType(Sender, ISharePointProjectItem) Dim message As String = String.Format("The name of the {0} item changed to: {1}", _ e.OldName, projectItem.Name) projectItem.Project.ProjectService.Logger.WriteLine(message, LogCategory.Message) End Sub End Class End Namespace
using System; using System.Diagnostics; using System.ComponentModel; using System.ComponentModel.Composition; using Microsoft.VisualStudio.SharePoint; namespace Contoso.SharePointProjectItems.CustomAction { // Enables Visual Studio to discover and load this extension. [Export(typeof(ISharePointProjectItemTypeProvider))] // Specifies the ID for this new project item type. This string must match the value of the // Type attribute of the ProjectItem element in the .spdata file for the project item. [SharePointProjectItemType("Contoso.CustomAction")] // Specifies the icon to display with this project item in Solution Explorer. [SharePointProjectItemIcon("ProjectItemDefinition.CustomAction_SolutionExplorer.ico")] // Defines a new type of project item that can be used to create a custom action on a SharePoint site. internal partial class CustomActionProjectItemTypeProvider : ISharePointProjectItemTypeProvider { // Implements IProjectItemTypeProvider.InitializeType. Configures the behavior of the project item type. public void InitializeType(ISharePointProjectItemTypeDefinition projectItemTypeDefinition) { projectItemTypeDefinition.Name = "CustomAction"; projectItemTypeDefinition.SupportedDeploymentScopes = SupportedDeploymentScopes.Site | SupportedDeploymentScopes.Web; projectItemTypeDefinition.SupportedTrustLevels = SupportedTrustLevels.All; projectItemTypeDefinition.ProjectItemNameChanged += ProjectItemNameChanged; projectItemTypeDefinition.ProjectItemMenuItemsRequested += ProjectItemMenuItemsRequested; } private const string designerMenuItemText = "View Custom Action Designer"; private void ProjectItemMenuItemsRequested(object sender, SharePointProjectItemMenuItemsRequestedEventArgs e) { e.ViewMenuItems.Add(designerMenuItemText).Click += MenuItemClick; } private void MenuItemClick(object sender, MenuItemEventArgs e) { ISharePointProjectItem projectItem = (ISharePointProjectItem)e.Owner; string message = String.Format("You clicked the menu on the {0} item. " + "You could perform some related task here, such as displaying a designer " + "for the custom action.", projectItem.Name); System.Windows.Forms.MessageBox.Show(message, "Contoso Custom Action"); } private void ProjectItemNameChanged(object sender, NameChangedEventArgs e) { ISharePointProjectItem projectItem = (ISharePointProjectItem)sender; string message = String.Format("The name of the {0} item changed to: {1}", e.OldName, projectItem.Name); projectItem.Project.ProjectService.Logger.WriteLine(message, LogCategory.Message); } } }
在解决方案资源管理器中为项目项创建图标
在创建一个自定义 SharePoint 项目项时,您可以将一个图像(图标或位图)与该项目项相关联。 在**“解决方案资源管理器”**中,此图像会出现在该项目项的旁边。
在下面的过程中,您将为项目项创建一个图标,并将此图标嵌入到扩展程序集中。 先前创建的 CustomActionProjectItemTypeProvider 类的 SharePointProjectItemIconAttribute 将引用此图标。
为项目项创建自定义图标
在**“解决方案资源管理器”中,右击“ProjectItemDefinition”**项目。
在快捷菜单上指向**“添加”,然后单击“新建项”**。
在项目项的列表中,单击**“图标文件”**。
提示
在 Visual Basic 项目中,必须单击“常规”节点才能查看“图标文件”项。
为新图标名称键入 CustomAction_SolutionExplorer.ico,再单击**“添加”**。
新图标将在**“图像编辑器”**中打开。
编辑 16x16 版本的图标文件,使得设计出的图标可以让您识别,然后保存该图标文件。
在**“解决方案资源管理器”中,单击“CustomAction_SolutionExplorer.ico”**。
在**“属性”窗口中,单击“生成操作”旁边的下拉箭头,然后单击“嵌入的资源”**。
检查点
演练进行到此时,项目项的所有代码都位于项目中。 生成项目以确保编译项目时不会出错。
生成项目
- 在**“生成”菜单上,选择“生成解决方案”**。
创建 Visual Studio 项模板
若要使其他开发人员能够使用您的项目项,必须创建一个项目模板或项模板。 开发人员可在 Visual Studio 中使用这些模板,通过创建一个新项目或向现有项目中添加项,从而创建您的项目项的实例。 在本演练中,将使用 ItemTemplate 项目配置项目项。
创建项模板
从 ItemTemplate 项目中删除 Class1 代码文件。
在 ItemTemplate 项目中,打开 ItemTemplate.vstemplate 文件。
用下面的 XML 替换该文件的内容,然后保存并关闭该文件。
提示
下面的 XML 适用于 Visual C# 项模板。 如果创建的是 Visual Basic 项模板,请用 VisualBasic 替换 ProjectType 元素的值。
<VSTemplate Version="2.0.0" xmlns="https://schemas.microsoft.com/developer/vstemplate/2005" Type="Item"> <TemplateData> <DefaultName>CustomAction</DefaultName> <Name>Custom Action</Name> <Description>SharePoint Custom Action by Contoso</Description> <ProjectType>CSharp</ProjectType> <SortOrder>1000</SortOrder> <Icon>ItemTemplate.ico</Icon> <ProvideDefaultName>true</ProvideDefaultName> </TemplateData> <TemplateContent> <ProjectItem ReplaceParameters="true" TargetFileName="$fileinputname$\Elements.xml">Elements.xml</ProjectItem> <ProjectItem ReplaceParameters="true" TargetFileName="$fileinputname$\SharePointProjectItem.spdata">CustomAction.spdata</ProjectItem> </TemplateContent> </VSTemplate>
此文件定义了项模板的内容和行为。 有关此文件的内容的更多信息,请参见 Visual Studio 模板架构参考。
在**“解决方案资源管理器”中,右击“ItemTemplate”项目,单击“添加”,再单击“新建项”**。
在**“添加新项”对话框中,选择“文本文件”,再在“名称”字段中键入 CustomAction.spdata,然后单击“添加”**。
向 CustomAction.spdata 文件添加下面的 XML,然后保存并关闭该文件。
<?xml version="1.0" encoding="utf-8"?> <ProjectItem Type="Contoso.CustomAction" DefaultFile="Elements.xml" xmlns="https://schemas.microsoft.com/VisualStudio/2010/SharePointTools/SharePointProjectItemModel"> <Files> <ProjectItemFile Source="Elements.xml" Target="$fileinputname$\" Type="ElementManifest" /> </Files> </ProjectItem>
此文件包含有关项目项所包含的文件的信息。 ProjectItem 元素的 Type 特性必须设置为传递给项目项定义(在本演练中先前创建的 CustomActionProjectItemTypeProvider 类)上的 SharePointProjectItemTypeAttribute 的同一字符串。 有关 .spdata 文件的内容的更多信息,请参见 SharePoint 项目项架构参考。
在**“解决方案资源管理器”中,右击“ItemTemplate”项目,单击“添加”,再单击“新建项”**。
在**“添加新项”对话框中,选择“XML 文件”,在“名称”字段中键入 Elements.xml,然后单击“添加”**。
用下面的 XML 替换 Elements.xml 文件的内容,然后保存并关闭该文件。
<?xml version="1.0" encoding="utf-8" ?> <Elements Id="$guid8$" xmlns="https://schemas.microsoft.com/sharepoint/"> <CustomAction Id="Replace this with a GUID or some other unique string" GroupId="SiteActions" Location="Microsoft.SharePoint.StandardMenu" Sequence="1000" Title="Replace this with your title" Description="Replace this with your description" > <UrlAction Url="~site/Lists/Tasks/AllItems.aspx"/> </CustomAction> </Elements>
此文件定义了一个默认自定义操作,该操作会在 SharePoint 网站的**“网站操作”**菜单上创建一个菜单项。 当用户单击此菜单项时,Web 浏览器中将打开 UrlAction 元素中指定的 URL。 有关可用于定义自定义操作的 XML 元素的更多信息,请参见 Custom Action Definitions(自定义操作)。
可以选择打开并修改 ItemTemplate.ico 文件,使该文件具有可识别的设计。 在**“添加新项”**对话框中,此图标将显示在该项目项的旁边。
在**“解决方案资源管理器”中右击“ItemTemplate”项目,然后单击“卸载项目”**。
再次右击**“ItemTemplate”项目,然后单击“编辑 ItemTemplate.csproj”或“编辑 ItemTemplate.vbproj”**。
定位到项目文件中的以下 VSTemplate 元素。
<VSTemplate Include="ItemTemplate.vstemplate">
用下面的 XML 替换此 VSTemplate 元素。
<VSTemplate Include="ItemTemplate.vstemplate"> <OutputSubPath>SharePoint\SharePoint14</OutputSubPath> </VSTemplate>
OutputSubPath 元素指定路径中的其他文件夹,在生成项目时将在这些文件夹中创建项模板。 此处指定的文件夹可确保项模板仅在客户单击**“添加新项”对话框的“SharePoint”节点下的“2010”**节点时可用。
保存并关闭文件。
在**“解决方案资源管理器”中右击“ItemTemplate”项目,然后单击“重新加载项目”**。
创建 VSIX 包以部署项目项
若要部署扩展,请使用解决方案中的 VSIX 项目来创建 VSIX 包。 首先,通过修改 VSIX 项目中包含的 source.extension.vsixmanifest 文件来配置 VSIX 包。 然后,通过生成解决方案来创建 VSIX 包。
配置并创建 VSIX 包
在**“解决方案资源管理器”中,双击 CustomActionProjectItem 项目中的“source.extension.vsixmanifest”**文件。
Visual Studio 将在清单编辑器中打开该文件。 source.extension.vsixmanifest 文件是所有 VSIX 包必需的 extension.vsixmanifest 文件的基础。 有关此文件的更多信息,请参见VSIX Extension Schema Reference。
在**“产品名称”**框中键入“自定义操作项目项”。
在**“作者”**框中键入 Contoso。
在**“说明”**框中,键入“表示自定义操作的 SharePoint 项目项”。
在编辑器的**“内容”部分中,单击“添加内容”**按钮。
在**“添加内容”对话框的“选择内容类型”列表框中,选择“项模板”**。
提示
此值对应于 extension.vsixmanifest 文件中的 ItemTemplate 元素。 此元素标识包含项目项模板的 VSIX 包中的子文件夹。 有关更多信息,请参见 ItemTemplate Element (VSX Schema)。
在**“选择源”下,单击“项目”单选按钮,然后在该按钮旁边的列表框中选择“ItemTemplate”**。
单击**“确定”**。
在清单编辑器中,再次单击**“添加内容”**按钮。
在**“添加内容”对话框的“选择内容类型”列表框中,选择“MEF 组件”**。
提示
此值对应于 extension.vsixmanifest 文件中的 MefComponent 元素。 此元素指定 VSIX 包中的扩展程序集的名称。 有关更多信息,请参见 MEFComponent Element (VSX Schema)。
在**“选择源”下,单击“项目”单选按钮,并在其旁边的列表框中选择“ProjectItemDefinition”**。
单击**“确定”**。
在**“生成”菜单上,单击“生成解决方案”**。 确保项目在编译时不会出错。
打开 CustomActionProjectItem 项目的生成输出文件夹。 确保此文件夹现在包含 CustomActionProjectItem.vsix 文件。
默认情况下,生成输出文件夹为 \bin\Debug 文件夹位于包含 CustomActionProjectItem 项目的文件夹下。
测试项目项
现在您可以对项目项进行测试了。 首先,在 Visual Studio 的实验实例中开始调试 CustomActionProjectItem 解决方案。 然后,测试 Visual Studio 实验实例中的 SharePoint 项目中的**“自定义操作”**项目项。 最后,生成并运行 SharePoint 项目,以验证此自定义操作是否按预期工作。
开始调试解决方案
利用管理员特权重新启动 Visual Studio,并打开“CustomActionProjectItem”解决方案。
打开 CustomAction 代码文件,并在 InitializeType 方法的第一行代码中添加一个断点。
按 F5 开始调试。
Visual Studio 将扩展安装到 %UserProfile%\AppData\Local\Microsoft\VisualStudio\10.0Exp\Extensions\Contoso\Custom Action Project Item\1.0 中,并启动 Visual Studio 的实验实例。 您将在此 Visual Studio 实例中测试项目项。
在 Visual Studio 中测试项目项
在 Visual Studio 的实验实例中,在**“文件”菜单上指向“新建”,然后单击“项目”**。
展开**“Visual C#”或“Visual Basic”(取决于项模板支持的语言),再展开“SharePoint”,然后单击“2010”**。
在项目模板的列表中,单击**“空项目”**。
在**“名称”**框中键入 CustomActionTest。
单击**“确定”**。
在**“SharePoint 自定义向导”中,键入要用于调试的网站的 URL,并单击“完成”**。
在**“解决方案资源管理器”中,右击项目节点,指向“添加”,然后单击“新建项”**。
在**“添加新项”对话框中,单击“SharePoint”节点下的“2010”**节点。
确认**“自定义操作”**项显示在项目项的列表中。
单击**“自定义操作”,再单击“添加”**。
Visual Studio 会将名为**“CustomAction1”**的新项添加到项目中,并在编辑器中打开 Elements.xml 文件。
验证另一个 Visual Studio 实例中的代码是否会在您之前在 InitializeType 方法中设置的断点处停止。 按 F5 以继续调试项目。
在 Visual Studio 的实验实例中,在**“解决方案资源管理器”中,右击“CustomAction1”节点,再单击“查看自定义操作设计器”。 确认会出现一个消息框,然后单击“确定”**。
可以使用此快捷菜单为开发人员提供其他选项或命令,如显示用于自定义操作的设计器。
在**“视图”菜单上,单击“输出”**。
将打开**“输出”**窗口。
在**“解决方案资源管理器”中,右击“CustomAction1”**项并将名称更改为 MyCustomAction。
**“输出”**窗口中应会显示一条确认消息,此消息由您在 CustomActionProjectItemTypeProvider 类中定义的 ProjectItemNameChanged 事件处理程序写入。 当开发人员修改项目项时,您可以处理此事件和其他项目项事件以实现自定义行为。
测试 SharePoint 中的自定义操作
在 Visual Studio 的实验实例中,打开 Elements.xml 文件(此文件是**“MyCustomAction”**项目项的子级)。
在 Elements.xml 文件中进行以下更改:
在 CustomAction 元素中,将 Id 特性设置为 GUID 或某个其他唯一字符串。 例如:
Id="cd85f6a7-af2e-44ab-885a-0c795b52121a"
在 CustomAction 元素中设置 Title 特性,如下所示:
Title="SharePoint Developer Center"
在 CustomAction 元素中设置 Description 特性,如下所示:
Description="Opens the SharePoint Developer Center Web site."
在 UrlAction 元素中设置 Url 特性,如下所示:
Url="https://msdn.microsoft.com/sharepoint/default.aspx"
保存 Elements.xml 文件。
按 F5。 这将对自定义操作进行打包并将其部署到由项目的**“网站 URL”**属性指定的 SharePoint 网站中。 Web 浏览器将打开此网站的默认页。
提示
如果出现“脚本调试被禁用”对话框,请单击“是”继续调试项目。
单击**“网站操作”菜单。 验证此菜单的底部是否显示名为“SharePoint Developer Center”(SharePoint 开发中心)**的自定义操作。
单击**“SharePoint Developer Center”(SharePoint 开发中心)**菜单项。 确认浏览器已打开网站 https://msdn.microsoft.com/sharepoint/default.aspx。
关闭 Web 浏览器。
清理开发计算机
测试完项目项之后,从 Visual Studio 的实验实例中移除项目项模板。
清理开发计算机
在 Visual Studio 的实验实例中,在**“工具”菜单上单击“扩展管理器”**。
这将打开**“扩展管理器”**对话框。
在扩展列表中,单击**“自定义操作项目项”,然后单击“卸载”**。
在出现的对话框中,单击**“是”**以确认您要卸载该扩展。
单击**“立即重新启动”**以完成卸载。
关闭 Visual Studio 的两个实例(Visual Studio 的实验实例和 Visual Studio 的已打开 CustomActionProjectItem 解决方案的实例)。
后续步骤
完成本演练后,可以向项模板添加向导。 当用户向 SharePoint 项目添加“自定义操作”项目项时,此向导将收集有关自定义操作的信息(如自定义操作的位置和单击自定义操作时将导航到的 URL),并将此信息添加到新项目项的 Elements.xml 文件中。 有关更多信息,请参见演练:使用项模板创建自定义操作项目项(第 2 部分)。