Walkthrough: Exposing Project and Configuration Properties (C#)

  • Article

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

This walkthrough creates project and configuration properties and accesses them through the <Project Name> Property Pages dialog box. You add new properties to the project template file. You then modify the managed project sample to display the properties in the <Project Name> Property Pages dialog box. You set the property category, display name, and description by creating appropriate string resources.

Exposing a Project Property

In this section, you modify the managed project sample and add a project property to it. You display and change the property from the <Project Name> Property Pages dialog box. You then examine the project file to see the new property value

To expose a project property to the Project Property dialog box

  1. Follow this link to find the managed project sample SimpleProject.

  2. Copy the sample to your local machine.

  3. Open the template file, Project\Templates\Projects\Application.myproj, in Notepad or some other editor.

  4. Insert the following line at the end of the first PropertyGroup:

                                   <AssemblyName>Application</AssemblyName>
   <MyString>Hello</MyString>
</PropertyGroup>

    This creates the new project property, MyString.

  5. Save the file and exit the editor.

    New projects of type MyProject have a project file that is generated from this template.

  6. Start Visual Studio and then open the solution Project\MyProject.sln.

  7. In Solution Explorer, double-click PropertyPages.cs to open it.

  8. Add a field to the fields at the beginning of the GeneralPropertyPage class to hold the new MyString project property:

    private string targetPlatformLocation;
private string myString;

  9. Add code to the end of the BindProperties method to read the new property from the project file:

    this.targetPlatformLocation = this.ProjectMgr.GetProjectProperty(
   "TargetPlatformLocation", false);
this.myString = this.ProjectMgr.GetProjectProperty(
   "MyString", false);

  10. Add code to the ApplyChanges method to write the new property to the project file:

    this.ProjectMgr.SetProjectProperty(
   "TargetPlatformLocation", this.targetPlatformLocation);
this.ProjectMgr.SetProjectProperty("MyString", this.myString);

  11. Add a MyString property to the end of the GeneralPropertyPage class to expose the new project property. Give it the category "MyCategory", the display name "My New Property", and the description "This is my new string property.":

    public string TargetPlatformLocation
{
   get { return this.targetPlatformLocation; }
   set { this.targetPlatformLocation = value; IsDirty = true; }
}
[Category("MyCategory")]
[DisplayName("My New Property")]
[Description("This is my new string property.")]
public string MyString
{
   get { return myString; }
   set { myString = value;  IsDirty = true; }
}

  12. Build and start the project in debug mode by pressing the keyboard shortcut, F5. This starts Visual Studio Exp.

    Note

    Both versions of Visual Studio are open at this point.

  13. In Visual Studio Exp, on the File menu, point to New, and then click Project. Create a new MyProject Application named SomeProject.

    The SomeProject solution and project are created and appear in Solution Explorer.

  14. In Solution Explorer, right-click the SomeProject project and then click Properties.

    The SomeProject Property Pages dialog box appears. The My New Property property appears in the MyCategory category and has the initial value "Hello".

  15. Change the value of My New Property, close the dialog box, and reopen it.

    The new value persists.

  16. Exit Visual Studio Exp and save changes to the SomeProject solution.

  17. On the File menu, point to Open, and then click File to open the file, SomeProject.myproj, in the SomeProject project folder.

    The location of the SomeProject project folder is determined by Tools/Options/Projects and Solutions/Visual Studio projects location.

  18. Verify that the MyString property has the latest value that you set in the SomeProject Property Pages dialog box.

Using String Resources for Property Attributes

In this section, you use string resources for the MyString property attributes. Using string resources instead of string literals is one of the steps to localize an application.

To use a string resource for a property attribute

  • Open the file, Resources.resx and add three string resources:

  • MyStringCategory
    Your Category

  • MyStringDisplayName
    Your New Property

  • MyStringDescription
    Your new string property

  1. Close the Resources.resx file and reopen it in the XML editor.

  2. Change the first line to read:

    <?xml version="1.0" encoding="utf-16"?>

    The resource editor incorrectly wrote utf-8. This is a known issue.

  3. Open the file, Resources.cs, and add three const strings to the SR class to map the new property attributes to resource names:

    internal const string TargetPlatformLocationDescription =    "TargetPlatformLocationDescription";
internal const string MyStringCategory = "MyStringCategory";
internal const string MyStringDisplayName = "MyStringDisplayName";
internal const string MyStringDescription = "MyStringDescription";

    This mapping helps find string resource naming errors at compile time. For more information, see const (C# Reference).

  4. Open the PropertyPages.cs file and change the MyString property attributes to their localizable equivalents:

     
[SRCategory(SR.MyStringCategory)]
[LocDisplayName(SR.MyStringDisplayName)]
[SRDescription(SR.MyStringDescription)]
public string MyString

  5. Build and start the project in debug mode by pressing the keyboard shortcut, F5. This starts Visual Studio Exp.

  6. In Visual Studio Exp, on the File menu, point to New, and then click Project. Create a new MyProject Application named SomeProject2.

    The SomeProject2 solution and project are created and appear in Solution Explorer.

  7. In Solution Explorer, right-click the SomeProject2 project and then click Properties.

    The SomeProject2 Property Pages dialog box appears. The Your New Property property appears in the YourCategory category and has the initial value "Hello".

Exposing a Configuration Property

In this section, you modify the managed project sample and add a configuration property to it. You display and change the property in both the Debug and Release configurations.

To expose a configuration property to the <Project Name> Property Pages dialog box

  1. Exit Visual Studio Exp.

  2. Reopen the template file, Application.myproj.

  3. Insert the following line at the end of the second PropertyGroup:

                                   <IncrementalBuild>false</IncrementalBuild>
   <MyConfigProp>Debugging</MyConfigProp>
</PropertyGroup>

  4. Insert the following line at the end of the third PropertyGroup:

                                   <IncrementalBuild>false</IncrementalBuild>
   <MyConfigProp>Releasing</MyConfigProp>
</PropertyGroup>

    This creates the new configuration property, MyConfigProp.

  5. Save and close the file.

    New projects of type, MyProject, have a project file generated from this template.

  6. In Visual Studio, open the PropertyPages.cs file, copy the class GeneralPropertyPage (and its attribute) to the same file, and rename it GeneralConfigPage. Give it a new GUID. The resulting class should start with code that resembles the following example (your GUID will differ):

    [ComVisible(true), Guid("14F7BDB1-32BC-4602-9335-B9158FFC89AD")]
   public class GeneralConfigPage : SettingsPage

  7. Replace the body of the GeneralConfigPage class by using the following code:

    [ComVisible(true), Guid("14F7BDB1-32BC-4602-9335-B9158FFC89AD")]
public class GeneralConfigPage : SettingsPage
{
   private string incrementalBuild;
   private string myConfigProp;

   public GeneralConfigPage()
   {
      this.Name = SR.GetString(SR.GeneralCaption);
   }

   public override string GetClassName()
   {
      return this.GetType().FullName;
   }

   protected override void BindProperties()
   {
      incrementalBuild = GetConfigProperty("IncrementalBuild");
      myConfigProp = GetConfigProperty("MyConfigProp");
   }

   protected override int ApplyChanges()
   {
      SetConfigProperty("IncrementalBuild", incrementalBuild);
      SetConfigProperty("MyConfigProp", myConfigProp);
      
      this.IsDirty = false;
      return VSConstants.S_OK;

   }

   [DisplayName("Incremental Build")]
   public string IncrementalBuild
   {
      get { return incrementalBuild; }
   }

   [Category("My Category")]
   [DisplayName("My Config Property")]
   public string MyConfigProp
   {
      get { return myConfigProp; }
      set { myConfigProp = value; IsDirty = true; }
   }
}

    This exposes the two configuration properties, IncrementalBuild and MyConfigProp. IncrementalBuild is exposed as a read-only property, and MyConfigProp is given the category "My Category".

    Note

    You can use string resources for the DisplayName and Category attributes by using the techniques presented in the previous section.

  8. Open the MyProject.cs file and add the following attribute to the MyPackage class:

    [ProvideObject(typeof(GeneralPropertyPage))]
[ProvideObject(typeof(GeneralConfigPage))]

Note

There are two classes defined in this file: MyPackage and MyProject.

  1. Replace the body of the MyProject.GetConfigurationDependentPropertyPages method by using the following code:

    public override Guid[] GetConfigurationDependentPropertyPages()
{
   if (this.SupportsProjectDesigner)
   {
      return this.GetConfigurationIndependentPropertyPages();
   }

   Guid[] result = new Guid[1];
   result[0] = typeof(GeneralConfigPage).GUID;
   return result;
}

  2. Build and start the project in debug mode by pressing the keyboard shortcut, F5. This starts Visual Studio Exp.

    Note

    Both versions of Visual Studio are open at this point.

  3. In Visual Studio Exp, on the File menu, point to New, and then click Project. Create a new MyProject Application named SomeOtherProject.

    The SomeOtherProject solution and project are created and appear in Solution Explorer.

  4. In Solution Explorer right-click the SomeOtherProject project and then click Properties.

    The SomeOtherProject Property Pages dialog box appears.

  5. Click Configuration Properties.

    The Incremental Build read-only property appears in the Misc category. My Config Property property appears in the My Category category and has the value "Debugging".

  6. Change the value of My Config Property, close the dialog box, and reopen it. The new value persists.

  7. Click the Configuration drop-down list arrow and then click Release.

    My Config Property changes to "Releasing".

  8. Change the value of My Config Property, close the dialog box, and reopen it. The new value persists.

  9. Click the Configuration drop-down list arrow and then click Release.

    My Config Property changes to "Releasing".

See Also

Concepts

Support for Project and Configuration Properties

Other Resources

VSPackage State