We recommend using Visual Studio 2017
This documentation is archived and is not being maintained.

Associating Custom Data with SharePoint Tools Extensions

You can add custom data to certain objects in SharePoint tools extensions. This is useful when you have data in one part of your extension that you want to access later from other code in your extension. Instead of implementing a custom way to store and access data, you can associate the data with an object in your extension and then retrieve the data from the same object later.

Adding custom data to objects is also useful when you want to preserve data that is relevant to a specific item in Visual Studio. SharePoint tools extensions are loaded just once in Visual Studio, so your extension might work with several different items (such as projects, project items, or Server Explorer nodes) at any time. If you have custom data that is relevant only to a specific item, you can add the data to the object that represents that item.

When you add custom data to objects in SharePoint tools extensions, the data does not persist. The data is available only during the lifespan of the object. After the object is reclaimed by garbage collection, the data is lost.

In extensions of the SharePoint project system, you can also save string data that persists after an extension is unloaded. For more information, see Saving Data in Extensions of the SharePoint Project System.

To add custom data to an object in a SharePoint tools extension, get the Annotations property of the object you want to add the data to, and then use the IAnnotationDictionary.Add() method to add the data to the object.

To retrieve custom data from an object in a SharePoint tools extension, get the Annotations property of the object and then use one of the following methods:

  • IAnnotationDictionary.TryGetValue(). This method returns true if the data object exists, or false if it does not exist. You can use this method to retrieve instances of value types or reference types.

  • IAnnotationDictionary.GetValue(). This method returns the data object if it exits, or null if it does not exist. You can use this method only to retrieve instances of reference types.

The following code example determines whether a certain data object is already associated with a project item. If the data object is not already associated with the project item, then the code adds the object to the Annotations property of the project item. To see this example in the context of a larger example, see How to: Add a Property to a Custom SharePoint Project Item Type.

void projectItemTypeDefinition_ProjectItemPropertiesRequested(object sender, 
    SharePointProjectItemPropertiesRequestedEventArgs e)
    CustomProperties property;

    // If the properties object already exists, get it from the project item's annotations.
    if (!e.ProjectItem.Annotations.TryGetValue(out property))
        // Otherwise, create a new properties object and add it to the annotations.
        property = new CustomProperties(e.ProjectItem);