Support for Project and Configuration Properties
The Properties window in the Visual Studio integrated development environment (IDE) can display project and configuration properties. You can provide a property page for your own project type so that the user can set properties for your application.
By selecting a project node in Solution Explorer and then clicking Properties on the Project menu, you can open a dialog box that includes project and configuration properties. In Visual C# and Visual Basic, and project types derived from these languages, this dialog box appears as a tabbed page in the General, Environment, Options Dialog Box. For more information, see Walkthrough: Exposing Project and Configuration Properties.
The Managed Package Framework for Projects (MPFProj) provides helper classes for creating and managing new project system. You can find the source code and compilation instructions at MPF for Projects - Visual Studio 2010.
Persistence of Project and Configuration Properties
Project and configuration properties are persisted in a project file that has an file name extension associated with the project type, for example, .csproj, .vbproj, and .myproj. Language projects typically use a template file to generate the project file. However, there are actually several ways to associate project types and templates. For more information, see Visual Studio Templates and Template Directory Description (.Vsdir) Files.
Project and configuration properties are created by adding items to the template file. These properties are then available to any project created by using the project type that uses this template. Visual C# projects and the MPFProj both use the MSBuild schema for template files. These files have a PropertyGroup section for each configuration. Properties of projects are typically persisted in the first PropertyGroup section, which has a Configuration argument set to a null string.
The following code shows the start of a basic MSBuild project file.
<Project MSBuildVersion="2.0" DefaultTargets="Build" xmlns="https://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup>
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
<Name>SomeProjectSix</Name>
<SchemaVersion>2.0</SchemaVersion>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
<Optimize>false</Optimize>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
<Optimize>true</Optimize>
In this project file, <Name> and <SchemaVersion> are project properties, and <Optimize> is a configuration property.
It is the responsibility of the project to persist the project and configuration properties of the project file.
Note
A project can optimize persistence by persisting only property values that differ from their default values.
Support for Project and Configuration Properties
The Microsoft.VisualStudio.Package.SettingsPage class implements project and configuration property pages. The default implementation of SettingsPage offers public properties to a user in a generic property grid. The Microsoft.VisualStudio.Package.HierarchyNode.GetPropertyPageGuids method selects classes derived from SettingsPage for project property grids. The Microsoft.VisualStudio.Package.ProjectNode.GetConfigPropertyPageGuids method selects classes derived from SettingsPage for configuration property grids. Your project type should override these methods to select the appropriate property pages.
The SettingsPage class and the Microsoft.VisualStudio.Package.ProjectNode class offer these methods to persist project and configuration properties:
Microsoft.VisualStudio.Package.ProjectNode.GetProjectProperty and Microsoft.VisualStudio.Package.ProjectNode.SetProjectProperty persist project properties.
Microsoft.VisualStudio.Package.SettingsPage.GetConfigProperty and Microsoft.VisualStudio.Package.SettingsPage.SetConfigProperty persist configuration properties.
Note
The implementations of the Microsoft.VisualStudio.Package.SettingsPage and Microsoft.VisualStudio.Package.ProjectNode classes use the Microsoft.Build.BuildEngine (MSBuild) methods to get and set project and configuration properties from the project file.
The class you derive from SettingsPage must implement Microsoft.VisualStudio.Package.SettingsPage.ApplyChanges and Microsoft.VisualStudio.Package.SettingsPage.BindProperties to persist project or configuration properties of the project file.
ProvideObjectAttribute and Registry Path
Classes derived from SettingsPage are designed to be shared across VSPackages. To make it possible for a VSPackage to create a class derived from SettingsPage, add a Microsoft.VisualStudio.Shell.ProvideObjectAttribute to a class derived from Microsoft.VisualStudio.Shell.Package.
<ProvideObject(GetType(MyProjectPropertyPage))> _
<Guid("e815d8ad-49bf-427d-99c8-009db3e56ab9")> _
Public Class MyPackage
Inherits Package
[ProvideObject(typeof(MyProjectPropertyPage))]
[Guid("e815d8ad-49bf-427d-99c8-009db3e56ab9")]
public sealed class MyPackage : Package
The VSPackage to which the attribute is attached is unimportant. When a VSPackage is registered with Visual Studio, the class id (CLSID) of any object that can be created is registered so that a call to CreateInstance can create it.
The registry path of an object that can be created is determined by combining UserRegistryRoot, the word, CLSID, and the guid of the object type. If MyProjectPropertyPage class has a guid of {3c693da2-5bca-49b3-bd95-ffe0a39dd723} and the UserRegistryRoot is HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\8.0Exp, then the registry path would be HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\8.0Exp\CLSID\{3c693da2-5bca-49b3-bd95-ffe0a39dd723}.
Project and Configuration Property Attributes and Layout
The CategoryAttribute, DisplayNameAttribute, and DescriptionAttribute attributes determine the layout, labeling, and description of project and configuration properties in a generic property page. These attributes determine the category, display name, and description of the option, respectively.
Note
Equivalent attributes, SRCategory, LocDisplayName, and SRDescription, use string resources for localization and are defined in MPF for Projects - Visual Studio 2010.
Consider the following code fragment:
Private _myConfigProp As String
Private _isDirty As Boolean
Public Property IsDirty As Boolean
Get
Return _isDirty
End Get
Set(ByVal value As Boolean)
_isDirty = value
End Set
End Property
<Category("My Category")> _
<DisplayName("My Config Property")> _
<Description("My Description")> _
Public Property MyConfigProp() As String
Get
Return _myConfigProp
End Get
Set(ByVal value As String)
_myConfigProp = value
IsDirty = True
End Set
End Property
public bool IsDirty { get; set; }
private string myConfigProp;
[Category("My Category")]
[DisplayName("My Config Property")]
[Description("My Description")]
public string MyConfigProp
{
get { return myConfigProp; }
set { myConfigProp = value; IsDirty = true; }
}
The MyConfigProp configuration property appears on the configuration property page as My Config Property in the category, My Category. If the option is selected, the description, My Description, appears in the description panel.
See Also
Tasks
How to: Add and Remove Property Pages
Concepts
Template Directory Description (.Vsdir) Files