We recommend using Visual Studio 2017

Support for Project and Configuration Properties

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at 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.

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="http://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.

System_CAPS_ICON_note.jpg Note

A project can optimize persistence by persisting only property values that differ from their default values.

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.

    System_CAPS_ICON_note.jpg 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.

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

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

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.

System_CAPS_ICON_note.jpg Note

Equivalent attributes, SRCategory, LocDisplayName, and SRDescription, use string resources for localization and are defined in MPF for Projects - Visual Studio 2013.

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

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.

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

Show: