Cómo: Agregar una propiedad a una extensión de elemento de proyecto de SharePoint

Artículo
02/19/2013

Puede usar una extensión de elemento de proyecto para agregar una propiedad a cualquier elemento de proyecto de SharePoint que ya se encuentre instalado en Visual Studio.La propiedad aparece en la ventana Propiedades cuando se selecciona el elemento de proyecto en el Explorador de soluciones.

En los siguientes pasos se da por supuesto que ha creado una extensión de elemento de proyecto.Para obtener más información, vea Cómo: Crear una extensión de elemento de proyecto de SharePoint.

Para agregar una propiedad a una extensión de elemento de proyecto

Defina una clase con una propiedad pública que represente la propiedad que va a agregar a un tipo de elemento de proyecto.Si desea agregar varias propiedades a un tipo de elemento de proyecto, puede definirlas todas en la misma clase o en clases diferentes.
En el método Initialize de la implementación ISharePointProjectItemTypeExtension, controle el evento ProjectItemPropertiesRequested del parámetro projectItemType.
En el controlador de eventos del evento ProjectItemPropertiesRequested, agregue una instancia de la clase de propiedades a la colección PropertySources del parámetro de argumentos del evento.

Ejemplo

En el siguiente ejemplo de código se muestra cómo agregar una propiedad denominada Example Property al elemento de proyecto de receptor de eventos.

Imports System
Imports System.ComponentModel
Imports System.ComponentModel.Composition
Imports Microsoft.VisualStudio.SharePoint

Namespace Contoso.Examples.ProjectItemExtensionWithProperty

    <Export(GetType(ISharePointProjectItemTypeExtension))> _
    <SharePointProjectItemType("Microsoft.VisualStudio.SharePoint.EventHandler")> _
    Friend Class ExampleProjectItemExtensionWithProperty
        Implements ISharePointProjectItemTypeExtension

        Private Sub Initialize(ByVal projectItemType As ISharePointProjectItemType) _
            Implements ISharePointProjectItemTypeExtension.Initialize
            AddHandler projectItemType.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.ProjectItemExtensionWithProperty
{
    [Export(typeof(ISharePointProjectItemTypeExtension))]
    [SharePointProjectItemType("Microsoft.VisualStudio.SharePoint.EventHandler")]
    internal class ExampleProjectItemExtensionWithProperty : ISharePointProjectItemTypeExtension
    {
        public void Initialize(ISharePointProjectItemType projectItemType)
        {
            projectItemType.ProjectItemPropertiesRequested += 
                projectItemType_ProjectItemPropertiesRequested;
        }

        void projectItemType_ProjectItemPropertiesRequested(object sender, 
            SharePointProjectItemPropertiesRequestedEventArgs e)
        {
            CustomProperties propertyObject;

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

            e.PropertySources.Add(propertyObject);
        }
    }

    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);
                }
            }
        }
    }
}

Introducción al código

Para garantizar que se usa la misma instancia de la clase CustomProperties cada vez que se genera el evento ProjectItemPropertiesRequested, en el ejemplo de código se agrega el objeto de propiedades a la propiedad Annotations del elemento de proyecto la primera vez que se genera este evento.El código recupera este objeto cada vez que el evento se genera.Para obtener más información sobre el uso de la propiedad Annotations para asociar los datos con los elementos de proyecto, vea Asociar datos personalizados con extensiones de herramientas de SharePoint.

Para conservar los cambios en el valor de propiedad, el descriptor de acceso set de la propiedad ExampleProperty guarda el nuevo valor en la propiedad ExtensionData del objeto ISharePointProjectItem al que está asociada la propiedad.Para obtener más información sobre el uso de la propiedad ExtensionData para mantener los datos con los elementos de proyecto, vea Guardar datos asociados en extensiones del sistema de proyectos de SharePoint.

Especificar el comportamiento de las propiedades personalizadas

Puede definir el aspecto y comportamiento de una propiedad personalizada en la ventana Propiedades aplicando los atributos del espacio de nombres System.ComponentModel a la definición de la propiedad.Los siguientes atributos son útiles en muchos escenarios:

DisplayNameAttribute: especifica el nombre de la propiedad que aparece en la ventana Propiedades.
DescriptionAttribute: especifica la cadena descriptiva que aparece en la parte inferior de la ventana Propiedades cuando la propiedad está seleccionada.
DefaultValueAttribute especifica el valor predeterminado de la propiedad.
TypeConverterAttribute: especifica una conversión personalizada entre la cadena que se muestra en la ventana Propiedades y un valor de propiedad que no es de cadena.
EditorAttribute: especifica un editor personalizado para modificar la propiedad.

Compilar el código

En estos ejemplos se requiere un proyecto de biblioteca de clases con referencias a los siguientes ensamblados:

Microsoft.VisualStudio.SharePoint
System.ComponentModel.Composition

Implementar la extensión

Para implementar la extensión, cree un paquete de extensión (VSIX) de Visual Studio para el ensamblado y el resto de archivos que desee distribuir con la extensión.Para obtener más información, vea Extensiones de implementación para las Herramientas de SharePoint en Visual Studio.