Share via

Walkthrough: Creating a Settings Category (C#)

  • Article

In this walkthrough, you create a Visual Studio settings category and use it to save values to and restore values from a settings file. A category is a group of related properties which appear as a "custom settings point", that is, as a check box in the Import and Export Settings Wizard. To start the wizard, on the Tools menu, click Import and Exports Settings. Settings are saved or restored as a category, and individual settings are not displayed in the wizard. For more information, see Visual Studio Settings.

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 Package class. You create the category itself by deriving it from the DialogPage class.

Note

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

To start this walkthrough you must first complete the first section of Walkthrough: Creating an Options Page. The resulting Tools Options property grid lets you examine and change 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

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

To create a new settings category

  1. Complete the first section of Walkthrough: Creating an Options Page.

  2. Right-click the MyToolsOptions project node and select Set as Startup Project.

  3. Open the VSPackage.resx file and add these three string resources:

    Name

    Value

    106

    My Category.

    107

    My Settings

    108

    OptionInteger and OptionFloat

    This creates resources which name the category "My Category", 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 wizard.

  4. Open the file VsPkg.cs in the MyToolsOptions project and add a float property named OptionFloat to the OptionPageGrid class. Following is an example:

    public class OptionPageGrid : 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 "My Category" now consists of the two properties, OptionInteger and OptionFloat.

  5. Add a ProvideProfileAttribute to the MyToolsOptions class and give it the CategoryName "My Category", give it the ObjectName "My Settings", and set IsToolsOptionPage to true. Set the categoryResourceID, objectNameResourceID, and DescriptionResourceID to the corresponding string resource IDs created earlier:

     
[ProvideProfileAttribute( 
   typeof(OptionPageGrid), "My Category", "My Settings", 
   106, 107, true, DescriptionResourceID = 108)]
[Guid(GuidList.guidMyToolsOptionsPkgString)]
public sealed class MyToolsOptions : Package

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

Examining the System Registry

In this section, you examine the system registry entries made by ProvideProfileAttribute.

To examine the system registry

  1. Start the project in debug mode by pressing the keyboard shortcut, F5.

    This starts Visual Studio Exp and writes the arguments of ProvideProfileAttribute to the system registry.

    Note

    Both versions of Visual Studio are open now.

  2. Exit Visual Studio Exp.

  3. Run the Registry Editor and examine the registry entry for HKLM\Software\Microsoft\VisualStudio\8.0Exp\UserSettings\MyCategory_MySettings. The following table includes subkeys of the entry although your GUIDs will differ:

    Name

    Data

    (Default)

    107

    Category

    {ba1e23e3-fecc-425d-8259-06c40cfac1b6}

    Description

    108

    Package

    {a2192704-7d66-44b7-b61b-44ed96aace98}

    The default subkey value "107" refers to the string resource "My Settings". The Description subkey value "108" refers to the string resource "OptionInteger and OptionFloat".

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

  1. 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 now.

  2. In Visual Studio Exp, on the Tools menu click Options.

    The Options dialog box opens.

  3. In the tree view in the left pane, expand My Category and then click 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.

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

  5. On the Tools menu, click Import and Export Settings.

    The Import and Export Settings wizard appears.

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

    The Choose Settings to Export page appears.

  7. Click My Settings.

    The Description changes to "OptionInteger and OptionFloat".

  8. Make sure that the My Settings check box is checked, and then click Next.

    The Name Your Settings File page appears.

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

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

  10. On the File menu, point to Open, and then click File. Navigate to and open the MySettings.vssettings file.

    You can find the property category you exported in this section of the file (your GUIDs will differ):

    <Category name="My Category_My Settings" 
      Category="{4802bc3e-3d9d-4591-8201-23d1a05216a6}" 
      Package="{6bb6942e-014c-489e-a612-a935680f703d}" 
      RegisteredName="My Category_My Settings">
      PackageName="Company.MyToolsOptions.MyToolsOptions,          MyToolsOptions, Version=1.0.2251.20398, Culture=neutral,          PublicKeyToken=d74639816260e962">
   <PropertyValue name="OptionFloat">3.1416</PropertyValue> 
   <PropertyValue name="OptionInteger">12</PropertyValue> 
</Category>

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

  11. Close the settings file without changing it.

  12. On the Tools menu, click Options, expand My Category, click My Grid Page and then change OptionFloat and OptionInteger to another value. Click OK.

  13. On the Tools menu, click Import and Export Settings, choose Import selected environment settings, and then click Next.

    The Save Current Settings page appears.

  14. Choose No, just import new settings and then click Next.

    The Choose a Collection of Settings to Import page appears.

  15. Select the MySettings.vssettings file from the My Settings node of the tree view. If the file does not appear in the tree view, click Browse and find it. Click Next.

    The Choose Settings to Import dialog appears.

  16. Make sure that the My Settings check box is checked, click Finish, wait for the Import Complete page to appear, and then click Close.

  17. On the Tools menu, click Options, expand My Category, click My Grid Page and verify that the property category values have been restored.

See Also

Concepts

Support for Settings Categories

Other Resources

VSPackage State