How to: Export Settings By Using the Managed Package Framework
The Visual Studio integrated development environment (IDE) uses classes that implement the IProfileManager interface and classes that are registered as supporting a given VSPackage implementation to save the state of a VSPackage.
Because the IDE instantiates the class that implements the IProfileManager interface to support the settings, IProfileManager should be implemented in an independent class.
Note
Do not implement IProfileManager on the class that implements Package.
To implement the export of settings
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:
[Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")] internal class MyPackageProfileManager : Component, IProfileManagerEnsure 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.
Dim mySvc As MyPackageService = TryCast(GetService(GetType(IVSMDMyPackage)), MyPackageService) Dim package As Package = TryCast(GetService(GetType(Package)), Package) Dim rootKey As RegistryKey = package.UserRegistryRootMyPackageService 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.
If mySvc.MyPackage.MakeCurrentSettingTheDefault() Then DirectCast(mySvc.MyPackage.packageState, IComPropertyBrowser).SaveState(pbrsKey) Else DirectCast(mySvc.MyPackage.packageState, IComPropertyBrowser).LoadState(pbrsKey) End Ifif (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.
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.
Dim mySvc As MyPackageService = TryCast(GetService(GetType(MyPackage)), MyPackageService) If mySvc IsNot Nothing Then ' Information is stored in a StateObject Dim myState As StateObject = mySvc.MyPackage.packageState writer.WriteSettingString("PbrsAlpha", (If(myState.SortState = SortState.Alphabetical, "1", "0"))) writer.WriteSettingString("PbrsShowDesc", (If(myState.HelpVisible, "1", "0"))) End IfMyPackageService 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")); }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.
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.
<ProvideProfile(GetType(MyPackageProfileManager), "CoreUI", "MyPackage", 1004, 1004, False)> _ <Guid("YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY")> _ Class MyPackage Inherits Package End Class[ProvideProfile(typeof(MyPackageProfileManager), "CoreUI", "MyPackage", 1004, 1004, false)] [Guid("YYYYYYYY-YYYY-YYYY-YYYY-YYYYYYYYYYYY")] class MyPackage: PackageIn 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 Persisting Settings and ProvideProfileAttribute.
Example
The following example implements IProfileManager on a class.
Imports System
Imports System.Runtime.InteropServices
Imports Microsoft.VisualStudio.Shell
Imports Microsoft.VisualStudio.Shell.Interop
Imports Microsoft.Win32
Imports myPackageNameSpace
Namespace myProfileManagerNameSpace
<Guid("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")> _
Friend Class MyPackageProfileManager
Inherits System.ComponentModel.Component
Implements IProfileManager
Friend Const m_supportVer As Integer = 8
Public Sub SaveSettingsToXml(ByVal writer As IVsSettingsWriter)
Dim mySvc As MyPackageService = TryCast(GetService(GetType(MyPackage)), MyPackageService)
If mySvc IsNot Nothing Then
' Information is stored in a StateObject.
Dim myState As StateObject = mySvc.MyPackage.packageState
writer.WriteSettingString("PbrsAlpha", (If(myState.SortState = SortState.Alphabetical, "1", "0")))
writer.WriteSettingString("PbrsShowDesc", (If(myState.HelpVisible, "1", "0")))
End If
End Sub
Public Sub LoadSettingsFromXml(ByVal reader As IVsSettingsReader)
Dim pnMajor As Integer, pnMinor As Integer, pnBuild As Integer
' First, check if data is obtained from the correct major version
reader.ReadVersion(pnMajor, pnMinor, pnBuild)
If pnMajor <> m_supportVer Then
reader.ReportError("Unsupported Version")
Else
Dim mySvc As MyPackageService = TryCast(GetService(GetType(IVSMDMyPackage)), MyPackageService)
If mySvc IsNot Nothing Then
Dim value As String
Dim myState As StateObject = mySvc.MyPackage.packageState
reader.ReadSettingString("PbrsShowDesc", value)
' Not all values must be present.
If value Is Nothing OrElse value = "" Then
reader.ReportError("Unable to Help Visibility Setting")
Else
myState.HelpVisible = Not value.Equals("0")
End If
reader.ReadSettingString("PbrsAlpha", value)
' Not all values must be present.
If value Is Nothing OrElse value = "" Then
reader.ReportError("Unable to Retrieve Sort Value")
Else
If Not value.Equals("0") Then
myState.SortState = SortState.Alphabetical
Else
myState.SortState = SortState.Categorized
End If
End If
End If
End If
End Sub
Public Sub SaveSettingsToStorage()
Dim mySvc As MyPackageService = TryCast(GetService(GetType(IVSMDMyPackage)), MyPackageService)
Dim package As Package = TryCast(GetService(GetType(Package)), Package)
Dim rootKey As RegistryKey = package.UserRegistryRoot
If mySvc.MyPackage.packageState IsNot Nothing Then
Using rootKey
Using pbrsKey As RegistryKey = rootKey.CreateSubKey(Me.[GetType]().Name)
Using pbrsKey
DirectCast(mySvc.MyPackage.packageState, IComPropertyBrowser).SaveState(pbrsKey)
End Using
End Using
End Using
End If
End Sub
Public Sub LoadSettingsFromStorage()
Dim mySvc As MyPackageService = TryCast(GetService(GetType(IVSMDMyPackage)), MyPackageService)
Dim package As Package = TryCast(GetService(GetType(Package)), Package)
Dim rootKey As RegistryKey = package.UserRegistryRoot
Using rootKey
Dim pbrsKey As RegistryKey = rootKey.OpenSubKey(Me.[GetType]().Name)
If pbrsKey IsNot Nothing Then
Using pbrsKey
If mySvc.MyPackage.MakeCurrentSettingTheDefault() Then
DirectCast(mySvc.MyPackage.packageState, IComPropertyBrowser).SaveState(pbrsKey)
Else
DirectCast(mySvc.MyPackage.packageState, IComPropertyBrowser).LoadState(pbrsKey)
End If
End Using
End If
End Using
End Sub
End Class
End Namespace
Convert C# to VB.NET
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 data is obtained 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: Import Settings By Using the Managed Package Framework