方法: SharePoint プロジェクトにプロパティを追加する

2011-08-09

プロジェクトの拡張機能を使用して任意の SharePoint プロジェクトにプロパティを追加できます。プロパティは、ソリューションエクスプローラーでプロジェクトを選択したときに [プロパティ] ウィンドウに表示されます。

次の手順は、プロジェクトの拡張機能が既に作成されていることを前提としています。詳細については、「方法: SharePoint プロジェクトの拡張機能を作成する」を参照してください。

SharePoint プロジェクトにプロパティを追加するには

SharePoint プロジェクトに追加するプロパティを表すパブリックプロパティを使用して、クラスを定義します。複数のプロパティを追加する場合は、すべてのプロパティを同じクラスで定義することも、異なるクラスで定義することもできます。
ISharePointProjectExtension 実装の Initialize メソッドで、projectService パラメーターの ProjectPropertiesRequested イベントを処理します。
ProjectPropertiesRequested イベントのイベントハンドラーで、プロパティクラスのインスタンスをイベント引数パラメーターの PropertySources コレクションに追加します。

例

2 つのプロパティを 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;
                }
            }
        }                
    }
}

コードについて

ProjectPropertiesRequested イベントが発生するたびに CustomProjectProperties クラスの同じインスタンスが使用されるように、このイベントが初めて発生したときにプロジェクトの 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 Extension (VSIX) パッケージを作成します。詳細については、「Visual Studio での SharePoint ツールの拡張機能の配置」を参照してください。