Procedura: aggiungere una proprietà a un'estensione di elemento di progetto SharePoint

Articolo
08/11/2011

È possibile utilizzare un'estensione di elemento di progetto per aggiungere una proprietà a qualsiasi elemento di progetto SharePoint già installato in Visual Studio. La proprietà viene visualizzata nella finestra Proprietà quando l'elemento di progetto viene selezionato in Esplora soluzioni.

I passaggi seguenti presuppongono che sia già stata creata un'estensione di elemento di progetto. Per ulteriori informazioni, vedere Procedura: creare un'estensione di elemento del progetto SharePoint.

Per aggiungere una proprietà a un'estensione di elemento di progetto

Definire una classe con una proprietà pubblica che rappresenta la proprietà da aggiungere a un tipo di elemento di progetto. Per aggiungere più proprietà a un tipo di elemento di progetto, è possibile definire tutte le proprietà nella stessa classe o in classi diverse.
Nel metodo Initialize dell'implementazione di ISharePointProjectItemTypeExtension gestire l'evento ProjectItemPropertiesRequested del parametro projectItemType.
Nel gestore dell'evento ProjectItemPropertiesRequested aggiungere un'istanza della classe di proprietà all'insieme PropertySources del parametro degli argomenti dell'evento.

Esempio

Nell'esempio di codice seguente viene illustrato come aggiungere una proprietà denominata Example Property all'elemento di progetto Ricevitore di eventi.

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

Informazioni sul codice

Per garantire che ogni volta che si verifica l'evento ProjectItemPropertiesRequested venga utilizzata la stessa istanza della classe CustomProperties, nell'esempio di codice l'oggetto delle proprietà viene aggiunto alla proprietà Annotations dell'elemento di progetto la prima volta che si verifica questo evento. Il codice recupera questo oggetto ogni volta che si verifica di nuovo questo evento. Per ulteriori informazioni sull'utilizzo della proprietà Annotations per associare i dati agli elementi di progetto, vedere Associazione di dati personalizzati alle estensioni degli strumenti di SharePoint.

Per rendere persistenti le modifiche al valore della proprietà, la funzione di accesso set della proprietà ExampleProperty salva il nuovo valore nella proprietà ExtensionData dell'oggetto ISharePointProjectItem a cui è associata la proprietà. Per ulteriori informazioni sull'utilizzo della proprietà ExtensionData per rendere persistenti i dati con gli elementi di progetto, vedere Salvataggio dei dati nelle estensioni del sistema di progetto SharePoint.

Specifica del comportamento delle proprietà personalizzate

È possibile definire la modalità di visualizzazione e il comportamento di una proprietà personalizzata nella finestra Proprietà applicando alla definizione di proprietà gli attributi ottenuti dallo spazio dei nomi System.ComponentModel. Gli attributi seguenti sono utili in molti scenari:

DisplayNameAttribute: specifica il nome della proprietà visualizzata nella finestra Proprietà.
DescriptionAttribute: specifica la stringa descrittiva visualizzata nella parte inferiore della finestra Proprietà quando si seleziona la proprietà.
DefaultValueAttribute: specifica il valore predefinito della proprietà.
TypeConverterAttribute: specifica una conversione personalizzata tra la stringa visualizzata nella finestra Proprietà e un valore di proprietà non di tipo stringa.
EditorAttribute: specifica un editor personalizzato da utilizzare per modificare la proprietà.

Compilazione del codice

Per questi esempi è necessario un progetto Libreria di classi con riferimenti agli assembly seguenti:

Microsoft.VisualStudio.SharePoint
System.ComponentModel.Composition

Distribuzione dell'estensione

Per distribuire l'estensione, creare un pacchetto Visual Studio Extension (VSIX) per l'assembly e qualsiasi altro file che si desidera distribuire con l'estensione. Per ulteriori informazioni, vedere Distribuzione di estensioni per gli strumenti di SharePoint in Visual Studio.