Walkthrough: Extending Server Explorer to Display Web Parts

In Visual Studio 2010, you can use the SharePoint Connections node of Server Explorer to view components on SharePoint sites. However, there are some components that Server Explorer does not display by default. In this walkthrough, you will extend Server Explorer so that it displays the Web Part gallery on each connected SharePoint site.

This walkthrough demonstrates the following tasks:

  • Creating a Visual Studio extension that extends Server Explorer in the following ways:

    • It adds a new Web Part Gallery node under each SharePoint site node in Server Explorer. This new node contains child nodes that represent each Web Part in the Web Part gallery on the site.

    • It defines a new type of node that represents a Web Part instance. This new node type is the basis for the child nodes under the new Web Part Gallery node. The new Web Part node type displays information in the Properties window about the Web Part it represents. The node type also includes a custom shortcut menu item that you can use as a starting point for performing other tasks related to the Web Part.

  • Creating two custom SharePoint commands that are called by the extension assembly. SharePoint commands are methods that can be called by extension assemblies to use APIs in the SharePoint server object model. In this walkthrough, you create commands that retrieve Web Part information from the local SharePoint site on the development computer. For more information, see Calling into the SharePoint Object Models.

  • Building a Visual Studio Extension (VSIX) package to deploy the extension.

  • Debugging and testing the extension.

NoteNote

For an alternate version of this walkthrough that uses the SharePoint client object model instead of the server object model, see Walkthrough: Calling into the SharePoint Client Object Model in a Server Explorer Extension.

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 to create the VSIX package to deploy the extension.

  • A class library project that implements the extension. This project must target the .NET Framework 4.

  • A class library project that defines the custom SharePoint commands. This project must target the.NET Framework 3.5.

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 New Project dialog box, expand the Visual C# or Visual Basic nodes, and then select 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.

  4. In the combo box at the top of the dialog box, select .NET Framework 4.

  5. Select the VSIX Project template.

  6. In the Name box, type WebPartNode.

  7. Click OK.

    Visual Studio adds the WebPartNode project to Solution Explorer.

To create the extension 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 New Project dialog box, expand the Visual C# or Visual Basic nodes, and then click Windows.

  3. In the combo box at the top of the dialog box, select .NET Framework 4.

  4. Select the Class Library project template.

  5. In the Name box, type WebPartNodeExtension.

  6. Click OK.

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

  7. Delete the Class1 code file from the project.

To create the SharePoint commands 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 New Project dialog box, expand the Visual C# or Visual Basic nodes, and then click Windows.

  3. In the combo box at the top of the dialog box, select .NET Framework 3.5.

  4. Select the Class Library project template.

  5. In the Name box, type WebPartCommands.

  6. Click OK.

    Visual Studio adds the WebPartCommands 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 create the extension, you have to add code files and assembly references, and configure the project settings.

To configure the WebPartNodeExtension project

  1. In the WebPartNodeExtension project, add four code files with the following names:

    • SiteNodeExtension

    • WebPartNodeTypeProvider

    • WebPartNodeInfo

    • WebPartCommandIds

  2. On the Project menu, click Add Reference.

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

    • Microsoft.VisualStudio.SharePoint

    • System.ComponentModel.Composition

    • System.Windows.Forms

  4. In Solution Explorer, right-click the WebPartNodeExtension project node, and select Properties.

    The Project Designer opens.

  5. Click the Application tab.

  6. In the Default namespace box (C#) or Root namespace box (Visual Basic), type ServerExplorer.SharePointConnections.WebPartNode.

To configure the WebPartCommands project

  1. In the WebPartCommands project, add a code file that is named WebPartCommands.

  2. In Solution Explorer, select the WebPartCommands project node.

  3. On the Project menu, select Add Existing Item.

  4. In the Add Existing Item dialog box, browse to the folder that contains the code files for the WebPartNodeExtension project.

  5. Select the WebPartNodeInfo and WebPartCommandIds code files.

  6. Click the drop-down menu for the Add button and select Add As Link.

    Visual Studio adds the code files to the WebPartCommands project as links. This means that the code files are located in the WebPartNodeExtension project, but the code in the files are also compiled in the WebPartCommands project.

  7. On the Project menu, click Add Reference.

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

    • Microsoft.SharePoint

    • Microsoft.VisualStudio.SharePoint.Commands

  9. In Solution Explorer, right-click the WebPartCommands project node, and select Properties.

    The Project Designer opens.

  10. Click the Application tab.

  11. In the Default namespace box (C#) or Root namespace box (Visual Basic), type ServerExplorer.SharePointConnections.WebPartNode.

Create two icons for the Server Explorer extension: an icon for the new Web Part Gallery node, and another icon for each child Web Part node under the Web Part Gallery node. Later in this walkthrough, you will write code that associates these icons with the nodes.

To create icons for the nodes

  1. In Solution Explorer, right-click the WebPartNodeExtension project node, and select Properties.

  2. On the Project menu, select WebPartNodeExtension Properties.

    The Project Designer opens.

  3. Click the Resources tab.

  4. Click This project does not contain a default resources file. Click here to create one.

    Visual Studio creates a resources file and opens it in the designer.

  5. At the top of the designer, click the drop-down arrow on the Add button, and then click Add New Icon.

  6. Type WebPartsNode for the new icon name, and click Add.

    The new icon opens in the Image Editor.

  7. Edit the 16x16 version of the icon so that it has a design you can easily recognize.

  8. Select the 32x32 version of the icon.

  9. On the Image menu, select Delete Image Type.

  10. Repeat steps 5 through 9 to add a second icon to the project resources. Name this icon WebPart.

  11. In Solution Explorer, under the Resources folder for the WebPartNodeExtension project, select WebPartsNode.ico.

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

  13. Repeat the last two steps for WebPart.ico.

Create a class that adds the new Web Part Gallery node to each SharePoint site node. To add the new node, the class implements the IExplorerNodeTypeExtension interface. Implement this interface whenever you want to extend the behavior of an existing node in Server Explorer, such as adding a new child node to a node.

To add the Web Part Gallery node to Server Explorer

  1. In the WebPartNodeExtension project, double-click the SiteNodeExtension code file.

  2. Paste the following code into this file.

    NoteNote

    After adding this code, the project will have some compile errors. These errors will go away when you add code in later steps.

    
    using System.Collections.Generic;
    using System.ComponentModel.Composition;
    using Microsoft.VisualStudio.SharePoint.Explorer;
    
    namespace ServerExplorer.SharePointConnections.WebPartNode
    {
        // Enables Visual Studio to discover and load this extension.
        [Export(typeof(IExplorerNodeTypeExtension))]        
    
        // Indicates that this class extends SharePoint site nodes in Server Explorer.
        [ExplorerNodeType(ExplorerNodeTypes.SiteNode)]
    
        // Represents an extension of SharePoint site nodes in Server Explorer.
        internal class SiteNodeExtension : IExplorerNodeTypeExtension
        {
            public void Initialize(IExplorerNodeType nodeType)
            {
                // The NodeChildrenRequested event is raised when the user expands the
                // SharePoint site node in Server Explorer.
                nodeType.NodeChildrenRequested += NodeChildrenRequested;
            }
    
            // Creates the new Web Part Gallery node with the specified icon.
            private void NodeChildrenRequested(object sender, ExplorerNodeEventArgs e)
            {
                // The CreateWebPartNodes argument is a delegate that Visual Studio calls 
                // to create the child nodes under the Web Part Gallery node.
                e.Node.ChildNodes.AddFolder("Web Part Gallery",
                    Properties.Resources.WebPartsNode.ToBitmap(), CreateWebPartNodes);
            }
    
            // Creates all of the individual Web Part nodes under the new Web Part Gallery node.
            private void CreateWebPartNodes(IExplorerNode parentNode)
            {
                // Call the custom SharePoint command to get items from the Web Part gallery.
                var webParts = parentNode.Context.SharePointConnection.ExecuteCommand<WebPartNodeInfo[]>(
                    WebPartCommandIds.GetWebParts);
    
                if (webParts != null)
                {
                    foreach (WebPartNodeInfo webPart in webParts)
                    {
                        // Create a new annotation object to store the current Web Part item with the new node.
                        var annotations = new Dictionary<object, object>() 
                        { 
                            { typeof(WebPartNodeInfo), webPart } 
                        };
    
                        // Create the new node for the current Web Part item.
                        parentNode.ChildNodes.Add(WebPartNodeTypeProvider.WebPartNodeTypeId,
                            webPart.Name, annotations);
                    }
                }
            }
        }
    }
    
    
    

Create a class that defines a new type of node that represents a Web Part. This new node type is used by Visual Studio to display child nodes under the Web Part Gallery node. Each of these child nodes represents a single Web Part on the SharePoint site.

To define the new node type, the class implements the IExplorerNodeTypeProvider interface. Implement this interface whenever you want to define a new type of node in Server Explorer.

To define the Web Part node type

  1. In the WebPartNodeExtension project, double-click the WebPartNodeTypeProvder code file.

  2. Paste the following code into this file.

    
    using System;
    using System.Collections.Generic;
    using System.Windows.Forms;
    using System.ComponentModel.Composition;
    using Microsoft.VisualStudio.SharePoint;
    using Microsoft.VisualStudio.SharePoint.Explorer;
    
    namespace ServerExplorer.SharePointConnections.WebPartNode
    {
        // Enables Visual Studio to discover and load this extension.
        [Export(typeof(IExplorerNodeTypeProvider))]
    
        // Specifies the ID for this new node type.
        [ExplorerNodeType(WebPartNodeTypeProvider.WebPartNodeTypeId)]
    
        // Defines a new node type that represents a Web Part on a SharePoint site.
        internal class WebPartNodeTypeProvider : IExplorerNodeTypeProvider
        {
            internal const string WebPartNodeTypeId = "Contoso.WebPart";
    
            public void InitializeType(IExplorerNodeTypeDefinition typeDefinition)
            {
                typeDefinition.DefaultIcon = Properties.Resources.WebPart.ToBitmap();
                typeDefinition.IsAlwaysLeaf = true;
                typeDefinition.NodePropertiesRequested += NodePropertiesRequested;
            }
    
            // Retrieves properties that are displayed in the Properties window when
            // a Web Part node is selected.
            private void NodePropertiesRequested(object sender,
                ExplorerNodePropertiesRequestedEventArgs e)
            {
                var webPartNodeInfo = e.Node.Annotations.GetValue<WebPartNodeInfo>();
    
                // Call the custom SharePoint command to get the Web Part properties.
                Dictionary<string, string> properties =
                    e.Node.Context.SharePointConnection.ExecuteCommand<
                    WebPartNodeInfo, Dictionary<string, string>>(
                    WebPartCommandIds.GetWebPartProperties, webPartNodeInfo);
    
                object propertySource = e.Node.Context.CreatePropertySourceObject(properties);
                e.PropertySources.Add(propertySource);
            }
        }
    }
    
    
    

Define a class that contains data about a single Web Part on the SharePoint site. Later in this walkthrough, you will create a custom SharePoint command that retrieves data about each Web Part on the site, and then assigns the data to instances of this class.

To define the Web Part data class

  1. In the WebPartNodeExtension project, double-click the WebPartNodeInfo code file.

  2. Paste the following code into this file.

    
    using System;
    
    namespace ServerExplorer.SharePointConnections.WebPartNode
    {
        // Contains basic data about a single Web Part on the SharePoint site. This class is 
        // serializable so that instances of it can be sent between the WebPartNode and 
        // WebPartCommands assemblies.
        [Serializable]
        public class WebPartNodeInfo
        {
            public Guid SiteId { get; set; }
            public int Id { get; set; }
            public Guid UniqueId { get; set; }
            public string Name { get; set; }
            public string ImageUrl { get; set; }
        }
    }
    
    
    

Define several strings that identify the custom SharePoint commands. You will implement these commands later in this walkthrough.

To define the command IDs

  1. In the WebPartNodeExtension project, double-click the WebPartCommandIds code file.

  2. Paste the following code into this file.

    
    namespace ServerExplorer.SharePointConnections.WebPartNode
    {
        public static class WebPartCommandIds
        {
            public const string GetWebParts = "WebPart.GetWebParts";
            public const string GetWebPartProperties = "WebPart.GetProperties";
        }
    }
    
    
    

Create custom commands that call into the SharePoint server object model to retrieve data about the Web Parts on the SharePoint site. Each command is a method that has the SharePointCommandAttribute applied to it.

To define the SharePoint commands

  1. In the WebPartCommands project, double-click the WebPartCommands code file.

  2. Paste the following code into this file.

    
    using System.Collections.Generic;
    using Microsoft.SharePoint;
    using Microsoft.VisualStudio.SharePoint.Commands;
    
    namespace ServerExplorer.SharePointConnections.WebPartNode
    {
        internal class WebPartsCommands
        {
            // Gets data for each Web Part on the SharePoint site, and returns an array of 
            // serializable objects that contain the data.
            [SharePointCommand(WebPartCommandIds.GetWebParts)]
            private static WebPartNodeInfo[] GetWebParts(ISharePointCommandContext context)
            {
                var nodeInfos = new List<WebPartNodeInfo>();
                SPListItemCollection webParts = context.Site.GetCatalog(
                    SPListTemplateType.WebPartCatalog).Items;
    
                foreach (SPListItem webPart in webParts)
                {
                    WebPartNodeInfo nodeInfo = new WebPartNodeInfo
                    {
                        Id = webPart.ID,
                        SiteId = webPart.ParentList.ParentWeb.ID,
                        Name = webPart.Title,
                        UniqueId = webPart.UniqueId,
                        ImageUrl = webPart.ParentList.ImageUrl
                    };
                    nodeInfos.Add(nodeInfo);
                }
    
                return nodeInfos.ToArray();
            }
    
            // Gets additional property data for a specific Web Part.
            [SharePointCommand(WebPartCommandIds.GetWebPartProperties)]
            private static Dictionary<string, string> GetWebPartProperties(ISharePointCommandContext context, 
                WebPartNodeInfo nodeInfo)
            {
                SPList webParts = context.Site.GetCatalog(SPListTemplateType.WebPartCatalog);
                SPListItem webPart = webParts.Items[nodeInfo.UniqueId];
    
                return SharePointCommandServices.GetProperties(webPart);
            }
        }
    }
    
    
    

At this point in the walkthrough, all the code for the Web Part Gallery node and the SharePoint commands are now in the projects. Build the solution to make sure that both projects compile without errors.

To build the solution

  • On the Build menu, select Build Solution.

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 the VSIX package

  1. In Solution Explorer, under the WebPartNode project, double-click the source.extension.vsixmanifest file.

    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 Web Part Gallery Node for Server Explorer.

  3. In the Author box, type Contoso.

  4. In the Description box, type Adds a custom Web Part Gallery node to the SharePoint Connections node in Server Explorer. This extension uses a custom SharePoint command to call into the server object model.

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

  7. Under Select a source, click the Project radio button, and select WebPartNodeExtension 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 Custom Extension Type.

    NoteNote

    This value corresponds to the CustomExtension element in the extension.vsixmanifest file. This element specifies a custom extension that you want to include in the Visual Studio extension. For more information, see CustomExtension Element (VSX Schema).

  11. In the Type text box, type SharePoint.Commands.v4.

    NoteNote

    This value corresponds to the Type attribute of the CustomExtension element in the extension.vsixmanifest file. The value Sharepoint.Commands.v4 is required for all custom extension assemblies that contain custom SharePoint commands.

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

  13. Click OK.

  14. On the Build menu, click Build Solution. Make sure that the solution compiles without errors.

  15. Open the build output folder for the WebPartNode project. Make sure that this folder now contains the WebPartNode.vsix file.

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

You are now ready to test the new Web Part Gallery node in Server Explorer. First, start debugging the extension in an experimental instance of Visual Studio. Then, use the new Web Parts node in the experimental instance of Visual Studio.

To start debugging the extension

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

  2. In the WebPartNodeExtension project, open the SiteNodeExtension code file and add a breakpoint to the first line of code in the NodeChildrenRequested and CreateWebPartNodes methods.

  3. Press F5 to start debugging.

    Visual Studio installs the extension to %UserProfile%\AppData\Local\Microsoft\VisualStudio\10.0Exp\Extensions\Contoso\Web Part Gallery Node Extension for Server Explorer\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 extension

  1. In the experimental instance of Visual Studio, on the View menu, click Server Explorer.

  2. Verify that the SharePoint site that you want to use for testing appears under the SharePoint Connections node in Server Explorer. If it is not listed, follow these steps:

    1. Right-click SharePoint Connections and then click Add Connection.

    2. In the Add SharePoint Connection dialog box, enter the URL for the SharePoint site that you want to connect to. To specify the SharePoint site on your development computer, type http://localhost.

    3. Click OK.

  3. Expand the site connection node (the node that displays the URL of your site), and then expand a child site node (for example, Team Site).

  4. Verify that the code in the other instance of Visual Studio stops on the breakpoint that you set earlier in the NodeChildrenRequested method. Press F5 to continue to debug the project.

  5. In the experimental instance of Visual Studio, verify that a new node named Web Part Gallery appears under the top-level site node. Expand the Web Part Gallery node.

  6. Verify that the code in the other instance of Visual Studio stops on the breakpoint that you set earlier in the CreateWebPartNodes method. Press F5 to continue to debug the project.

  7. In the experimental instance of Visual Studio, verify that all the Web Parts on the connected site appear under the Web Part Gallery node in Server Explorer.

  8. Right-click one of the Web Parts, and then click Properties.

  9. In the Visual Studio instance you are debugging, verify that details about the Web Part appear in the Properties window.

After you finish testing the extension, uninstall the extension from Visual Studio.

To uninstall the extension

  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, select Web Part Gallery Node Extension for Server Explorer, 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 WebPartNode solution open).

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft