Exporting Settings

To implement the export of settings

1. Declare the class that implements the Visual Studio settings.

   Declare a class as implementing the IProfileManager interface and provide it with a GUID.

   Note
   Classes that implement IProfileManager must also implement IComponent. This can be done by deriving the class from Component.

   For example:

   Copy

   [Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")]
   internal class MyPackageProfileManager : Component, IProfileManager 
   

2. Ensure that the class that implements the settings obtains correct state information. This procedure is specific to each VSPackage, and may involve obtaining state from automation, querying registry keys, or querying the VSPackage.

   Typically, as in the following example, use the implementation of the LoadSettingsFromStorage method to validate and stage VSPackage state information.

   Note
   The LoadSettingsFromStorage method is also called by the IDE when it initializes the VSPackage that it supports.

   In this case, the implementation of the LoadSettingsFromStorage method does these things:

   • Obtains access to the state information in the VSPackage current configuration and configuration information stored in the registry.

     VB

     Copy

     Dim mySvc As MyPackageService = TryCast(GetService(GetType(IVSMDMyPackage)), MyPackageService) 
     Dim package As Package = TryCast(GetService(GetType(Package)), Package) 
     Dim rootKey As RegistryKey = package.UserRegistryRoot
     

     C#

     Copy

     MyPackageService mySvc = GetService(typeof(IVSMDMyPackage)) as MyPackageService;
     Package package = GetService(typeof(Package)) as Package;
     RegistryKey rootKey = package.UserRegistryRoot;
     

   • Depending on the value returned by the MakeCurrentSettingTheDefault method of the VSPackage, it either updates the registry settings by using the current VSPackage state, or the state by using the registry settings.

     VB

     Copy

     If mySvc.MyPackage.MakeCurrentSettingTheDefault() Then 
         DirectCast(mySvc.MyPackage.packageState, IComPropertyBrowser).SaveState(pbrsKey) 
     Else 
         DirectCast(mySvc.MyPackage.packageState, IComPropertyBrowser).LoadState(pbrsKey) 
     End If
     

     C#

     Copy

     if (mySvc.MyPackage.MakeCurrentSettingTheDefault()){
       ((IComPropertyBrowser)mySvc.MyPackage.packageState).SaveState(pbrsKey);
     }else{
       ((IComPropertyBrowser)mySvc.MyPackage.packageState).LoadState(pbrsKey);
     }
     

     For simplicity in this example, unless the MakeCurrentSettingsTheDefault method returns true, the current state is always reset to the default that is stored in the registry.

3. Ensure that the class that implements the settings also persists the state to disk.

   The actual writing of state information to the settings disk file must always be performed by the class implementation of the SaveSettingsToXml method. The specifics of a settings writer operation depend on the implementation.

   However, the class must obtain access to state information and must use the supplied IVsSettingsWriter interface to save data to the setting file.

   Typically, as in the following example, the implementation of the SaveSettingsToXml method does not validate state information. The validation is performed in the LoadSettingsFromStorage method. Instead, the implementation merely obtains access to the state information and writes it, in this case, as string data.

   C#

   VB

   C++

   Copy

   No code example is currently available or this language may not be supported.

   Implementation details are as follows:

   • In addition to data explicitly written and transparent to the ExportSettings method implementation, the settings API also saves Visual Studio version information. Therefore, saved settings can be compared against the version of the IDE that generated them during settings importation.

   • The value of the pszSettingName argument supplied to a method of the IVsSettingsWriter interface must uniquely identify each data element saved in a settings category.

     Note
     Names must only be unique within the scope of the implementing class. The IDE uses the GUID of the class that implements the settings and the value of pszSettingName to identify each saved setting. If more than one IVsSettingsWriter method that have the same pszSettingName value are called, the original value is overwritten in the settings file.

   • The settings file supports random data access, so the order of read and write operations is not important. In the following example, the order of writer operations in the implementation of the SaveSettingsToXml method is opposite of the read operations in the LoadSettingsFromXml method.

   • If the implementation can map data into one of the four supported formats, then there is no restriction on how much or what type of data can be written.

     Note
     The division of labor between the LoadSettingsFromStorage and SaveSettingsToXml methods depends on the implementation and is somewhat arbitrary. For example, the implementation could be rewritten by using an empty implementation of the LoadSettingsFromStorage method and by having all registry and state queries performed in the SaveSettingsToXml method.

4. Register the settings implementing class as providing support to a VSPackage.

   Apply an instance of ProvideProfileAttribute that is constructed by using the Type of the class that implements IProfileManager to the VSPackage Package implementation.

   VB

   Copy

   <ProvideProfile(GetType(MyPackageProfileManager), "CoreUI", "MyPackage", 1004, 1004, False)> _ 
   <Guid("YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY")> _ 
   Class MyPackage 
       Inherits Package 
   End Class
   

   C#

   Copy

   [ProvideProfile(typeof(MyPackageProfileManager), "CoreUI", "MyPackage", 1004, 1004, false)]
   [Guid("YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY")]
   class MyPackage: Package 
   

   In this case, the attribute informs the IDE that the MyPackageProfileManager class provides a settings implementation to the MyPackage class. The Custom Settings Point in the registry is created under HKLM\Software\Microsoft\VisualStudio\Version\UserSettings\ CoreUI_MyPackage, where Version is the version of Visual Studio, for example, 10.0.

   For more information, see Support for User Settings and ProvideProfileAttribute.

Example