IVsSettingsReader Interface

Definition

Namespace:

Microsoft.VisualStudio.Shell.Interop

Assembly:

Microsoft.VisualStudio.Interop.dll

Package:

Microsoft.VisualStudio.Interop v17.12.40391

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

public interface class IVsSettingsReader

public interface class IVsSettingsReader

__interface IVsSettingsReader

[System.Runtime.InteropServices.Guid("38C38501-1428-4ABB-8B27-2F0E1E6DD757")]
[System.Runtime.InteropServices.InterfaceType(1)]
public interface IVsSettingsReader

[<System.Runtime.InteropServices.Guid("38C38501-1428-4ABB-8B27-2F0E1E6DD757")>]
[<System.Runtime.InteropServices.InterfaceType(1)>]
type IVsSettingsReader = interface

Public Interface IVsSettingsReader

Attributes

GuidAttribute InterfaceTypeAttribute

Examples

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.

Note

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;  
};  

Remarks

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.

Methods

ReadCategoryVersion(Int32, Int32, Int32, Int32)	Returns the value of a category version object stored in the Visual Studio settings file.
ReadFileVersion(Int32, Int32, Int32, Int32)	Returns the value of a file version object stored in the Visual Studio settings file.
ReadSettingAttribute(String, String, String)	Returns the value of an attribute object stored in the Visual Studio settings file.
ReadSettingBoolean(String, Int32)	Returns the value of a Boolean object stored in the Visual Studio settings file.
ReadSettingBytes(String, Byte, Int32, Int32)	Returns the values of an array stored in the Visual Studio settings file.
ReadSettingLong(String, Int32)	Returns the value of a Long object stored in the Visual Studio settings file.
ReadSettingString(String, String)	Returns the value of a String object stored in the Visual Studio settings file.
ReadSettingXml(String, Object)	Returns the value of an XML object stored in the Visual Studio settings file.
ReadSettingXmlAsString(String, String)	Returns the value of an XML setting as a string object stored in the Visual Studio settings file.
ReportError(String, UInt32)	Reports the error status of the settings file read operation.