Extending the SharePoint Tools in Visual Studio: An Overview

Since you’re reading this blog, you’re probably aware that Visual Studio 2010 includes an all-new set of tools for creating SharePoint solutions for Microsoft SharePoint Foundation 2010 and Microsoft SharePoint Server 2010. These tools include a set of project and item templates for developing various types of solutions, integrated Feature and packaging support (with designers), and the SharePoint Connections node in Server Explorer.

However, you might not know that the SharePoint tools include a comprehensive extensibility model. This extensibility model is public and fully documented. In fact, all of the built-in tools were implemented by using same extensibility model that you can use to create your own extensions. A number of Visual Studio extensions that were built by using this extensibility API are already available, such as VSeWSSImport and vsixforsp.

The purpose of this post is to provide a high-level overview of the different ways you can extend the SharePoint tools, with some pointers to relevant topics and code examples in the documentation.

Introduction to the Extensibility Model

To extend the SharePoint tools in Visual Studio 2010, you use types in three assemblies that are included with Visual Studio:

• Microsoft.VisualStudio.SharePoint.dll
• Microsoft.VisualStudio.SharePoint.Commands.dll
• Microsoft.VisualStudio.SharePoint.Explorer.Extensions.dll.

For the rest of the post I'll refer to these collectively as the SharePoint tools API. You can think of this API as an abstraction layer on top of the Visual Studio automation object model (DTE and related types) and integration object model (VSPackages and related types). When you create extension for the SharePoint tools, you always work directly with the SharePoint tools API, but you can also call into the automation and integration object models if you need to leverage functionality that is provided only in those object models.

The SharePoint tools API consists of two main groups of types:

• Extensibility interfaces that you implement as the basis for an extension of the SharePoint tools. To extend a particular feature of the SharePoint tools, you implement an interface that is defined by the SharePoint tools and apply the Export attribute (and additional attributes as necessary) to your interface implementation. There are a handful of extensibility interfaces provided by the SharePoint tools, including ISharePointProjectItemTypeExtension, ISharePointProjectItemTypeProvider, and ISharePointProjectExtension. The SharePoint tools use the Managed Extensibility Framework (MEF) to expose extensibility interfaces and to manage extensions.

• Other types that represent components that you can modify or automate in extensions (such as ISharePointProject and ISharePointProjectItem, which represent a SharePoint project and project item, respectively), and other supporting types such as delegates, attributes, and enumerations. Most of the types in the SharePoint tools API fall into this category.

There are two main feature areas that you can extend: the SharePoint project system and the SharePoint Connections node in Server Explorer.

SharePoint Project System

The SharePoint project system refers to the components and functionality that are available in a SharePoint project. At the highest level, this includes the project itself, each SharePoint project item in the project, and other contents of the project such as mapped folders, Feature definitions, and the package definition. A SharePoint project item (or SPI for short) represents a specific SharePoint customization - for example, a Web Part, an event receiver, or list definition. In a SharePoint project that is open in Solution Explorer, each SharePoint project item is represented by a node with an icon that identifies the item type. This node can contain additional files that are associated with the project item, such as Elements.xml files or code files.

The Microsoft.VisualStudio.SharePoint namespace contains most of the main types in the SharePoint project system, such as ISharePointProject and ISharePointProjectItem. Other project system types are also provided in the Microsoft.VisualStudio.SharePoint.Deployment, Microsoft.VisualStudio.SharePoint.Features, Microsoft.VisualStudio.SharePoint.Packages, and Microsoft.VisualStudio.SharePoint.Validation namespaces.

You can extend the SharePoint project system in the following ways:

• Create an extension for a particular type of SPI, such as the built-in List Definition project item. Your extension is loaded only when an instance of the targeted SPI type is in a project that is open in Visual Studio. For more information and related code examples, see Extending SharePoint Project Items in the MSDN documentation.

• Create your own new type of SPI, which you can associate with an item template or project template. You can even implement your own wizard that appears when a customer adds your SPI to a project, or creates a new project that includes your SPI. For more information and related code examples, see Defining Custom SharePoint Project Item Types in the MSDN documentation.

• Create an extension for SharePoint projects. Your extension is loaded whenever any type of SharePoint project is open in Visual Studio. For more information and related code examples, see Extending SharePoint Projects in the MSDN documentation.

• Extend the packaging and deployment behavior of a SharePoint project or SPI. For example, you can create your own deployment steps or deployment configurations, handle various deployment-related events, or create your own validation rules for Features and package definitions. For more information and related code examples, see Extending SharePoint Packaging and Deployment in the MSDN documentation.

There are a number of tasks you can perform in extensions of the SharePoint project system. For example, you can add custom properties to SharePoint projects or particular types of SPIs (these properties appear in the Properties window when a project or SPI is selected in Solution Explorer), add your own context menu items to SharePoint projects or particular types of SPIs (these menu items appear when you right click the project or SPI in Solution Explorer), and you can handle many different events that are raised by SharePoint projects and SPIs in various scenarios. The MSDN topics I link to above provide how-to topics and walkthroughs that demonstrate all of these tasks.

