Partager via

IVsSettingsReader Interface

  • Article

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)

Syntax

'Declaration
<GuidAttribute("38C38501-1428-4ABB-8B27-2F0E1E6DD757")> _
<InterfaceTypeAttribute()> _
Public Interface IVsSettingsReader

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

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

[<GuidAttribute("38C38501-1428-4ABB-8B27-2F0E1E6DD757")>]
[<InterfaceTypeAttribute()>]
type IVsSettingsReader =  interface end

public interface IVsSettingsReader

The IVsSettingsReader type exposes the following members.

Methods

  Name Description
Public method ReadCategoryVersion Returns the value of a category version object stored in the Visual Studio settings file.
Public method ReadFileVersion Returns the value of a file version object stored in the Visual Studio settings file.
Public method ReadSettingAttribute Returns the value of an attribute object stored in the Visual Studio settings file.
Public method ReadSettingBoolean Returns the value of a Boolean object stored in the Visual Studio settings file.
Public method ReadSettingBytes Returns the values of an array stored in the Visual Studio settings file.
Public method ReadSettingLong Returns the value of a Long object stored in the Visual Studio settings file.
Public method ReadSettingString Returns the value of a String object stored in the Visual Studio settings file.
Public method ReadSettingXml Returns the value of an XML object stored in the Visual Studio settings file.
Public method ReadSettingXmlAsString Returns the value of an XML setting as a string object stored in the Visual Studio settings file.
Public method ReportError Reports the error status of the settings file read operation.

Top

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

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

See Also

Reference

Microsoft.VisualStudio.Shell.Interop Namespace

ImportSettings

IVsSettingsWriter

Other Resources

Persisting Settings

How to: Use Interop Assemblies to Import Settings

How to: Import Settings By Using the Managed Package Framework

Working with Settings