Walkthrough: Creating a Custom Action Project Item with an Item Template, Part 1

Article
02/04/2013

You can extend the SharePoint project system in Visual Studio 2010 by creating your own project item types. In this walkthrough, you will create a project item that can be added to a SharePoint project to create a custom action on a SharePoint site. The custom action adds a menu item to the Site Actions menu of the SharePoint site.

This walkthrough demonstrates the following tasks:

Creating a Visual Studio extension that defines a new type of SharePoint project item for a custom action. The new project item type implements several custom features:
- A shortcut menu that serves as a starting point for additional tasks related to the project item, such as displaying a designer for the custom action in Visual Studio.
- Code that runs when a developer changes certain properties of the project item and the project that contains it.
- A custom icon that appears next to the project item in Solution Explorer.
Creating a Visual Studio item template for the project item.
Building a Visual Studio Extension (VSIX) package to deploy the project item template and the extension assembly.
Debugging and testing the project item.

This is a stand-alone walkthrough. After you complete this walkthrough, you can enhance the project item by adding a wizard to the item template. For more information, see Walkthrough: Creating a Custom Action Project Item with an Item Template, Part 2.

Note

You can download a sample that contains the completed projects, code, and other files for this walkthrough from the following location: https://go.microsoft.com/fwlink/?LinkId=191369.

Prerequisites

You need the following components on the development computer to complete this walkthrough:

Supported editions of Microsoft Windows, SharePoint and Visual Studio. For more information, see Requirements for Developing SharePoint Solutions.
The Visual Studio 2010 SDK. This walkthrough uses the VSIX Project template in the SDK to create a VSIX package to deploy the project item. For more information, see Extending the SharePoint Tools in Visual Studio.

Knowledge of the following concepts is helpful, but not required, to complete the walkthrough:

Custom actions in SharePoint. For more information, see Custom Action.
Item templates in Visual Studio. For more information, see Introduction to Visual Studio Templates.

Creating the Projects

To complete this walkthrough, you need to create three projects:

A VSIX project. This project creates the VSIX package to deploy the SharePoint project item.
An item template project. This project creates an item template that can be used to add the SharePoint project item to a SharePoint project.
A class library project. This project implements a Visual Studio extension that defines the behavior of the SharePoint project item.

Start the walkthrough by creating the projects.

To create the VSIX project

Start Visual Studio.
On the File menu, point to New, and then click Project.
In the combo box at the top of the New Project dialog box, make sure that .NET Framework 4 is selected.
In the New Project dialog box, expand the Visual C# or Visual Basic nodes, and then click the Extensibility node.

Note

The Extensibility node is available only if you install the Visual Studio 2010 SDK. For more information, see the prerequisites section above.
Click the VSIX Project template.
In the Name box, type CustomActionProjectItem.
Click OK.

Visual Studio adds the CustomActionProjectItem project to Solution Explorer.

To create the item template project

In Solution Explorer, right-click the solution node, click Add, and then click New Project.

Note

In Visual Basic projects, the solution node appears in Solution Explorer only when the Always show solution check box is selected in the General, Projects and Solutions, Options Dialog Box.
In the combo box at the top of the New Project dialog box, make sure that .NET Framework 4 is selected.
In the New Project dialog box, expand the Visual C# or Visual Basic nodes, and then click the Extensibility node.
In the list of project templates, select C# Item Template or Visual Basic Item Template.
In the Name box, type ItemTemplate.
Click OK.

Visual Studio adds the ItemTemplate project to the solution.

To create the extension project

In Solution Explorer, right-click the solution node, click Add, and then click New Project.
In the combo box at the top of the New Project dialog box, make sure that .NET Framework 4 is selected.
In the New Project dialog box, expand the Visual C# or Visual Basic nodes, and then click the Windows node.
Select the Class Library project template.
In the Name box, type ProjectItemDefinition.
Click OK.

Visual Studio adds the ProjectItemDefinition project to the solution and opens the default Class1 code file.
Delete the Class1 code file from the project.

Configuring the Extension Project

Before you write code to define the SharePoint project item type, you have to add code files and assembly references to the extension project.

To configure the project

In the ProjectItemDefinition project, add a code files with the name CustomAction.
On the Project menu, click Add Reference.
On the .NET tab, press CTRL and click the following assemblies, and then click OK:
- Microsoft.VisualStudio.SharePoint
- System.ComponentModel.Composition
- System.Windows.Forms

Defining the New SharePoint Project Item Type

Create a class that implements the ISharePointProjectItemTypeProvider interface to define the behavior of the new project item type. Implement this interface whenever you want to define a new type of project item.

To define the new SharePoint project item type

In the ProjectItemDefinition project, open the CustomAction code file.

Replace the code in this file with the following code.

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);
        }
    }
}

Creating an Icon for the Project Item in Solution Explorer

When you create a custom SharePoint project item, you can associate an image (an icon or bitmap) with the project item. This image appears next to the project item in Solution Explorer.

In the following procedure, you create an icon for the project item and embed the icon in the extension assembly. This icon is referenced by the SharePointProjectItemIconAttribute of the CustomActionProjectItemTypeProvider class that you created earlier.

To create a custom icon for the project item

In Solution Explorer, right-click the ProjectItemDefinition project.
On the shortcut menu, point to Add, and then click New Item.
In the list of project items, click Icon File.

Note

In Visual Basic projects, you must click the General node to see the Icon File item.
Type CustomAction_SolutionExplorer.ico for the new icon name, and click Add.

The new icon opens in the Image Editor.
Edit the 16x16 version of the icon file so that it has a design you can recognize, and then save the icon file.
In Solution Explorer, click CustomAction_SolutionExplorer.ico.
In the Properties window, click the drop-down next to Build Action and then click Embedded Resource.

Checkpoint

At this point in the walkthrough, all the code for the project item is now in the project. Build the project to make sure that it compiles without errors.

To build your project

On the Build menu, select Build Solution.

Creating a Visual Studio Item Template

To enable other developers to use your project item, you must create a project template or item template. Developers use these templates in Visual Studio to create an instance of your project item by creating a new project, or by adding an item to an existing project. For this walkthrough, use the ItemTemplate project to configure your project item.

To create the item template

Delete the Class1 code file from the ItemTemplate project.
In the ItemTemplate project, open the ItemTemplate.vstemplate file.

Replace the contents of the file with the following XML, and then save and close the file.

Note

The following XML is for a Visual C# item template. If you are creating a Visual Basic item template, replace the value of the ProjectType element with VisualBasic.

<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>

This file defines the contents and behavior of the item template. For more information about the contents of this file, see Visual Studio Template Schema Reference.

In Solution Explorer, right-click the ItemTemplate project, click Add, and then click New Item.
In the Add New Item dialog, select Text File, type CustomAction.spdata in the Name field, and click Add.
Add the following XML to the CustomAction.spdata file, and then save and close the file.
```
<?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>
```
This file contains information about the files that are contained by the project item. The Type attribute of the ProjectItem element must be set to the same string that is passed to the SharePointProjectItemTypeAttribute on the project item definition (the CustomActionProjectItemTypeProvider class you created earlier in this walkthrough). For more information about the contents of .spdata files, see SharePoint Project Item Schema Reference.
In Solution Explorer, right-click the ItemTemplate project, click Add, and then click New Item.
In the Add New Item dialog, select XML File, type Elements.xml in the Name field, and click Add.

Replace the contents of the Elements.xml file with the following XML, and then save and close the file.

<?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>

This file defines a default custom action that creates a menu item on the Site Actions menu of the SharePoint site. When a user clicks the menu item, the URL specified in the UrlAction element opens in the Web browser. For more information about the XML elements you can use to define a custom action, see Custom Action Definitions.

Optionally, open the ItemTemplate.ico file and modify it so that it has a design that you can recognize. This icon will display next to the project item in the Add New Item dialog box.
In Solution Explorer, right-click the ItemTemplate project and click Unload Project.
Right-click the ItemTemplate project again and click Edit ItemTemplate.csproj or Edit ItemTemplate.vbproj.
Locate the following VSTemplate element in the project file.
```
<VSTemplate Include="ItemTemplate.vstemplate">
```
Replace this VSTemplate element with the following XML.
```
<VSTemplate Include="ItemTemplate.vstemplate">
  <OutputSubPath>SharePoint\SharePoint14</OutputSubPath>
</VSTemplate>
```
The OutputSubPath element specifies additional folders in the path under which the item template is created when you build the project. The folders specified here ensure that the item template will be available only when customers click the 2010 node under the SharePoint node in the Add New Item dialog box.
Save and close the file.
In Solution Explorer, right-click the ItemTemplate project and click Reload Project.

Creating a VSIX Package to Deploy the Project Item

To deploy the extension, use the VSIX project in your solution to create a VSIX package. First, configure the VSIX package by modifying the source.extension.vsixmanifest file that is included in the VSIX project. Then, create the VSIX package by building the solution.

To configure and create the VSIX package

In Solution Explorer, double-click the source.extension.vsixmanifest file in the CustomActionProjectItem project.

Visual Studio opens the file in the manifest editor. The source.extension.vsixmanifest file is the basis for the extension.vsixmanifest file that is required by all VSIX packages. For more information about this file, see VSIX Extension Schema Reference.
In the Product Name box, type Custom Action Project Item.
In the Author box, type Contoso.
In the Description box, type A SharePoint project item that represents a custom action.
In the Content section of the editor, click the Add Content button.
In the Add Content dialog box, in the Select a content type list box, select Item Template.

Note

This value corresponds to the ItemTemplate element in the extension.vsixmanifest file. This element identifies the subfolder in the VSIX package that contains the project item template. For more information, see ItemTemplate Element (VSX Schema).
Under Select a source, click the Project radio button, and select ItemTemplate in the list box next to it.
Click OK.
In the manifest editor, click the Add Content button again.
In the Add Content dialog box, in the Select a content type list box, select MEF Component.

Note

