Walkthrough: Creating a Settings Category
In this walkthrough, you can 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 that 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 Working with Settings.
The managed package framework (MPF) supports creation of 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.
Hinweis
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 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.
Prerequisites
To complete this walkthrough, you must install the Visual Studio 2010 SDK.
Hinweis
For more information about the Visual Studio SDK, see Visual Studio Integration SDK. To find out how to download the Visual Studio SDK, see Visual Studio Extensibility Developer Center on the MSDN Web site.
Locations for the Visual Studio Package Project Template
The Visual Studio Package project template can be found in three different locations in the New Project dialog:
Under Visual Basic Extensibility. The default language of the project is Visual Basic.
Under C# Extensibility. The default language of the project is C#.
Under Other Project Types Extensibility. The default language of the project is C++.
Creating a Settings Category
In this section, you create a settings category by using the Visual Studio Package project template. You use a custom settings point to save and restore the values of the settings category.
To create a settings category
Complete the first section of Walkthrough: Creating an Options Page.
Right-click the MyToolsOptions project node and then click Set as Startup Project.
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 that name the category "My Category", the object "My Settings", and the category description "OptionInteger and OptionFloat".
Hinweis
Of these three, only the category name does not appear in the Import and Export Settings wizard.
Open the file MyToolsOptionsPackage.cs or MyToolsOptionsPackage.vb in the MyToolsOptions project and add a float property named OptionFloat to the OptionPageGrid class, as shown in the following example.
Public Class OptionPageGrid Inherits DialogPage Private _optionInt As Integer = 256 Private _optionFloat As Single = 3.14F <Category("My Options")> <Description("My integer option")> Public Property OptionInteger() As Integer Get Return _optionInt End Get Set(ByVal value As Integer) _optionInt = value End Set End Property <Category("My Options")> <Description("My float option")> Public Property OptionFloat() As Single Get Return _optionFloat End Get Set(ByVal value As Single) _optionFloat = value End Set End Property End Classpublic 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; } } }Hinweis
The OptionPageGrid category named "My Category" now consists of the two properties, OptionInteger and OptionFloat.
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(GetType(OptionPageGrid), "My Category", "My Settings", 106, 107, True, DescriptionResourceID:=108)> <Guid(GuidList.guidMyToolsOptionsPkgString)> Public NotInheritable Class MyToolsOptions Inherits Package[ProvideProfileAttribute( typeof(OptionPageGrid), "My Category", "My Settings", 106, 107, true, DescriptionResourceID = 108)] [Guid(GuidList.guidMyToolsOptionsPkgString)] public sealed class MyToolsOptions : PackageBuild 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
Start the project in debug mode by pressing F5.
This starts Visual Studio Exp and writes the arguments of ProvideProfileAttribute to the system registry.
Hinweis
Two versions of Visual Studio are open now.
Close the debug instance of Visual Studio.
Run the Registry Editor and examine the registry entry for HKCU\Software\Microsoft\VisualStudio\10.0Exp_Config\UserSettings\MyCategory_MySettings. The following table shows subkeys of the entry (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".
Correcting the System Registry
In this section, you correct the system registry entries made by ProvideProfileAttribute.
ProvideProfileAttribute is designed to write resource IDs for unmanaged resources to the system registry. The Visual Studio resource loader expects unmanaged resource IDs to have numeric values preceded by "#", and managed resources to have numeric values with no preceding "#". Therefore, you have to delete the "#" for managed resource IDs.
To correct the system registry
Correct the registry entry for HKLM\Software\Microsoft\VisualStudio\8.0Exp\UserSettings\MyCategory_MySettings by deleting "#" from its numeric subkeys. The following table shows subkeys of the entry (your GUIDs will differ).
Name
Data
(Default)
107
Category
{ba1e23e3-fecc-425d-8259-06c40cfac1b6}
Description
108
Package
{a2192704-7d66-44b7-b61b-44ed96aace98}
ToolsOptionsPath
My Category
Right-click the registry entry and export it to the file "settings.reg" in the MyToolsOptions project folder.
Close the Registry Editor.
Right-click the MyToolsOptions project node and add "settings.reg" to the project.
Open VsPkg.cs or VsPkg.vb and comment out ProvideProfileAttribute and its arguments.
'<ProvideProfileAttribute(GetType(OptionPageGrid), "My Category", "My Settings", 106, 107, True, DescriptionResourceID := 108)>//[ProvideProfileAttribute( // typeof(OptionPageGrid), "My Category", "My Settings", // 106, 107, true, DescriptionResourceID = 108)]This prevents the incorrect registry entries from being rewritten to the System Registry.
Right-click the MyToolsOptions project and then click Properties.
Click the Build Events tab and add the following Post-build event command line. You must include the full path of the settings.reg file (your path may differ).
regedit /s D:\MyToolsOptions\MyToolsOptions\settings.regBuild the MyToolsOptions solution. The corrected numeric subkeys will be written to the registry.
Hinweis
You must also make these corrections when you create a registry file for final VSPackage deployment.
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
Start the project in debug mode by pressing F5. This starts Visual Studio Exp.
Hinweis
Two versions of Visual Studio are open now.
In Visual Studio Exp, on the Tools menu, click Options.
The Options dialog box opens.
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.
Change the value of OptionFloat to 3.1416 and OptionInteger to 12. Click OK.
On the Tools menu, click Import and Export Settings.
The Import and Export Settings wizard appears.
Make sure Export selected environment settings is selected, and then click Next.
The Choose Settings to Export page appears.
Click My Settings.
The Description changes to OptionInteger and OptionFloat.
Make sure that My Settings is selected, and then click Next.
The Name Your Settings File page appears.
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.
On the File menu, point to Open, and then click File. Locate MySettings.vssettings and open it.
You can find the property category you exported in the following 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>Notice that the full category name is formed by the addition of an underscore to the category name followed by the object name. OptionFloat and OptionInteger appear in the category, together with their exported values.
Close the settings file without changing it.
On the Tools menu, click Options, expand My Category, click My Grid Page and then change the values of OptionFloat and OptionInteger. Click OK.
On the Tools menu, click Import and Export Settings, select Import selected environment settings, and then click Next.
The Save Current Settings page appears.
Select No, just import new settings and then click Next.
The Choose a Collection of Settings to Import page appears.
Select the MySettings.vssettings file in 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 box appears.
Make sure that My Settings is selected, and then click Finish. When the Import Complete page appears, click Close.
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