可以通过在 Visual Studio 中创建自己的项目项类型来扩展 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 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.5 中选择。
在 新建项目 对话框中,展开 visual C# 或 Visual Basic 节点,然后选择 扩展性 节点。
说明
只有在安装 Visual Studio SDK,扩展性 节点可用。有关更多信息,请参见本主题前面的系统必备部分。
选择 VSIX 项目 模板。
在 名称 框中,输入 CustomActionProjectItem,然后选择 确定 按钮。
Visual Studio 会将**“CustomActionProjectItem”项目添加到“解决方案资源管理器”**中。
创建项模板项目
在 解决方案资源管理器,请打开解决方案节点的快捷菜单上,选择 添加,然后选择 新建项目。
说明
在 Visual Basic 项目中,仅当在General, Projects and Solutions, Options Dialog Box中选中“总是显示解决方案”复选框时,解决方案节点才会出现在“解决方案资源管理器”中。
在列表中 新建项目 对话框顶部,确保 .NET Framework 4.5 中选择。
在 新建项目 对话框中,展开 visual C# 或 Visual Basic 节点,然后选择 扩展性 节点。
在项目模板列表中,选择 C# 项目模板 或 Visual Basic 项模板 模板。
在 名称 框中,输入 ItemTemplate,然后选择 确定 按钮。
Visual Studio 将**“ItemTemplate”**项目添加到解决方案中。
创建扩展项目
在 解决方案资源管理器,请打开解决方案节点的快捷菜单上,选择 添加,然后选择 新建项目。
在列表中 新建项目 对话框顶部,确保 .NET Framework 4.5 中选择。
在 新建项目 对话框中,展开 visual C# 或 Visual Basic 节点,选择 Windows 节点,然后选择 类库 项目模板。
在 名称 框中,输入 ProjectItemDefinition,然后选择 确定 按钮。
Visual Studio 将**“ProjectItemDefinition”**项目添加到解决方案中,并打开默认的 Class1 代码文件。
从项目中删除 Class1 代码文件。
配置扩展项目
在编写代码以定义 SharePoint 项目项类型之前,您必须将代码文件和程序集引用添加到扩展项目中。
配置项目
在 解决方案资源管理器,打开 ProjectItemDefinition 项目的快捷菜单,选择 添加,然后选择 新建项。
在项目项的列表中,选择 代码文件。
在 名称 框中,输入与适当的文件扩展名的名称 CustomAction,然后选择 添加 按钮。
在 解决方案资源管理器,打开 ProjectItemDefinition 项目的快捷菜单,然后选择 添加引用。
在 引用管理器– ProjectItemDefinition 对话框中,选择 程序集 节点,然后选择 框架 节点。
以下程序集中的每一个旁边的复选框:
System.ComponentModel.Composition
System.Windows.Forms
选择 扩展 节点,请在 Microsoft.VisualStudio.Sharepoint 程序集旁边的复选框,然后选择 确定 按钮。
定义新的 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。
在 属性 窗口,请在 生成操作 属性旁边的下箭头。
在显示的列表中,选择 嵌入的资源。
检查点
演练进行到此时,项目项的所有代码都位于项目中。生成项目验证它在编译时不会出错。
生成项目
- 打开 ProjectItemDefinition 项目的快捷菜单中选择 Build。
创建 Visual Studio 项模板
若要使其他开发人员能够使用您的项目项,必须创建一个项目模板或项模板。开发人员可在 Visual Studio 中使用这些模板,通过创建一个新项目或向现有项目中添加项,从而创建您的项目项的实例。在本演练中,将使用 ItemTemplate 项目配置项目项。
创建项模板
从 ItemTemplate 项目中删除 Class1 代码文件。
在 ItemTemplate 项目中,打开 ItemTemplate.vstemplate 文件。
用下面的 XML 替换该文件的内容,然后保存并关闭该文件。
说明
下面的 XML 适用于 Visual C# 项模板。如果创建的是 Visual Basic 项模板,请用 VisualBasic 替换 ProjectType 元素的值。
<?xml version="1.0" encoding="utf-8"?> <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 网站的**“网站操作”**菜单上创建一个菜单项。当用户选择菜单项时,在 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 包
在 解决方案资源管理器,打开 source.extension.vsixmanifest 文件的快捷菜单在 CustomActionProjectItem 项目,然后选择 打开。
Visual Studio 将在清单编辑器中打开该文件。source.extension.vsixmanifest 文件是所有 VSIX 包必需的 extension.vsixmanifest 文件的基础。有关此文件的更多信息,请参见VSIX 扩展架构参考。
在 产品名称 框中,输入 自定义操作"项目项。
在 作者 框中,输入 Contoso。
在 说明 框中,输入 表示一个自定义操作的 SharePoint 项目项。
在 资产 选项卡中,选择 新建 按钮。
添加新资产 出现对话框。
在 类型 列表中,选择 Microsoft.VisualStudio.ItemTemplate。
说明
此值对应于 extension.vsixmanifest 文件中的 ItemTemplate 元素。此元素标识包含项目项模板的 VSIX 包中的子文件夹。有关更多信息,请参见ItemTemplate Element。
在 源 列表中,选择 当前解决方案中的项目。
在 项目 列表中,选择 ItemTemplate,然后选择 确定 按钮。
在 资产 选项,请选择 新建 按钮。
添加新资产 出现对话框。
在 类型 列表中,选择 Microsoft.VisualStudio.MefComponent。
说明
此值对应于 extension.vsixmanifest 文件中的 MefComponent 元素。此元素指定 VSIX 包中的扩展程序集的名称。有关更多信息,请参见MEFComponent Element。
在 源 列表中,选择 当前解决方案中的项目。
在 项目 列表中,选择 ProjectItemDefinition。
选择**“确定”**按钮。
在菜单栏上,依次选择 Build,生成解决方案,然后确保项目在编译时不会出错。
确保 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 节点。
在项目模板列表中,选择 SharePoint 2010 项目。
在 名称 框中,输入 CustomActionTest,然后选择 确定 按钮。
在 SharePoint 自定义向导,输入要用于调试的网站的 URL,然后选择 完成 按钮。
在 解决方案资源管理器,请打开项目节点的快捷菜单上,选择 添加,然后选择 新建项。
在 添加新项 对话框中,选择 2010 节点。SharePoint 节点下。
确认**“自定义操作”**项显示在项目项的列表中。
选择 自定义操作 项目,然后选择 添加 按钮。
Visual Studio 添加一个名为"项目的 CustomAction1 的一个项目并在编辑器中打开 Elements.xml 文件。
验证另一个 Visual Studio 实例中的代码是否会在您之前在 InitializeType 方法中设置的断点处停止。
选择 F5 键继续调试项目。
在 Visual Studio 的实验实例中,在 解决方案资源管理器,打开 CustomAction1 节点的快捷菜单,然后选择 视图自定义活动设计器。
验证将出现一个消息框,然后选择 确定 按钮。
可以使用此快捷菜单为开发人员提供其他选项或命令,如显示用于自定义操作的设计器。
在菜单栏上,依次选择 视图,输出。
将打开**“输出”**窗口。
在 解决方案资源管理器,打开 CustomAction1 项目的快捷菜单,然后将其名称。MyCustomAction。
在 输出 窗口中,确认消息。此消息由 ProjectItemNameChanged 事件处理程序编写在 CustomActionProjectItemTypeProvider 选件类定义。当开发人员修改项目项时,您可以处理此事件和其他项目项事件以实现自定义行为。
测试 SharePoint 中的自定义操作
在 Visual Studio 的实验实例中,打开是 MyCustomAction 项目项的子级的 Elements.xml 文件。
在 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"
选择 F5 键。
该自定义操作进行打包并部署到 SharePoint。在项目的 网站 URL 属性指定站点。该浏览器将打开此网站的默认页。
说明
如果 脚本调试被禁用 出现对话框,请选择 是 按钮继续调试项目。
在 网站操作 菜单中,选择 SharePoint 开发中心,验证浏览器中打开网站 https://msdn.microsoft.com/sharepoint/default.aspx,然后关闭该浏览器。
清理开发计算机
测试完项目项之后,从 Visual Studio 的实验实例中移除项目项模板。
清理开发计算机
在 Visual Studio 的实验实例中,在菜单栏上,依次选择 工具,扩展和更新。
扩展和更新 对话框打开。
在扩展列表中,选择 自定义操作"项目项,然后选择 卸载 按钮。
在出现的对话框中,选择 是 按钮以确认您要卸载该扩展。
选择 立即重新启动 按钮来卸载。
关闭 CustomActionProjectItem 解决方案已在中打开 Visual Studio 的实验实例和实例。
后续步骤
完成本演练后,可以向项模板添加向导。当用户添加自定义操作"项目项添加到 SharePoint 项目时,此向导将收集有关事件的信息 (例如其位置和将导航,当事件处于选定状态时并将此信息添加到新项目项的 Elements.xml 文件。有关更多信息,请参见演练:使用项模板创建自定义操作项目项(第 2 部分)。