IVsUserSettings.ImportSettings Method
Retrieves a VSPackage's configuration using the Visual Studio settings mechanism when a user selects the import option of the Import/Export Settings feature on the IDE’s Tools menu.
Namespace: Microsoft.VisualStudio.Shell.Interop
Assembly: Microsoft.VisualStudio.Shell.Interop.8.0 (in Microsoft.VisualStudio.Shell.Interop.8.0.dll)
Syntax
'Declaration
Function ImportSettings ( _
pszCategoryGUID As String, _
pSettings As IVsSettingsReader, _
flags As UInteger, _
<OutAttribute> ByRef pfRestartRequired As Integer _
) As Integer
int ImportSettings(
string pszCategoryGUID,
IVsSettingsReader pSettings,
uint flags,
out int pfRestartRequired
)
int ImportSettings(
[InAttribute] String^ pszCategoryGUID,
[InAttribute] IVsSettingsReader^ pSettings,
[InAttribute] unsigned int flags,
[InAttribute] [OutAttribute] int% pfRestartRequired
)
abstract ImportSettings :
pszCategoryGUID:string *
pSettings:IVsSettingsReader *
flags:uint32 *
pfRestartRequired:int byref -> int
function ImportSettings(
pszCategoryGUID : String,
pSettings : IVsSettingsReader,
flags : uint,
pfRestartRequired : int
) : int
Parameters
- pszCategoryGUID
Type: System.String
[in] GUID identifying the group of settings to be imported. This is the identify GUID of the Custom Settings Point. For more information on Custom Settings Points see Registering Settings Persistence Support.
- pSettings
Type: Microsoft.VisualStudio.Shell.Interop.IVsSettingsReader
[in]An IVsSettingsWriter interface provided by the environment to the VSPackage providing read access to the Visual Studio settings file.
- flags
Type: System.UInt32
[in] Flag from the system indicating how an implementation of ImportSettings is supposed to process retrieved settings.
The supported values of that are members of the __UserSettingsFlags enumeration.
- pfRestartRequired
Type: System.Int32%
[out] Flag returned to the environment indicating if a restart of the IDE is required to complete environment reconfiguration based on retrieved data. If the value returned by pfRestartRequired is true, the environment should be restarted.
Return Value
Type: System.Int32
If the method succeeds, it returns S_OK. If it fails, it returns an error code.
Remarks
A single VSPackage can support more than one Custom Settings Point (settings category). Therefore, implementations of ImportSettings must check the category GUID passed in and choose the correct mechanism for retrieving the state specified by particular Custom Settings Point.
The settings information is contained in XML files. These manually editable XML files can suffer corruption on disk, may contain version-specific settings, and could be used as a vehicle for malicious attack. Therefore, validation of inputs is important as part of retrieving settings configuration data.
If invalidate is found, an implementation of ImportSettings can use the IDE to automatically prompt the user through the ReportError method.
The Visual Studio IDE itself prompts users to restart Visual Studio when a VSPackage implementing ImportSettings indicates that the Visual Studio environment needs to be restarted following the import of settings data by returning pfRestartRequired with a value of true. There is no need to implement either a user dialog or a shutdown of Visual Studio.
Examples
In this example, the implementation of ImportSettings chooses between two different methods of retrieving data depending on the pszCategoryGUID argument.
In the example, the handling of __UserSettingsFlags based flags is also shown.
STDMETHOD(ImportSettings)(WCHAR *pszCategoryGUID, IVsSettingsReader *pSettings, UserSettingsFlags flags, BOOL *pfRestartRequired)
{
CLSID clsidCategory;
HRESULT hr;
hr = CLSIDFromString(pszCategoryGUID, &clsidCategory);
IfFailGo(hr);
//Delegate to the right internal implementation based on the requested category
if (GUID_Profiles_CommandBars == clsidCategory)
{
hr = ImportSettings_CommandBars(, pSettings, flags, pfRestartRequired);
}
else if (GUID_Profiles_KeyBindings == clsidCategory)
{
hr = ImportSettings_KeyBindings( pSettings, flags, pfRestartRequired);
}
else
{
hr = E_UNEXPECTED;
}
Error:
return hr;
};
// Import Settings
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;
};
HRESULT ImportSettings_KeyBindings(IVsSettingsReader *pSettings, UserSettingsFlags flags, BOOL *pfRestartRequired)
{
if (!pSettings)
return E_INVALIDARG;
if (pfRestartRequired)
{
*pfRestartRequired = FALSE; //Nobody should require a restart!!
}
CComBSTR bstrBreakPointWindow;
//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_szBreakPointWindow, &bstrBreakPointWindow);
IfFailGo(hr);
//Note: Before returning, these settings should immediately be applied to your personal
// settings store, whether in the registry or the file system.
//This write-thru cache methodology is essential to allow us to work in multi-instance IDE scenarios.
hr = UpdateState_KeyBindings(bstrBreakPointWindow);
Error:
return hr;
}
.NET Framework Security
- Full trust for the immediate caller. This member cannot be used by partially trusted code. For more information, see Using Libraries from Partially Trusted Code.
See Also
Reference
Microsoft.VisualStudio.Shell.Interop Namespace