HOW TO：將屬性加入至 SharePoint 專案

發行項
08/12/2011

您可以使用專案擴充功能，將屬性加入至任何 SharePoint 專案。當在 [方案總管] 中選取專案項目時，這個屬性就會出現在 [屬性] 視窗中。

下列步驟假設您已經建立專案擴充功能。如需詳細資訊，請參閱 HOW TO：建立 SharePoint 專案擴充功能。

若要將屬性加入至 SharePoint 專案

定義類別，這個類別具有表示要加入至 SharePoint 專案的公用屬性。如果想要加入多個屬性，您可以在同一類別或不同類別中定義所有屬性。
在您的 ISharePointProjectExtension 實作 Initialize 方法中，處理 projectService 參數的 ProjectPropertiesRequested 事件。
在 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;
                }
            }
        }                
    }
}

了解程式碼

為了確保在每次發生 ProjectPropertiesRequested 事件時都使用 CustomProjectProperties 類別的同一個執行個體，程式碼範例會在第一次發生此事件時，將屬性物件加入至專案的 Annotations 屬性。每當重新發生此事件時，程式碼都會擷取這個物件。如需使用 Annotations 屬性使資料與專案產生關聯的詳細資訊，請參閱讓自訂資料與 SharePoint 工具擴充功能產生關聯。

為了保存屬性值的變更，屬性的 set 存取子會使用下列 API：

CustomUserFileProperty 會使用 ProjectUserFileData 屬性將其值儲存到專案使用者選項檔。
CustomProjectFileProperty 會使用 IVsBuildPropertyStorage.SetPropertyValue 方法將其值儲存到專案檔。

如需在這些檔案中保存資料的詳細資訊，請參閱儲存 SharePoint 專案系統擴充功能的資料。

指定自訂屬性的行為

您可以在 [屬性] 視窗中定義自訂屬性 (Property) 的外觀和行為，方法是將屬性 (Attribute) 從 System.ComponentModel 命名空間套用至屬性 (Property) 定義。下列屬性在許多情節中都十分有用：

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) 套件。如需詳細資訊，請參閱部署 Visual Studio 中 SharePoint 工具的擴充功能。

請參閱

共用方式為