This documentation is archived and is not being maintained.

IVsSettingsReader Interface

Provides read access to configuration information stored in the Visual Studio settings file.

Namespace:  Microsoft.VisualStudio.Shell.Interop
Assembly:  Microsoft.VisualStudio.Shell.Interop.8.0 (in Microsoft.VisualStudio.Shell.Interop.8.0.dll)

public interface IVsSettingsReader

The IVsSettingsReader type exposes the following members.

Public methodReadCategoryVersion
Public methodReadFileVersion
Public methodReadSettingAttributeInfrastructure.
Public methodReadSettingBooleanReturns the value of a Boolean object stored in the Visual Studio settings file.
Public methodReadSettingBytesReturns the values of an array stored in the Visual Studio settings file.
Public methodReadSettingLongReturns the value of a Long object stored in the Visual Studio settings file.
Public methodReadSettingStringReturns the value of a String object stored in the Visual Studio settings file.
Public methodReadSettingXml
Public methodReadSettingXmlAsString
Public methodReportError

This interface is implemented by the environment.

Notes for Callers

Call the IVsSettingsReader interface when retrieving a VSPackage's stored configuration information from the Visual Studio settings file.

Notes for Implementers

Only VSPackages that have registered their support for the Visual Studio settings mechanism make use of the IVsSettingsReader interface. For more information on registering a VSPackage that supports the Visual Studio settings mechanism, see Persisting Settings.

When a settings import operation has been selected from the Import/Export Settings feature available on the IDE’s Tools menu, the environment passes a IVsSettingsReader interface to a VSPackage's settings import method, which uses the interface to read in configuration data. The Visual Studio SDK supports several import methods:

  • For interop assembly based VSPackages, the import method is the VSPackage's implementation of the IVsUserSettings interface's ImportSettings method.

  • For most Managed Package Framework based VSPackages, the import method is the VSPackage's implementation of the IProfileManager interface's LoadSettingsFromXml method.

  • For Managed Package Framework based VSPackages implementing the DialogPage interface, the import method is that interface's LoadSettingsFromXml method.

For more information importing settings, see How to: Use Interop Assemblies to Import Settings or How to: Import Settings By Using the Managed Package Framework.

In the example below, is an implementation of the ImportSettings, which reads in three settings values. This method uses some of the retrieved values to determine how to retrieve other value: the size of the input buffer pTrashBytes is determined by retrieving the value of lTrashLength retrieved earlier.


Best practice when storing buffers or string is to save the size of the stored buffer or string as well as with the object itself. This size information should always be used when retrieving the saved buffer of string to avoid buffer overruns.

HRESULT ImportSettings_CommandBars(IVsSettingsReader *pSettings, UserSettingsFlags flags, BOOL *pfRestartRequired)
    if (!pSettings)
        return E_INVALIDARG;
    if (pfRestartRequired)
            *pfRestartRequired = FALSE; //Nobody should require a restart!!
    CComBSTR bstrFirstSettingName;
    long lTrashLength = 0;
    BYTE *pTrashBytes = NULL;
    //Determines whether we can treat import as an additive operation, or a reset all settings operation
    BOOL fResetCompletely = FALSE; 
    if (flags & USF_ResetOnImport)
        fResetCompletely = TRUE;
    hr = pSettings->ReadSettingString(c_szFirstSettingName, &bstrFirstSettingName);
    hr = pSettings->ReadSettingLong(c_szRandomTrashLength, &lTrashLength);
    if (lTrashLength > 0)
            pTrashBytes = (BYTE*)VSAlloc(lTrashLength);
            long lDataRead = 0;
            hr = pSettings->ReadSettingBytes(c_szRandomTrashLength, pTrashBytes, &lDataRead, lTrashLength);
            if (lDataRead != lTrashLength)
        hr = E_UNEXPECTED;
        goto Error;
    //Note: before returning these settings should immediately be applied to your personal
    //            settings store, whether in the registry or the file system.
    //This write-through cache methodology is essential to allow us to work in multi-instance IDE scenarios.
    hr = UpdateState_CommandBar(bstrFirstSettingName,lTrashLength,pTrashBytes,lDataRead);
    return hr;