Comment : ajouter une propriété à des projets SharePoint

Article
02/19/2013

Vous pouvez utiliser une extension de projet pour ajouter une propriété à tout projet SharePoint.La propriété s'affiche dans la fenêtre Propriétés lorsque le projet est sélectionné dans l'Explorateur de solutions.

Les étapes suivantes supposent que vous avez déjà créé une extension de projet.Pour plus d'informations, consultez Comment : créer une extension de projet SharePoint.

Pour ajouter une propriété à un projet SharePoint

Définissez une classe avec une propriété publique représentant la propriété que vous ajoutez à des projets SharePoint.Pour ajouter plusieurs propriétés, vous pouvez définir toutes les propriétés dans la même classe ou dans des classes différentes.
Dans la méthode Initialize de votre implémentation ISharePointProjectExtension, gérez l'événement ProjectPropertiesRequested du paramètre projectService.
Dans le gestionnaire d'événements de l'événement ProjectPropertiesRequested, ajoutez une instance de votre classe de propriétés à la collection PropertySources du paramètre d'arguments d'événement.

Exemple

L'exemple de code suivant montre comment ajouter deux propriétés à des projets SharePoint.Une propriété rend ses données persistantes dans le fichier d'options utilisateur du projet (fichier .csproj.user ou .vbproj.user).L'autre propriété rend ses données persistantes dans le fichier projet (fichier .csproj ou .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;
                }
            }
        }                
    }
}

Fonctionnement du code

Pour garantir que la même instance de la classe CustomProjectProperties est utilisée chaque fois que l'événement ProjectPropertiesRequested a lieu, l'exemple de code ajoute l'objet de propriétés dans la propriété Annotations du projet la première fois que cet événement se produit.Le code extrait cet objet chaque fois que cet événement se produit à nouveau.Pour plus d'informations sur l'utilisation de la propriété Annotations afin d'associer les données aux projets, consultez Association de données personnalisées à des extensions d'outils SharePoint.

Pour rendre persistantes les modifications apportées aux valeurs de propriété, les accesseurs set des propriétés utilisent les API suivantes :

CustomUserFileProperty utilise la propriété ProjectUserFileData pour sauvegarder sa valeur dans le fichier d'options utilisateur du projet.
CustomProjectFileProperty utilise la méthode IVsBuildPropertyStorage.SetPropertyValue pour sauvegarder sa valeur dans le fichier projet.

Pour plus d'informations sur la manière de rendre des données de ces fichiers persistantes, consultez Enregistrement des données dans les extensions du système de projet SharePoint.

Spécification du comportement des propriétés personnalisées

Vous pouvez définir la manière dont une propriété personnalisée apparaît et se comporte dans la fenêtre Propriétés en appliquant des attributs de l'espace de noms System.ComponentModel à la définition de la propriété.Les attributs suivants sont utiles dans de nombreux scénarios :

DisplayNameAttribute : spécifie le nom de la propriété qui s'affiche dans la fenêtre Propriétés.
DescriptionAttribute : spécifie la chaîne de description qui s'affiche en bas de la fenêtre Propriétés lorsque la propriété est sélectionnée.
DefaultValueAttribute : spécifie la valeur par défaut de la propriété.
TypeConverterAttribute : spécifie une conversion personnalisée entre la chaîne affichée dans la fenêtre Propriétés et une valeur de propriété non-chaîne.
EditorAttribute : spécifie un éditeur personnalisé à utiliser pour modifier la propriété.

Compilation du code

Cet exemple nécessite des références aux assemblys suivants :

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

Déploiement de l'extension

Pour déployer l'extension, créez un package d'extension Visual Studio (VSIX) pour l'assembly et tous les autres fichiers que vous voulez distribuer avec l'extension.Pour plus d'informations, consultez Déploiement d'extensions pour les outils SharePoint dans Visual Studio.