Walkthrough: Create a custom action project item with an item template, Part 1

Article
02/02/2017

Applies to: Visual Studio Visual Studio for Mac

Note

This article applies to Visual Studio 2017. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here

You can extend the SharePoint project system in Visual Studio 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: Create a custom action project item with an item template, Part 2.

Note

You can download a sample from Github that shows how to create custom activities for a workflow.

Prerequisites

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

Supported editions of Microsoft Windows, SharePoint and Visual Studio.
The Visual Studio 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 Extend 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 Creating Project and Item Templates.

Create 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 menu bar, choose File > New > Project.
In the list at the top of the New Project dialog box, make sure that .NET Framework 4.5 is selected.
In the New Project dialog box, expand the Visual C# or Visual Basic nodes, and then choose the Extensibility node.

Note

The Extensibility node is available only if you install the Visual Studio SDK. For more information, see the prerequisites section earlier in this topic.
Choose the VSIX Project template.
In the Name box, enter CustomActionProjectItem, and then choose the OK button.

Visual Studio adds the CustomActionProjectItem project to Solution Explorer.

To create the item template project

In Solution Explorer, open the shortcut menu for the solution node, choose Add, and then choose New Project.
In the list at the top of the New Project dialog box, make sure that .NET Framework 4.5 is selected.
In the New Project dialog box, expand the Visual C# or Visual Basic nodes, and then choose the Extensibility node.
In the list of project templates, choose the C# Item Template or Visual Basic Item Template template.
In the Name box, enter ItemTemplate, and then choose the OK button.

Visual Studio adds the ItemTemplate project to the solution.

To create the extension project

In Solution Explorer, open the shortcut menu for the solution node, choose Add, and then choose New Project.
In the list at the top of the New Project dialog box, make sure that .NET Framework 4.5 is selected.
In the New Project dialog box, expand the Visual C# or Visual Basic nodes, choose the Windows node, and then choose the Class Library project template.
In the Name box, enter ProjectItemDefinition, and then choose the OK button.

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

Configure 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 Solution Explorer, open the shortcut menu for the ProjectItemDefinition project, choose Add, then choose New Item.
In the list of project items, choose Code File.
In the Name box, enter the name CustomAction with the appropriate file name extension, and then choose the Add button.
In Solution Explorer, open the shortcut menu for the ProjectItemDefinition project, and then choose Add Reference.
In the Reference Manager - ProjectItemDefinition dialog box, choose the Assemblies node, and then choose the Framework node.
Select the check box next to each of the following assemblies:
- System.ComponentModel.Composition
- System.Windows.Forms
Choose the Extensions node, select the check box next to the Microsoft.VisualStudio.Sharepoint assembly, and then choose the OK button.

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

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

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

Create 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, open the shortcut menu for the ProjectItemDefinition project, choose Add, and then choose New Item....
In the list of project items, choose the Icon File item.

Note

In Visual Basic projects, you must choose the General node to display the Icon File item.
In the Name box, enter CustomAction_SolutionExplorer.ico, and then choose the Add button.

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, choose CustomAction_SolutionExplorer.ico.
In the Properties window, choose the arrow next to the Build Action property.
In the list that appears, choose 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 verify that it compiles without errors.

To build your project

Open the shortcut menu for the ProjectItemDefinition project and choose Build.

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

