Практическое руководство. Добавление свойства в проекты SharePoint

Статья
02/20/2013

С помощью расширения проекта можно добавить свойство в любой проект SharePoint.Свойство отображается в окне Свойства при выборе проекта в обозревателе решений.

В описании следующих действий предполагается, что расширение проекта уже создано.Дополнительные сведения см. в разделе Практическое руководство. Создание расширения проекта SharePoint.

Добавление свойства в проект SharePoint

Определите класс с общедоступным свойством, представляющим свойство, добавляемое в проекты SharePoint.Если требуется добавить несколько свойств в проект, можно определить все свойства в одном классе или задать их в разных классах.
В методе Initialize реализации ISharePointProjectExtension обработайте событие ProjectPropertiesRequested параметра projectService.
В обработчике событий для события ProjectPropertiesRequested добавьте экземпляр класса свойств в коллекцию PropertySources параметра аргументов события.

Пример

В следующем примере кода демонстрируется добавление двух свойств в проекты SharePoint.Для одного из них данные сохраняются в файле пользовательских параметров проекта (с расширением CSPROJ.USER или VBPROJ.USER).Для другого свойства данные сохраняются в файле проекта (с расширением CSPROJ или 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;
                }
            }
        }                
    }
}

Общие сведения о коде

Чтобы обеспечить использование одного и того же экземпляра класса CustomProjectProperties при каждом возникновении события ProjectPropertiesRequested, пример кода добавляет объект свойств в свойство Annotations проекта, когда это событие происходит впервые.Когда событие происходит снова, код извлекает этот объект.Дополнительные сведения об использовании свойства Annotations для связывания данных с проектами см. в разделе Связь пользовательских данных с расширениями средств SharePoint.

Чтобы сохранить изменения значений свойств, методы доступа set для этих свойств используют следующие API:

Свойство CustomUserFileProperty использует свойство ProjectUserFileData для сохранения своего значения в файл пользовательских параметров проекта.
Свойство CustomProjectFileProperty использует метод IVsBuildPropertyStorage.SetPropertyValue для сохранения своего значения в файл проекта.

Дополнительные сведения о сохранении данных в этих файлах см. в разделе Сохранение данных в расширениях системы проектов SharePoint.

Определение поведения настраиваемых свойств

Отображение и поведение настраиваемого свойства можно определить в окне Свойства, применив к определению этого свойства атрибуты из пространства имен System.ComponentModel.Во многих сценариях удобно использовать перечисленные ниже атрибуты.

DisplayNameAttribute — задает имя свойства, которое отображается в окне Свойства.
DescriptionAttribute — задает строку описания, которая отображается в нижней части окна Свойства при выборе данного свойства.
DefaultValueAttribute — задает значение свойства по умолчанию.
TypeConverterAttribute — задает настраиваемое преобразование между строкой, отображаемой в окне Свойства, и нестроковым значением свойства.
EditorAttribute — задает пользовательский редактор, который необходимо использовать для изменения свойства.

Компиляция кода

Для этого примера требуются ссылки на следующие сборки:

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

Развертывание расширения

Чтобы развернуть расширение, создайте пакет расширения Visual Studio (VSIX) для сборки и всех остальных файлов, которые предположительно будут распространяться с расширением.Дополнительные сведения см. в разделе Разработка расширений для средств SharePoint в Visual Studio.