Associating Custom Data with SharePoint Tools Extensions

Article
02/04/2013

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.

Objects that Can Contain Custom Data

You can add custom data to any object in the SharePoint tools object model that implements the IAnnotatedObject interface. This interface defines just one property, Annotations, which is a collection of custom data objects. The following types implement IAnnotatedObject:

Adding and Retrieving Custom Data

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.

Private Sub ProjectItemPropertiesRequested(ByVal Sender As Object,
    ByVal e As SharePointProjectItemPropertiesRequestedEventArgs)
    Dim propertyObject As CustomProperties = Nothing

    ' If the properties object already exists, get it from the project item's annotations.
    If False = e.ProjectItem.Annotations.TryGetValue(propertyObject) Then
        ' Otherwise, create a new properties object and add it to the annotations.
        propertyObject = New CustomProperties(e.ProjectItem)
        e.ProjectItem.Annotations.Add(propertyObject)
    End If
    e.PropertySources.Add(propertyObject)
End Sub

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);
        e.ProjectItem.Annotations.Add(property);
    }

    e.PropertySources.Add(property);
}

Share via

Associating Custom Data with SharePoint Tools Extensions

Objects that Can Contain Custom Data

Adding and Retrieving Custom Data

See Also

Tasks

Concepts

Additional resources