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 to let the user set properties for your application.

Selecting a project node in Solution Explorer and then selecting Properties from the Project menu opens a dialog box that includes project and configuration properties. In Visual C#, Visual J#, 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 (C#) and the Managed Visual Studio Project Sample.

Persistence of Project and Configuration Properties

Project and configuration properties are persisted in a project file that has an extension associated with the project type. Examples of these extensions are: .csproj, .vbproj, and .myproj. Language projects usually 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 the project type that uses this template. Visual C# projects and the Managed Visual Studio Project Sample both use the 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.

Following is the start of a simple 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 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 GetPropertyPageGuids method selects classes derived from SettingsPage for project property grids. The GetConfigPropertyPageGuids(String) 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 ProjectNode class offer these methods to persist project and configuration properties:

• GetProjectProperty(String) and SetProjectProperty(String, String) persist project properties.

• GetConfigProperty(String) and SetConfigProperty(String, String) persist configuration properties.

  Note

  The implementations of the SettingsPage and 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 ApplyChanges and 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 ProvideObjectAttribute to a class derived from Package.

[ProvideObject(typeof(MyProjectPropertyPage))]
[Guid("e815d8ad-49bf-427d-99c8-009db3e56ab9")]
public 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.

Consider the following code fragment:

[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 the in 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

Walkthrough: Exposing Project and Configuration Properties (C#)

How to: Add and Remove Property Pages

Concepts

Template Directory Description (.Vsdir) Files

Other Resources

VSPackage State

Projects (Visual Studio SDK)

Visual Studio Templates