Saving Data in Extensions of the SharePoint Project System

Article
04/28/2015

When you extend the SharePoint project system, you can save string data that persists after a SharePoint project is closed. The data is typically associated with a particular project item or with the project itself.

If you have data that does not need to persist, you can add the data to any object in the SharePoint tools object model that implements the IAnnotatedObject interface. For more information, see Associating Custom Data with SharePoint Tools Extensions.

Saving Data That is Associated with a Project Item

When you have data that is associated with a particular SharePoint project item, such as the value of a property that you add to a project item, you can save the data to the .spdata file for the project item. To do this, use the ExtensionData property of an ISharePointProjectItem object. Data that you add to this property is saved in the ExtensionData element in the .spdata file for the project item. For more information, see ExtensionData Element.

The following code example demonstrates how to use the ExtensionData property to save the value of a string property that is defined in a custom SharePoint project item type. 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 Const TestPropertyId As String = "Contoso.ExampleProperty" 
Private Const PropertyDefaultValue As String = "This is an example property."

<DisplayName("Example Property")> _
<DescriptionAttribute("This is an example property for project items.")> _
<DefaultValue(PropertyDefaultValue)> _
Public Property ExampleProperty As String 
    Get 
        Dim propertyValue As String = Nothing 

        ' Get the current property value if it already exists; otherwise, return a default value. 
        If False = projectItem.ExtensionData.TryGetValue(TestPropertyId, propertyValue) Then
            propertyValue = PropertyDefaultValue
        End If 
        Return propertyValue
    End Get 
    Set(ByVal value As String)
        If value <> PropertyDefaultValue Then 
            ' Store the property value in the ExtensionData property of the project item. 
            ' Data in the ExtensionData property persists when the project is closed.
            projectItem.ExtensionData(TestPropertyId) = value
        Else 
            ' Do not save the default value.
            projectItem.ExtensionData.Remove(TestPropertyId)
        End If 
    End Set 
End Property

private const string PropertyId = "Contoso.ExampleProperty";
private const string PropertyDefaultValue = "This is an example property.";

[DisplayName("Example Property")]
[DescriptionAttribute("This is an example property for project items.")]
[DefaultValue(PropertyDefaultValue)]
public string ExampleProperty
{
    get
    {
        string propertyValue;

        // Get the current property value if it already exists; otherwise, return a default value. 
        if (!projectItem.ExtensionData.TryGetValue(PropertyId, out propertyValue))
        {
            propertyValue = PropertyDefaultValue;
        }
        return propertyValue;
    }
    set
    {
        if (value != PropertyDefaultValue)
        {
            // Store the property value in the ExtensionData property of the project item.  
            // Data in the ExtensionData property persists when the project is closed.
            projectItem.ExtensionData[PropertyId] = value;
        }
        else
        {
            // Do not save the default value.
            projectItem.ExtensionData.Remove(PropertyId);
        }
    }
}

Saving Data That is Associated with a Project

When you have project-level data, such as the value of a property that you add to SharePoint projects, you can save the data to the project file (the .csproj file or .vbproj file) or the project user option file (the .csproj.user file or .vbproj.user file). The file you choose to save the data in depends on how you want the data to be used:

If you want the data to be available to all developers who open the SharePoint project, save the data to the project file. This file is always checked in to source control databases, so the data in this file is available to other developers who check out the project.
If you want the data to be available only to the current developer who has the SharePoint project open in Visual Studio, save the data to the project user option file. This file is not typically checked in to source control databases, so the data in this file is not available to other developers who check out the project.

Saving Data to the Project File

To save data to the project file, convert an ISharePointProject object to an IVsBuildPropertyStorage object, and then use the IVsBuildPropertyStorage.SetPropertyValue method. The following code example demonstrates how to use this method to save the value of a project property to the project file. To see this example in the context of a larger sample, see How to: Add a Property to SharePoint Projects.

Private sharePointProject As ISharePointProject
Private projectStorage As IVsBuildPropertyStorage
Private Const ProjectFilePropertyId As String = "ContosoCustomProjectFileProperty" 
Private Const ProjectFilePropertyDefaultValue As String = "Default" 

Public Sub New(ByVal myProject As ISharePointProject)
    sharePointProject = myProject
    projectStorage = sharePointProject.ProjectService.Convert(Of ISharePointProject, IVsBuildPropertyStorage)(sharePointProject)
End Sub

<DisplayName("Custom Project File Property")> _
<DescriptionAttribute("This property is saved to the .csproj/.vbproj file.")> _
<DefaultValue(ProjectFilePropertyDefaultValue)> _
Public Property CustomProjectFileProperty As String 
    Get 
        Dim propertyValue As String = String.Empty
        Dim hr As Integer = projectStorage.GetPropertyValue(ProjectFilePropertyId, String.Empty, _
            CUInt(_PersistStorageType.PST_PROJECT_FILE), propertyValue)

        ' Try to get the current value from the project file; if it does not yet exist, return a default value. 
        If Not ErrorHandler.Succeeded(hr) Or String.IsNullOrEmpty(propertyValue) Then
            propertyValue = ProjectFilePropertyDefaultValue
        End If 
        Return propertyValue
    End Get 
    Set(ByVal value As String)
        ' Do not save the default value. 
        If value <> ProjectFilePropertyDefaultValue Then
            projectStorage.SetPropertyValue(ProjectFilePropertyId, String.Empty, _
                CUInt(_PersistStorageType.PST_PROJECT_FILE), value)
        End If 
    End Set 
End Property

private ISharePointProject sharePointProject;
private IVsBuildPropertyStorage projectStorage;
private const string ProjectFilePropertyId = "ContosoCustomProjectFileProperty";
private const string ProjectFilePropertyDefaultValue = "Default";

public CustomProjectProperties(ISharePointProject myProject)
{
    sharePointProject = myProject;
    projectStorage = sharePointProject.ProjectService.Convert<ISharePointProject, IVsBuildPropertyStorage>(sharePointProject);
}

[DisplayName("Custom Project File Property")]
[DescriptionAttribute("This property is saved to the .csproj/.vbproj file.")]
[DefaultValue(ProjectFilePropertyDefaultValue)]
public string CustomProjectFileProperty
{
    get
    {
        string propertyValue;
        int hr = projectStorage.GetPropertyValue(ProjectFilePropertyId, string.Empty, 
            (uint)_PersistStorageType.PST_PROJECT_FILE, out propertyValue);

        // Try to get the current value from the project file; if it does not yet exist, return a default value. 
        if (!ErrorHandler.Succeeded(hr) || String.IsNullOrEmpty(propertyValue))
        {
            propertyValue = ProjectFilePropertyDefaultValue;
        }

        return propertyValue;
    }

    set
    {
        // Do not save the default value. 
        if (value != ProjectFilePropertyDefaultValue)
        {
            projectStorage.SetPropertyValue(ProjectFilePropertyId, string.Empty, 
                (uint)_PersistStorageType.PST_PROJECT_FILE, value);
        }
    }
}

For more information about converting ISharePointProject objects to other types in the Visual Studio automation object model or integration object model, see Converting Between SharePoint Project System Types and Other Visual Studio Project Types.

Saving Data to the Project User Option File

To save data to the project user option file, use the ProjectUserFileData property of an ISharePointProject object. The following code example demonstrates how to use this property to save the value of a project property to the project user option file. To see this example in the context of a larger sample, see How to: Add a Property to SharePoint Projects.

Private Const UserFilePropertyId As String = "ContosoCustomUserFileProperty" 
Private Const UserFilePropertyDefaultValue As String = "Default"

<DisplayName("Custom Project User File Property")> _
<DescriptionAttribute("This property is saved to the .user file.")> _
<DefaultValue(UserFilePropertyDefaultValue)> _
Public Property CustomUserFileProperty As String 
    Get 
        Dim propertyValue As String = String.Empty
        ' Try to get the current value from the .user file; if it does not yet exist, return a default value. 
        If Not sharePointProject.ProjectUserFileData.TryGetValue(UserFilePropertyId, propertyValue) Then
            propertyValue = UserFilePropertyDefaultValue
        End If 
        Return propertyValue
    End Get 
    Set(ByVal value As String)
        ' Do not save the default value. 
        If value <> UserFilePropertyDefaultValue Then
            sharePointProject.ProjectUserFileData(UserFilePropertyId) = value
        End If 
    End Set 
End Property

private const string UserFilePropertyId = "ContosoCustomUserFileProperty";
private const string UserFilePropertyDefaultValue = "Default";

[DisplayName("Custom Project User File Property")]
[DescriptionAttribute("This property is saved to the .user file.")]
[DefaultValue(UserFilePropertyDefaultValue)]
public string CustomUserFileProperty
{
    get
    {
        string propertyValue = string.Empty;

        // Try to get the current value from the .user file; if it does not yet exist, return a default value. 
        if (!sharePointProject.ProjectUserFileData.TryGetValue(UserFilePropertyId, out propertyValue))
        {
            propertyValue = UserFilePropertyDefaultValue; 
        }

        return propertyValue; 
    }

    set
    {
        // Do not save the default value. 
        if (value != UserFilePropertyDefaultValue)
        {
            sharePointProject.ProjectUserFileData[UserFilePropertyId] = value;
        }
    }
}

Saving Data in Extensions of the SharePoint Project System

Saving Data That is Associated with a Project Item

Saving Data That is Associated with a Project

Saving Data to the Project File

Saving Data to the Project User Option File

See Also

Concepts

Additional resources