Export (0) Print
Expand All
This topic has not yet been rated - Rate this topic

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

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.

NoteNote

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

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

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

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

  1. Start Visual Studio.

  2. On the File menu, point to New, and then click Project.

  3. In the combo box at the top of the New Project dialog box, make sure that .NET Framework 4 is selected.

  4. In the New Project dialog box, expand the Visual C# or Visual Basic nodes, and then click the Extensibility node.

    NoteNote

    The Extensibility node is available only if you install the Visual Studio 2010 SDK. For more information, see the prerequisites section above.

  5. Click the VSIX Project template.

  6. In the Name box, type CustomActionProjectItem.

  7. Click OK.

    Visual Studio adds the CustomActionProjectItem project to Solution Explorer.

To create the item template project

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

    NoteNote

    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.

  2. In the combo box at the top of the New Project dialog box, make sure that .NET Framework 4 is selected.

  3. In the New Project dialog box, expand the Visual C# or Visual Basic nodes, and then click the Extensibility node.

  4. In the list of project templates, select C# Item Template or Visual Basic Item Template.

  5. In the Name box, type ItemTemplate.

  6. Click OK.

    Visual Studio adds the ItemTemplate project to the solution.

To create the extension project

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

  2. In the combo box at the top of the New Project dialog box, make sure that .NET Framework 4 is selected.

  3. In the New Project dialog box, expand the Visual C# or Visual Basic nodes, and then click the Windows node.

  4. Select the Class Library project template.

  5. In the Name box, type ProjectItemDefinition.

  6. Click OK.

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

  7. Delete the Class1 code file from the 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

  1. In the ProjectItemDefinition project, add a code files with the name CustomAction.

  2. On the Project menu, click Add Reference.

  3. On the .NET tab, press CTRL and click the following assemblies, and then click OK:

    • Microsoft.VisualStudio.SharePoint

    • System.ComponentModel.Composition

    • System.Windows.Forms

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

  1. In the ProjectItemDefinition project, open the CustomAction code file.

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

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

  1. In Solution Explorer, right-click the ProjectItemDefinition project.

  2. On the shortcut menu, point to Add, and then click New Item.

  3. In the list of project items, click Icon File.

    NoteNote

    In Visual Basic projects, you must click the General node to see the Icon File item.

  4. Type CustomAction_SolutionExplorer.ico for the new icon name, and click Add.

    The new icon opens in the Image Editor.

  5. Edit the 16x16 version of the icon file so that it has a design you can recognize, and then save the icon file.

  6. In Solution Explorer, click CustomAction_SolutionExplorer.ico.

  7. In the Properties window, click the drop-down next to Build Action and then click Embedded Resource.

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.

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

  1. Delete the Class1 code file from the ItemTemplate project.

  2. In the ItemTemplate project, open the ItemTemplate.vstemplate file.

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

    NoteNote

    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="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.

  4. In Solution Explorer, right-click the ItemTemplate project, click Add, and then click New Item.

  5. In the Add New Item dialog, select Text File, type CustomAction.spdata in the Name field, and click Add.

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

  7. In Solution Explorer, right-click the ItemTemplate project, click Add, and then click New Item.

  8. In the Add New Item dialog, select XML File, type Elements.xml in the Name field, and click Add.

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

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

  11. In Solution Explorer, right-click the ItemTemplate project and click Unload Project.

  12. Right-click the ItemTemplate project again and click Edit ItemTemplate.csproj or Edit ItemTemplate.vbproj.

  13. Locate the following VSTemplate element in the project file.

    <VSTemplate Include="ItemTemplate.vstemplate">
    
  14. 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.

  15. Save and close the file.

  16. In Solution Explorer, right-click the ItemTemplate project and click Reload Project.

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

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

  2. In the Product Name box, type Custom Action Project Item.

  3. In the Author box, type Contoso.

  4. In the Description box, type A SharePoint project item that represents a custom action.

  5. In the Content section of the editor, click the Add Content button.

  6. In the Add Content dialog box, in the Select a content type list box, select Item Template.

    NoteNote

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

  7. Under Select a source, click the Project radio button, and select ItemTemplate in the list box next to it.

  8. Click OK.

  9. In the manifest editor, click the Add Content button again.

  10. In the Add Content dialog box, in the Select a content type list box, select MEF Component.

    NoteNote

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

  11. Under Select a source, click the Project radio button, and select ProjectItemDefinition in the list box next to it.

  12. Click OK.

  13. On the Build menu, click Build Solution. Make sure that the project compiles without errors.

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

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

  1. Restart Visual Studio with administrator privileges and open the CustomActionProjectItem solution.

  2. Open the CustomAction code file, and add a breakpoint to the first line of code in the InitializeType method.

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

  1. In the experimental instance of Visual Studio, on the File menu, point to New, and then click Project.

  2. Expand Visual C# or Visual Basic (depending on the language your item template supports), expand SharePoint, and then click 2010.

  3. In the list of project templates, click Empty Project.

  4. In the Name box, type CustomActionTest.

  5. Click OK.

  6. In the SharePoint Customization Wizard, type the URL of the site that you want to use for debugging, and click Finish.

  7. In Solution Explorer, right-click the project node, point to Add, and then click New Item.

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

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

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

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

  12. On the View menu, click Output.

    The Output window opens.

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

  1. In the experimental instance of Visual Studio, open the Elements.xml file that is a child of the MyCustomAction project item.

  2. 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="http://msdn.microsoft.com/sharepoint/default.aspx"
      
  3. Save the Elements.xml file.

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

    NoteNote

    If the Script Debugging Disabled dialog box is displayed, click Yes to continue to debug the project.

  5. Click the Site Actions menu. Verify that the custom action named SharePoint Developer Center appears at the bottom of this menu.

  6. Click the SharePoint Developer Center menu item. Verify that the browser opens the Web site http://msdn.microsoft.com/sharepoint/default.aspx.

  7. Close the Web browser.

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

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

    The Extension Manager dialog box opens.

  2. In the list of extensions, click Custom Action Project Item, and then click Uninstall.

  3. In the dialog box that appears, click Yes to confirm that you want to uninstall the extension.

  4. Click Restart Now to complete the uninstallation.

  5. Close both instances of Visual Studio (the experimental instance and the instance of Visual Studio that has the CustomActionProjectItem solution open).

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.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.