<?xml version="1.0" encoding="utf-8"?>
<VSTemplate Version="2.0.0" xmlns="http://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, open the shortcut menu for the ItemTemplate project, choose Add, and then choose New Item.
In the Add New Item dialog box, choose the Text File template.
In the Name box, enter CustomAction.spdata, and then choose the Add button.
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="http://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, open the shortcut menu for the ItemTemplate project, choose Add, and then choose New Item.
In the Add New Item dialog box, choose the XML File template.
In the Name box, enter Elements.xml, and then choose the Add button.

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="http://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 chooses 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, open the shortcut menu for the ItemTemplate project, and then choose Unload Project.
Open the shortcut menu for the ItemTemplate project again, and then choose 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, and then save and close the file.
```
<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 open the Add New Item dialog box, expand the SharePoint node, and then choose the 2010 node.
In Solution Explorer, open the shortcut menu for the ItemTemplate project, and then choose Reload Project.

Create 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, open the shortcut menu for the source.extension.vsixmanifest file in the CustomActionProjectItem project, and then choose Open.

Visual Studio opens the file in the manifest editor. The source.extension.vsixmanifest file is the basis for the extension.vsixmanifest file that all VSIX packages require. For more information about this file, see VSIX Extension Schema 1.0 Reference.
In the Product Name box, enter Custom Action Project Item.
In the Author box, enter Contoso.
In the Description box, enter A SharePoint project item that represents a custom action.
On the Assets tab, choose the New button.

The Add New Asset dialog box appears.
In the Type list, choose Microsoft.VisualStudio.ItemTemplate.

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).
In the Source list, choose A project in current solution.
In the Project list, choose ItemTemplate, and then choose the OK button.
In the Assets tab, choose the New button again.

The Add New Asset dialog box appears.
In the Type list, choose Microsoft.VisualStudio.MefComponent.

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).
In the Source list, choose A project in current solution.
In the Project list, choose ProjectItemDefinition.
Choose the OK button.
On the menu bar, choose Build > Build Solution, and then make sure that the project compiles without errors.
Make sure that the build output folder for the CustomActionProjectItem project contains the CustomActionProjectItem.vsix file.

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

Test 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 administrative credentials, and then open the CustomActionProjectItem solution.
Open the CustomAction code file, and then add a breakpoint to the first line of code in the InitializeType method.
Choose the F5 key 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'll 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 menu bar, choose File > New > Project.
Expand Visual C# or Visual Basic (depending on the language that your item template supports), expand SharePoint, and then choose the 2010 node.
In the list of project templates, choose SharePoint 2010 Project.
In the Name box, enter CustomActionTest, and then choose the OK button.
In the SharePoint Customization Wizard, enter the URL of the site that you want to use for debugging, and then choose the Finish button.
In Solution Explorer, open the shortcut menu for the project node, choose Add, and then choose New Item.
In the Add New Item dialog box, choose the 2010 node under the SharePoint node.

Verify that the Custom Action item appears in the list of project items.
Choose the Custom Action item, and then choose the Add button.

Visual Studio adds an item that's named CustomAction1 to your project and 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.
Choose the F5 key to continue to debug the project.
In the experimental instance of Visual Studio, in Solution Explorer, open the shortcut menu for the CustomAction1 node, and then choose View Custom Action Designer.
Verify that a message box appears, and then choose the OK button.

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 menu bar, choose View > Output.

The Output window opens.
In Solution Explorer, open the shortcut menu for the CustomAction1 item, and then change its name to MyCustomAction.

In the Output window, a confirmation message appears. This message is written by the ProjectItemNameChanged event handler that 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's a child of the MyCustomAction project item.
In the Elements.xml file, make the following changes, and then save the file:
- In the CustomAction element, set the Id attribute to a GUID or some other unique string as the following example shows:
```
Id="cd85f6a7-af2e-44ab-885a-0c795b52121a"
```
- In the CustomAction element, set the Title attribute as the following example shows:
```
Title="SharePoint Developer Center"
```
- In the CustomAction element, set the Description attribute as the following example shows:
```
Description="Opens the SharePoint Developer Center Web site."
```
- In the UrlAction element, set the Url attribute as the following example shows:
```
Url="https://docs.microsoft.com/sharepoint/dev/"
```
Choose the F5 key.

The custom action is packaged and deployed to the SharePoint site that's specified in 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 appears, choose the Yes button to continue to debug the project.
On the Site Actions menu, choose SharePoint Developer Center, verify that the browser opens the website https://docs.microsoft.com/sharepoint/dev/, and then close the web browser.

Clean 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 menu bar, choose Tools > Extensions and Updates.

The Extensions and Updates dialog box opens.
In the list of extensions, choose Custom Action Project Item, and then choose the Uninstall button.
In the dialog box that appears, choose the Yes button to confirm that you want to uninstall the extension.
Choose the Restart Now button to complete the uninstallation.
Close both the experimental instance of Visual Studio and the instance in which the CustomActionProjectItem solution is 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 action (such as its location and the URL to navigate to when the action is chosen) and adds this information to the Elements.xml file in the new project item. For more information, see Walkthrough: Create a custom action project item with an item template, Part 2.

Walkthrough: Create a custom action project item with an item template, Part 1

Prerequisites

Create the projects

To create the VSIX project

To create the item template project

To create the extension project

Configure the extension project

To configure the project

Define the new SharePoint project item type

To define the new SharePoint project item type

Create an icon for the project item in Solution Explorer

To create a custom icon for the project item

Checkpoint

To build your project

Create a Visual Studio item template

To create the item template

Create a VSIX package to deploy the project item

To configure and create the VSIX package

Test the project item

To start debugging the solution

To test the project item in Visual Studio

To test the custom action in SharePoint

Clean up the development computer

To clean up the development computer

Next steps

See also

Additional resources