This value corresponds to the MefComponent element in the extension.vsixmanifest file. This element specifies the name of an extension assembly in the VSIX package. For more information, see MEFComponent Element (VSX Schema).
Under Select a source, click the Project radio button, and select ProjectItemDefinition in the list box next to it.
Click OK.
On the Build menu, click Build Solution. Make sure that the project compiles without errors.
Open the build output folder for the CustomActionProjectItem project. Make sure that this folder now contains the CustomActionProjectItem.vsix file.

By default, the build output folder is the ..\bin\Debug folder under the folder that contains the CustomActionProjectItem project.

Testing the Project Item

You are now ready to test the project item. First, start debugging the CustomActionProjectItem solution in the experimental instance of Visual Studio. Then, test the Custom Action project item in a SharePoint project in the experimental instance of Visual Studio. Finally, build and run the SharePoint project to verify that the custom action works as expected.

To start debugging the solution

Restart Visual Studio with administrator privileges and open the CustomActionProjectItem solution.
Open the CustomAction code file, and add a breakpoint to the first line of code in the InitializeType method.
Press F5 to start debugging.

Visual Studio installs the extension to %UserProfile%\AppData\Local\Microsoft\VisualStudio\10.0Exp\Extensions\Contoso\Custom Action Project Item\1.0 and starts an experimental instance of Visual Studio. You will test the project item in this instance of Visual Studio.

To test the project item in Visual Studio

In the experimental instance of Visual Studio, on the File menu, point to New, and then click Project.
Expand Visual C# or Visual Basic (depending on the language your item template supports), expand SharePoint, and then click 2010.
In the list of project templates, click Empty Project.
In the Name box, type CustomActionTest.
Click OK.
In the SharePoint Customization Wizard, type the URL of the site that you want to use for debugging, and click Finish.
In Solution Explorer, right-click the project node, point to Add, and then click New Item.
In the Add New Item dialog box, click the 2010 node under the SharePoint node.

Verify that the Custom Action item appears in the list of project items.
Click Custom Action, and then click Add.

Visual Studio adds a new item named CustomAction1 to your project, and it opens the Elements.xml file in the editor.
Verify that the code in the other instance of Visual Studio stops on the breakpoint that you set earlier in the InitializeType method. Press F5 to continue to debug the project.
In the experimental instance of Visual Studio, in Solution Explorer, right-click the CustomAction1 node and click View Custom Action Designer. Verify that a message box appears, and then click OK.

You can use this shortcut menu to provide additional options or commands for developers, such as displaying a designer for the custom action.
On the View menu, click Output.

The Output window opens.
In Solution Explorer, right-click the CustomAction1 item, and change the name to MyCustomAction.

You should see a confirmation message in the Output window This message is written by the ProjectItemNameChanged event handler you defined in the CustomActionProjectItemTypeProvider class. You can handle this event and other project item events to implement custom behavior when the developer modifies the project item.

To test the custom action in SharePoint

In the experimental instance of Visual Studio, open the Elements.xml file that is a child of the MyCustomAction project item.
In the Elements.xml file, make the following changes:
- In the CustomAction element, set the Id attribute to a GUID or some other unique string. For example:
```
Id="cd85f6a7-af2e-44ab-885a-0c795b52121a"
```
- In the CustomAction element, set the Title attribute as follows:
```
Title="SharePoint Developer Center"
```
- In the CustomAction element, set the Description attribute as follows:
```
Description="Opens the SharePoint Developer Center Web site."
```
- In the UrlAction element, set the Url attribute as follows:
```
Url="https://msdn.microsoft.com/sharepoint/default.aspx"
```
Save the Elements.xml file.
Press F5. The custom action is packaged and deployed to the SharePoint site specified by the Site URL property of the project. The Web browser opens to the default page of this site.

Note

If the Script Debugging Disabled dialog box is displayed, click Yes to continue to debug the project.
Click the Site Actions menu. Verify that the custom action named SharePoint Developer Center appears at the bottom of this menu.
Click the SharePoint Developer Center menu item. Verify that the browser opens the Web site https://msdn.microsoft.com/sharepoint/default.aspx.
Close the Web browser.

Cleaning up the Development Computer

After you finish testing the project item, remove the project item template from the experimental instance of Visual Studio.

To clean up the development computer

In the experimental instance of Visual Studio, on the Tools menu, click Extension Manager.

The Extension Manager dialog box opens.
In the list of extensions, click Custom Action Project Item, and then click Uninstall.
In the dialog box that appears, click Yes to confirm that you want to uninstall the extension.
Click Restart Now to complete the uninstallation.
Close both instances of Visual Studio (the experimental instance and the instance of Visual Studio that has the CustomActionProjectItem solution open).

Next Steps

After you complete this walkthrough, you can add a wizard to the item template. When a user adds a Custom Action project item to a SharePoint project, the wizard collects information about the custom action (such as its location and the URL to navigate to when it is clicked) and adds this information to the Elements.xml file in the new project item. For more information, see Walkthrough: Creating a Custom Action Project Item with an Item Template, Part 2.

Share via