Procedura: aggiungere una proprietà ai progetti SharePoint

Articolo
08/11/2011

Per aggiungere una proprietà a un progetto SharePoint, è possibile utilizzare un'estensione di progetto. La proprietà viene visualizzata nella finestra Proprietà quando il progetto viene selezionato in Esplora soluzioni.

Nei passaggi seguenti si suppone che sia già stata creata un'estensione di progetto. Per ulteriori informazioni, vedere Procedura: creare un'estensione di progetto SharePoint.

Per aggiungere una proprietà a un progetto SharePoint

Definire una classe con una proprietà pubblica che rappresenta la proprietà da aggiungere ai progetti SharePoint. Per aggiungere più proprietà, è possibile definire tutte le proprietà nella stessa classe o in classi diverse.
Nel metodo Initialize dell'implementazione di ISharePointProjectExtension gestire l'evento ProjectPropertiesRequested del parametro projectService.
Nel gestore dell'evento ProjectPropertiesRequested 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 due proprietà ai progetti SharePoint. Una proprietà consente di conservarne i dati nel file delle opzioni utente del progetto (il file csproj.user o vbproj.user). L'altra proprietà consente di conservarne i dati nel file di progetto (il file con estensione csproj o vbproj).

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

Namespace CustomSharePointProperty

    <Export(GetType(ISharePointProjectExtension))> _
    Partial Friend Class ProjectExtensionWithProperty
        Implements ISharePointProjectExtension

        Public Sub Initialize(ByVal projectService As ISharePointProjectService) _
            Implements ISharePointProjectExtension.Initialize
            AddHandler projectService.ProjectPropertiesRequested, _
                AddressOf ProjectPropertiesRequested
        End Sub

        Private Sub ProjectPropertiesRequested(ByVal sender As Object, _
            ByVal e As SharePointProjectPropertiesRequestedEventArgs)

            Dim propertiesObject As CustomProjectProperties = Nothing

            ' If the properties object already exists, get it from the project's annotations.
            If False = e.Project.Annotations.TryGetValue(propertiesObject) Then
                ' Otherwise, create a new properties object and add it to the annotations.
                propertiesObject = New CustomProjectProperties(e.Project)
                e.Project.Annotations.Add(propertiesObject)
            End If

            e.PropertySources.Add(propertiesObject)
        End Sub
    End Class

    Public Class CustomProjectProperties
        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 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
    End Class
End Namespace

using System;
using System.ComponentModel;
using System.ComponentModel.Composition;
using Microsoft.VisualStudio;
using Microsoft.VisualStudio.SharePoint;
using Microsoft.VisualStudio.Shell.Interop;

namespace CustomSharePointProperty
{
    [Export(typeof(ISharePointProjectExtension))]
    public class ProjectExtensionWithProperty : ISharePointProjectExtension
    {
        public void Initialize(ISharePointProjectService projectService)
        {
            projectService.ProjectPropertiesRequested += projectService_ProjectPropertiesRequested;           
        }

        void projectService_ProjectPropertiesRequested(object sender, SharePointProjectPropertiesRequestedEventArgs e)
        {
            CustomProjectProperties propertiesObject;

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

            e.PropertySources.Add(propertiesObject);
        }
    }

    public class CustomProjectProperties
    {
        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);
                }
            }
        }

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

Informazioni sul codice

Per garantire che ogni volta che si verifica l'evento ProjectPropertiesRequested venga utilizzata la stessa istanza della classe CustomProjectProperties, nell'esempio di codice l'oggetto delle proprietà viene aggiunto alla proprietà Annotations del 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 ai progetti, vedere Associazione di dati personalizzati alle estensioni degli strumenti di SharePoint.

Per conservare le modifiche ai valori delle proprietà, le funzioni di accesso set per le proprietà utilizzano le seguenti API:

CustomUserFileProperty utilizza la proprietà ProjectUserFileData per salvarne il valore nel file delle opzioni utente del progetto.
CustomProjectFileProperty utilizza il metodo IVsBuildPropertyStorage.SetPropertyValue per salvarne il valore nel file di progetto.

Per ulteriori informazioni su come conservare i dati in questi file, 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

In questo esempio sono richiesti riferimenti agli assembly seguenti:

Microsoft.VisualStudio.SharePoint
Microsoft.VisualStudio.Shell
Microsoft.VisualStudio.Shell.Interop
Microsoft.VisualStudio.Shell.Interop.8.0
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.

Vedere anche

Condividi tramite

Procedura: aggiungere una proprietà ai progetti SharePoint

Per aggiungere una proprietà a un progetto SharePoint

Esempio

Informazioni sul codice

Specifica del comportamento delle proprietà personalizzate

Compilazione del codice

Distribuzione dell'estensione

Vedere anche

Attività

Concetti

Altre risorse

Risorse aggiuntive