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)

[GuidAttribute("38C38501-1428-4ABB-8B27-2F0E1E6DD757")]
[InterfaceTypeAttribute()]
public interface IVsSettingsReader

The IVsSettingsReader type exposes the following members.

  NameDescription
Public methodReadCategoryVersionReturns the value of a category version object stored in the Visual Studio settings file.
Public methodReadFileVersionReturns the value of a file version object stored in the Visual Studio settings file.
Public methodReadSettingAttributeReturns the value of an attribute object stored in the Visual Studio settings file.
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 methodReadSettingXmlReturns the value of an XML object stored in the Visual Studio settings file.
Public methodReadSettingXmlAsStringReturns the value of an XML setting as a string object stored in the Visual Studio settings file.
Public methodReportErrorReports the error status of the settings file read operation.
Top

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 Support for User 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 Importing Settings.

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.

NoteNote

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);
    IfFailGo(hr);
    
    hr = pSettings->ReadSettingLong(c_szRandomTrashLength, &lTrashLength);
    IfFailGo(hr);
    
    if (lTrashLength > 0)
        {
            pTrashBytes = (BYTE*)VSAlloc(lTrashLength);
            IfNullMemGo(pTrashBytes);
            
            long lDataRead = 0;
            
            hr = pSettings->ReadSettingBytes(c_szRandomTrashLength, pTrashBytes, &lDataRead, lTrashLength);
            IfFailGo(hr);
            
            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);
    
 Error:
    return hr;
};
Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2015 Microsoft