SharePoint Connections Node in Server Explorer

The new SharePoint Connections node in Server Explorer is intended to be used to browse the contents of local SharePoint sites on your development computer. After you add a connection to a local SharePoint site, many (but not all) of the components of the site are displayed here in a hierarchical tree view. This can help provide a quick, comprehensive view of the site while you are working on a new SharePoint solution that you plan to deploy to it. For an overview of how this feature is used, see Browsing SharePoint Connections Using Server Explorer.

The Microsoft.VisualStudio.SharePoint.Explorer and Microsoft.VisualStudio.SharePoint.Explorer.Extensions namespaces contain the types that you can use to extend the SharePoint Connections node.

You can extend the SharePoint Connections node in the following ways:

• Extend a node, such as the node that represents fields, lists, or content types. For a code example and step-by-step instructions, see How to: Extend a SharePoint Node in Server Explorer in the MSDN documentation.

• Create a new type of node. For example, you might want to do this if you want to create an extension that can display components of SharePoint sites that the built-in SharePoint Connections node does not support, such as Web Parts. For a code example and step-by-step instructions, see How to: Add a Custom SharePoint Node to Server Explorer in the MSDN documentation.

As with the project system, you can also add custom properties and context menu items to nodes, and there are a number of different events you can handle. The MSDN topics I link to above provide how-to topics and walkthroughs that demonstrate all of these tasks.

Important Features

The following features play an important role in most extensions of the SharePoint tools.

SharePoint Commands

Most extensions need to call into the SharePoint APIs to perform some work, such as determining whether a particular file exists on a SharePoint site or adding or deleting content from a site. Although the 2010 releases of SharePoint now include a client object model, most SharePoint tools extensions should use the "traditional" server object model, because the client object model was designed to be used to call into remote SharePoint installations, not local installations. However, the SharePoint server object model cannot be called directly from SharePoint tools extensions, because the SharePoint server object model can be called only from 64-bit processes that target the .NET Framework 3.5, but SharePoint tools extensions are run in the Visual Studio process, which is a 32-bit process that targets the .NET Framework 4.

To bridge this gap, the Visual Studio tools include the concept of a SharePoint command. A SharePoint command is essentially an intermediary method that can call into the SharePoint server object model directly, and that can be called by your extension. For a nuts-and-bolts explanation of how this works, see Calling into the SharePoint Object Models, How to: Create a SharePoint Command, and How to: Execute a SharePoint Command in the MSDN documentation.

SharePoint Service

The Visual Studio tools provide a special service object, called the SharePoint service, which provides a number of different features such as the ability to convert some types in the SharePoint tools API to types in the Visual Studio automation and integration object models, execute a SharePoint command, and access any open SharePoint project or project item. For more information, see Using the SharePoint Project Service in the MSDN documentation.

Related Walkthroughs

For end-to-end walkthroughs that demonstrate how to implement, deploy, and test different types of SharePoint tools extensions, see the following walkthroughs in the MSDN documentation.

Project System Extensions

• Walkthrough: Extending a SharePoint Project Item Type: Demonstrates how to extend the built-in Business Data Connectivity Model project item type. 

• Walkthrough: Creating a SharePoint Project Extension: Demonstrates how to add a custom property to all SharePoint projects. Developers can use the property to add or remove a mapped folder.

• Walkthrough: Creating a Custom Action Project Item with an Item Template, Part 1: Demonstrates how to define a SharePoint project item type for creating a custom action in SharePoint, and associating an item template with the new project item type.

• Walkthrough: Creating a Custom Action Project Item with an Item Template, Part 2: Demonstrates how to create a wizard for a custom SharePoint project item type that is associated with an item template. 

• Walkthrough: Creating a Site Column Project Item with a Project Template, Part 1: Demonstrates how to define a SharePoint project item type for creating a site column in SharePoint, and associating a project template with the new project item type. 

• Walkthrough: Creating a Site Column Project Item with a Project Template, Part 2: Demonstrates how to create a wizard for a custom SharePoint project item type that is associated with a project template. 

• Walkthrough: Creating a Custom Deployment Step for SharePoint Projects: Demonstrates how to define a custom deployment step that can be used to upgrade SharePoint solutions.

Extensions of the SharePoint Connections Node in Server Explorer

• Walkthrough: Extending Server Explorer to Display Web Parts: Demonstrates how to add new nodes for displaying Web Parts in SharePoint sites that are displayed in Server Explorer. This walkthrough also demonstrates how to create a SharePoint command to call into the SharePoint server object model. 

• Walkthrough: Calling into the SharePoint Client Object Model in a Server Explorer Extension: Demonstrates how to add new nodes for displaying Web Parts in SharePoint sites that are displayed in Server Explorer. This walkthrough also demonstrates how to use the SharePoint client object model.

McLean Schofield