How to: Add a Property to a Custom SharePoint Project Item Type
When you define a custom SharePoint project item type, you can add a property to the project item. The property appears in the Properties window when the project item is selected in Solution Explorer.
The following steps assume that you have already defined your own SharePoint project item type. For more information, see How to: Define a SharePoint Project Item Type.
To add a property to a definition of a project item type
Define a class with a public property that represents the property you are adding to the custom project item type. If you want to add multiple properties to a custom project item type, you can define all the properties in the same class or in different classes.
In the InitializeType method of your ISharePointProjectItemTypeProvider implementation, handle the ProjectItemPropertiesRequested event of the projectItemTypeDefinition parameter.
In the event handler for the ProjectItemPropertiesRequested event, add an instance of your custom properties class to the PropertySources collection of the event arguments parameter.
Example
The following code example demonstrates how to add a property named Example Property to a custom project item type.
Imports System
Imports System.ComponentModel
Imports System.ComponentModel.Composition
Imports Microsoft.VisualStudio.SharePoint
Namespace Contoso.Examples.ProjectItemTypeWithProperty
<Export(GetType(ISharePointProjectItemTypeProvider))> _
<SharePointProjectItemType("Contoso.ExampleProjectItemType")> _
<SharePointProjectItemIcon("ExampleProjectItemType.ProjectItemIcon.ico")> _
Friend Class ExampleProjectItemTypeWithProperty
Implements ISharePointProjectItemTypeProvider
Private Sub InitializeType(ByVal projectItemTypeDefinition As ISharePointProjectItemTypeDefinition) _
Implements ISharePointProjectItemTypeProvider.InitializeType
projectItemTypeDefinition.Name = "ExampleProjectItemType"
projectItemTypeDefinition.SupportedDeploymentScopes = _
SupportedDeploymentScopes.Site Or SupportedDeploymentScopes.Web
projectItemTypeDefinition.SupportedTrustLevels = SupportedTrustLevels.All
AddHandler projectItemTypeDefinition.ProjectItemPropertiesRequested, AddressOf ProjectItemPropertiesRequested
End Sub
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
End Class
Friend Class CustomProperties
Private projectItem As ISharePointProjectItem
Friend Sub New(ByVal projectItem As ISharePointProjectItem)
Me.projectItem = projectItem
End Sub
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
End Class
End Namespace
using System;
using System.ComponentModel;
using System.ComponentModel.Composition;
using Microsoft.VisualStudio.SharePoint;
namespace Contoso.Examples.ProjectItemTypeWithProperty
{
[Export(typeof(ISharePointProjectItemTypeProvider))]
[SharePointProjectItemType("Contoso.ExampleProjectItemType")]
[SharePointProjectItemIcon("ExampleProjectItemType.ProjectItemIcon.ico")]
internal class ExampleProjectItemTypeWithProperty : ISharePointProjectItemTypeProvider
{
public void InitializeType(ISharePointProjectItemTypeDefinition projectItemTypeDefinition)
{
projectItemTypeDefinition.Name = "ExampleProjectItemType";
projectItemTypeDefinition.SupportedDeploymentScopes =
SupportedDeploymentScopes.Site | SupportedDeploymentScopes.Web;
projectItemTypeDefinition.SupportedTrustLevels = SupportedTrustLevels.All;
projectItemTypeDefinition.ProjectItemPropertiesRequested +=
projectItemTypeDefinition_ProjectItemPropertiesRequested;
}
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);
}
}
internal class CustomProperties
{
private ISharePointProjectItem projectItem;
internal CustomProperties(ISharePointProjectItem projectItem)
{
this.projectItem = projectItem;
}
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);
}
}
}
}
}
Understanding the Code
To ensure that the same instance of the CustomProperties class is used each time the ProjectItemPropertiesRequested event occurs, the code example saves the properties object to the Annotations property of the project item the first time this event occurs. The code retrieves this object whenever this event occurs again. For more information about using the Annotations property to save data with project items, see Associating Custom Data with SharePoint Tools Extensions.
To persist changes to the property value, the set accessor for ExampleProperty saves the new value to the ExtensionData property of the ISharePointProjectItem object that the property is associated with. For more information about using the ExtensionData property to persist data with project items, see Saving Data in Extensions of the SharePoint Project System.
Specifying the Behavior of Custom Properties
You can define how a custom property appears and behaves in the Properties window by applying attributes from the System.ComponentModel namespace to the property definition. The following attributes are useful in many scenarios:
DisplayNameAttribute: Specifies the name of the property that appears in the Properties window.
DescriptionAttribute: Specifies the description string that appears in the bottom of the Properties window when the property is selected.
DefaultValueAttribute: Specifies the default value of the property.
TypeConverterAttribute: Specifies a custom conversion between the string that is displayed in the Properties window and a non-string property value.
EditorAttribute: Specifies a custom editor to use to modify the property.
Compiling the Code
These code examples require a class library project with references to the following assemblies:
Microsoft.VisualStudio.SharePoint
System.ComponentModel.Composition
Deploying the Project Item
To enable other developers to use your project item, create a project template or a project item template. For more information, see Creating Item Templates and Project Templates for SharePoint Project Items.
To deploy the project item, create a Visual Studio extension (VSIX) package for the assembly, the template, and any other files that you want to distribute with the project item. For more information, see Deploying Extensions for the SharePoint Tools in Visual Studio.
See Also
Concepts
How to: Define a SharePoint Project Item Type
How to: Add a Shortcut Menu Item to a Custom SharePoint Project Item Type