How to: Import Settings By Using the Managed Package Framework

  • Article

The Visual Studio integrated development environment (IDE) uses the classes that implement the IProfileManager interface and are registered to support a VSPackage implementation. This implementation is used to retrieve a VSPackage's state.

Because the IDE instantiates the class implementing the IProfileManager interface to support the Visual Studio settings, the IProfileManager interface should be implemented in an independent class.

Note

Do not implement IProfileManager on the class implementing Package.

To implement Settings Export

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

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

    Note

    Classes implementing the IProfileManager interface must also implement the IComponent interface, which can be done by deriving the class from the Component class.

    For example:

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

  2. Ensure that the class that implements the settings retrieves state data from disk.

    This step is performed by implementing the LoadSettingsFromXml method.

    The exact information that is to be persisted and how that information will be obtained and marshaled from the VSPackage differs for each VSPackage.

    Regardless of the information that is to be persisted by the VSPackage, the class implementing IProfileManager must use the supplied IVsSettingsReader interface to retrieve data from the settings file.

    Typically, as in the example below, LoadSettingsFromXml also validates the retrieved data and updates the VSPackage's state.

    MyPackageService mySvc = GetService(typeof(IVSMDMyPackage)) as MyPackageService;
if (mySvc != null){
  string value;
  StateObject myState = mySvc.MyPackage.packageState;
  reader.ReadSettingString("PbrsShowDesc", out value);
  if (value == null || value == ""){
      reader.ReportError("Unable to Help Visibility Setting");
  }else{
      myState.HelpVisible = !value.Equals("0");
  }
  reader.ReadSettingString("PbrsAlpha", out value);
  if (value == null || value == ""){
      reader.ReportError("Unable to Retrieve Sort Value");
  }else{
    if (!value.Equals("0")){
      myState.SortState = SortState.Alphabetical;
    }else{
      myState.SortState = SortState.Categorized;
    }
  }
}

    Implementation details:

    • Report errors back to the user interactively through the IDE by using the ReportError method of the IVsSettingsReader interface:

        reader.ReadSettingString("PbrsAlpha", out value);
  if (value == null || value == ""){
      reader.ReportError("Unable to Retrieve Sort Value");
  }

    • Prior to actually retrieving stored settings, an implementation of the LoadSettingsFromXml method should use the ReadFileVersion method to verify that version of Visual Studio that exports the stored settings is supported.

      In the case of the example below, the implementation checks to see if settings were produced by a version of Visual Studio with a major version number of m_supportVer, and if not, signals an error.

      if (pnMajor != m_supportVer){
  reader.ReportError("Unsupported Version");
}

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

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

      Note

      Names need to be unique only within the scope of the implementing class because 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 is called with the same value of pszSettingName, the original value is overwritten in the settings file.

  3. Ensure the coherence between VSPackage state and locally stored or cached settings.

    This step is normally performed during the implementation of the SaveSettingsToStorage method (as is seen in the example below). The details of this step are specific to a VSPackage and may involve obtaining the state of the VSPackage from automation, querying the VSPackage, and setting registry keys.

    Note

    The LoadSettingsFromStorage method should retrieve the information saved by the SaveSettingsToStorage method when the LoadSettingsFromStorage method is called by the IDE during its initialization of the VSPackage that it supports.

    In the example below, the class providing settings support implements the SaveSettingsToStorage method to:

    • Obtain access to the VSPackage's updated state information.

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

    • Use that information to update the VSPackage's registry settings.

      if (mySvc.MyPackage.packageState != null) {
  using (rootKey) {
    using(RegistryKey pbrsKey = rootKey.CreateSubKey(this.GetType().Name)) {
      using (pbrsKey) {
        ((IComPropertyBrowser)mySvc.MyPackage.packageState).SaveState(pbrsKey);
      }
    }
  }
}

    • Note

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

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

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

    [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 8.0.

    For more information, see Persisting Settings and ProvideProfileAttribute

Example

The following example implements IProfileManager on a class.

namespace myProfileManagerNameSpace  {
  
  using System;
  using System.Runtime.InteropServices;
  using Microsoft.VisualStudio.Shell;
  using Microsoft.VisualStudio.Shell.Interop;
  using Microsoft.Win32;
  using myPackageNameSpace;
  
  
  [Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")]
  internal class MyPackageProfileManager : System.ComponentModel.Component , IProfileManager {
    internal const int m_supportVer = 8;
    public void SaveSettingsToXml(IVsSettingsWriter writer) {
      MyPackageService mySvc = GetService(typeof(MyPackage)) as MyPackageService;
      if (mySvc != null) {
        // Information is stored in a StateObject.
        StateObject myState = mySvc.MyPackage.packageState;
        writer.WriteSettingString( 
                                  "PbrsAlpha", 
                                  (myState.SortState == SortState.Alphabetical ? "1" : "0"));
        writer.WriteSettingString( 
                                  "PbrsShowDesc", 
                                  (myState.HelpVisible ? "1" : "0"));
      }
    }
    
    public void LoadSettingsFromXml(IVsSettingsReader reader)
    {
      
      int pnMajor, pnMinor, pnBuild;
      // First check if we are getting data from the correct major version. 
      reader.ReadVersion(pnMajor, pnMinor, pnBuild);
      if (pnMajor != m_supportVer){
        reader.ReportError("Unsupported Version");
      }else{
        MyPackageService mySvc = GetService(typeof(IVSMDMyPackage)) as MyPackageService;
        if (mySvc != null){
          string value;
          StateObject myState = mySvc.MyPackage.packageState;
          reader.ReadSettingString("PbrsShowDesc", out value);
          // Not all values must be present.
          if (value == null || value == ""){
              reader.ReportError("Unable to Help Visibility Setting");
          }else{
            myState.HelpVisible = !value.Equals("0");
          }
          reader.ReadSettingString("PbrsAlpha", out value);
          // Not all values must be present.
          if (value == null || value == ""){
              reader.ReportError("Unable to Retrieve Sort Value");
          }else{
            if (!value.Equals("0")){
              myState.SortState = SortState.Alphabetical;
            }else{
              myState.SortState = SortState.Categorized;
            }
          }
        }
      }
    }

    public void SaveSettingsToStorage() {
      MyPackageService mySvc = GetService(typeof(IVSMDMyPackage)) as MyPackageService;
      Package package = GetService(typeof(Package)) as Package;
      RegistryKey rootKey = package.UserRegistryRoot;
      
      if (mySvc.MyPackage.packageState != null) {
        using (rootKey) {
          using(RegistryKey pbrsKey = rootKey.CreateSubKey(this.GetType().Name)) {
            using (pbrsKey) {
              ((IComPropertyBrowser)mySvc.MyPackage.packageState).SaveState(pbrsKey);
            }
          }
        }
      }
    }
    
    public void LoadSettingsFromStorage() {
      MyPackageService mySvc = GetService(typeof(IVSMDMyPackage)) as MyPackageService;
      Package package = GetService(typeof(Package)) as Package;
      RegistryKey rootKey = package.UserRegistryRoot;
      using (rootKey) {
        RegistryKey pbrsKey = rootKey.OpenSubKey(this.GetType().Name);
        if (pbrsKey != null) {
          using (pbrsKey) {
            if (mySvc.MyPackage.MakeCurrentSettingTheDefault()){
              ((IComPropertyBrowser)mySvc.MyPackage.packageState).SaveState(pbrsKey);
            }else{
              ((IComPropertyBrowser)mySvc.MyPackage.packageState).LoadState(pbrsKey);
            }
          }
        }
      }
    }
  }
}

See Also

Tasks

How to: Export Settings By Using the Managed Package Framework

Concepts

Persisting Settings

Reference

IProfileManager

IVsSettingsWriter