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)
Syntax
'Declaration
<InterfaceTypeAttribute()> _
<GuidAttribute("38C38501-1428-4ABB-8B27-2F0E1E6DD757")> _
Public Interface IVsSettingsReader
'Usage
Dim instance As IVsSettingsReader
[InterfaceTypeAttribute()]
[GuidAttribute("38C38501-1428-4ABB-8B27-2F0E1E6DD757")]
public interface IVsSettingsReader
[InterfaceTypeAttribute()]
[GuidAttribute(L"38C38501-1428-4ABB-8B27-2F0E1E6DD757")]
public interface class IVsSettingsReader
public interface IVsSettingsReader
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
Concepts
How to: Use Interop Assemblies to Import Settings
How to: Import Settings By Using the Managed Package Framework