VSIP: Creating a Profile Settings Category


In this walkthrough, you create a profile settings category and use it to save and restore values to and from a settings file. A category is simply a group of related properties which show up as a "custom settings point", that is, as a checkbox in the Tools/Import and Export Settings dialog. Properties are saved or restored as a group, and individual property names are not displayed in the dialog.

The managed package framework (MPF) supports creating settings categories with very little additional code. You create a VSPackage to provide a container for the category by subclassing the Microsoft.VisualStudio.Shell.Package class. You create the category itself by deriving it from the Microsoft.VisualStudio.Shell.DialogPage class.

Note   Although DialogPage can provide a property grid or custom user interface, neither is used by the profile settings manager.

To begin this walkthrough you must first complete the first section of the walkthrough Creating a Tools/Options Page. The resulting Tools/Options property grid lets you examine and alter the properties in the category. After you save the property category in a settings file, you examine the file to see how the property values are stored.

  • Creating a New Settings Category.
  • Examining the Settings File.

   Creating a New Settings Category

In this section, you create a profile settings category using the Visual Studio Integration Package wizard. You use the custom settings point to save and restore the values of the property category.

 

To create a new settings category

1.      Complete the first section of the walkthrough Creating a Tools/Options Page.

2.      Open the file MyToolsOptionsUI/Resource.h and add these three string resource IDs:

#define IDS_MINVSEDITION   105

#define IDS_CATEGORYNAME   106

#define IDS_OBJECTNAME   107

#define IDS_DESCRIPTION   108

3.      Open the file MyToolsOptionsUI/MyToolsOptionsUI.rc with NotePad or a source code editor, and add these three string resources to the STRINGTABLE section:

IDS_MINVSEDITION        "Standard"

IDS_CATEGORYNAME   "General"

IDS_OBJECTNAME   "My Settings"

IDS_DESCRIPTION   "OptionInteger and OptionFloat"

Together, the two previous steps create resources which name the category "General", the object "My Settings", and the category description "OptionInteger and OptionFloat".

Note   Of these three, only the category name does not appear in the Import and Export Settings dialog.

4.      Open the file MyToolsOptions/VsPkg.cs and add a float property named OptionFloat to the OptionPageGrid class. The code should look something like this:

public class OptionPageGrid : MSVSIP.DialogPage

{

   private int _optionInt = 256;

   private float _optionFloat = 3.14F;

 

   [Category("My Options")]

   [Description("My integer option")]

   public int OptionInteger

   {

      get { return _optionInt; }

      set { _optionInt = value; }

   }

   [Category("My Options")]

   [Description("My float option")]

   public float OptionFloat

   {

      get { return _optionFloat; }

      set { _optionFloat = value; }

   }

}

Note   The OptionPageGrid category named "General" now consists of the two properties OptionInteger and OptionFloat.

5.      Add a Microsoft.VisualStudio.Shell.ProvideProfileAttribute to the MyToolsOptions class, giving it the CategoryName "General", the ObjectName "MySettings", and setting IsToolsOptionPage to true. Set the categoryResourceID, objectNameResourceID, and DescriptionResourceID to the corresponding string resource IDs created earlier:

[MSVSIP.ProvideProfileAttribute(
   typeof(OptionPageGrid), "My Settings", "General",

   106, 107, true, DescriptionResourceID = 108)]

[Guid("b3125df0-8db0-408f-8a3f-25e7aac2a2c0")]

public sealed class MyToolsPackage : MSVSIP.Package

6.      Build the project and verify that it compiles without errors.

 

   Examining the Settings File

In this section, you export property category values to a settings file. You examine the file and then import the values back into the property category.

 

To examine the settings file

7.      Launch the project in debug mode by pressing the keyboard shortcut, F5. This launches Visual Studio Exp.

Note   Both versions of Visual Studio are open at this time.

8.      From Visual Studio Exp, select the Tools/Options menu item.
The Options dialog opens.

9.      In the tree view in the left pane, select My Category/My Grid Page.
The options grid appears in the right pane. The property category is "My Options", and the property names are OptionFloat and OptionInteger.

10.  Change the value of OptionFloat to 3.1416 and OptionInteger to 12. Click OK.

11.  Select the Tools/Import and Export Settings menu item.

The Import and Export Settings Wizard appears.

12.  Make sure Export selected environment settings is selected, then click Next.

The Choose Settings to Export dialog appears.

13.  Click on My Settings. The Description changes to "OptionInteger and OptionFloat".

14.  Make sure the My Settings checkbox is checked, then click Next.

The Name Your Settings File dialog appears.

15.  Name the new settings file MySettings.vssettings and save it in an appropriate directory. Click Finish.

The Export Complete dialog reports that your settings were successfully exported.

16.  From the File/Open/File menu item, navigate to your settings file and right-click on the file name.  Select Open With… and open the file with an XML editor.

Note    You may see a warning like "You are attempting to open a file of type 'Visual Studio Settings File' …". Ignore this warning. If you see a warning like "Windows cannot open this file…", click Select the program from a list. When the list appears, select the XML editor. If all else fails, open the settings file in NotePad.

17.  You can find the property category you exported in this section of the file:

<Category name="General_My Settings"

      Category="{4802bc3e-3d9d-4591-8201-23d1a05216a6}"

      Package="{6bb6942e-014c-489e-a612-a935680f703d}"       RegisteredName="General_My Settings">

   <PropertyValue name="OptionFloat">3.1416</PropertyValue>

   <PropertyValue name="OptionInteger">12</PropertyValue>

</Category>

Note that the full category name is formed by appending the category name and the object name with an underscore. OptionFloat and OptionInteger appear in the category, along with their exported values.

18.  Close the settings file without making any changes to it.

19.  Select Tools/Options/My Category/My Grid Page again and change OptionFloat and OptionInteger to some other value. Click OK.

20.  Select Tools/Import and Export Settings and choose Import selected environment settings. Click Next.

The Save Current Settings dialog appears.

21.  Choose No, just import new settings.  Click Next.

The Choose a Collection of Settings to Import dialog appears.

22.  Select the MySettings.vssettings file from the tree view. If the file doesn't appear in the tree view, click the Browse button and navigate to it. Click Next.

The Choose Settings to Import dialog appears.

23.  Make sure the My Settings checkbox is checked. Click Finish and wait for the Import Complete dialog to appear.  Click Close.

24.  Select Tools/Options/My Category/My Grid Page once more and verify that the property category values have been restored.

Enjoy, Martin Tracy, Programmer Writer

Important note: This material is provided in an 'as is' condition so that you might evaluate it for your own use at your own risk. You agree that by providing comments, suggestions, or other feedback related to our products, technology or services to the individuals listed above, you allow Microsoft, at its option, to use your feedback in our products, technology, and services without any obligation to you. Due to the volume of e-mails we receive, Microsoft, including the individual listed above, may not be able respond to your e-mail.


Skip to main content