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 Not in Build: Walkthrough: Exposing Project and Configuration Properties (C#).

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 2013.

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 NIB: 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 Not in Build: MSBuild Overview 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.

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(typeof(MyProjectPropertyPage))]
[Guid("e815d8ad-49bf-427d-99c8-009db3e56ab9")]
public sealed class MyPackage : Package

<ProvideObject(GetType(MyProjectPropertyPage))> _ 
<Guid("e815d8ad-49bf-427d-99c8-009db3e56ab9")> _
Public Class MyPackage
    Inherits 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.

Consider the following code fragment:

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; }
}

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

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

Not in Build: Walkthrough: Exposing Project and Configuration Properties (C#)
Adding and Removing Property Pages
VSPackage State
Projects
NIB: Visual Studio Templates
Template Directory Description (.Vsdir) Files