Export (0) Print
Expand All

IVsUserSettings.ImportSettings Method

Saves a VSPackage configuration by using the Visual Studio settings mechanism when a user clicks Import and Export Settings on the Tools menu and then selects Import selected environment settings.

Namespace: Microsoft.VisualStudio.Shell.Interop
Assembly: Microsoft.VisualStudio.Shell.Interop.8.0 (in microsoft.visualstudio.shell.interop.8.0.dll)

int ImportSettings (
	[InAttribute] string pszCategoryGUID,
	[InAttribute] IVsSettingsReader pSettings,
	[InAttribute] uint flags,
	[InAttribute] out int pfRestartRequired
)
int ImportSettings (
	/** @attribute InAttribute() */ String pszCategoryGUID, 
	/** @attribute InAttribute() */ IVsSettingsReader pSettings, 
	/** @attribute InAttribute() */ UInt32 flags, 
	/** @attribute InAttribute() */ /** @attribute OutAttribute() */ /** @ref */ int pfRestartRequired
)
JScript does not support passing value-type arguments by reference.

Parameters

pszCategoryGUID

[in] GUID that identifies the group of settings to be imported. This is the GUID for the Custom Settings Point. For more information about Custom Settings Points, see Persisting Settings.

pSettings

[in]An IVsSettingsWriter interface that is provided by the IDE to enable read access to the Visual Studio settings file.

flags

[in] Flag from the system that indicates how an implementation of ImportSettings should process retrieved settings.

The supported values of the flag are members of the __UserSettingsFlags enumeration.

pfRestartRequired

[out] Flag that is returned to the IDE to indicate whether a restart of the IDE is required to complete its reconfiguration, based on retrieved data. If the value returned by pfRestartRequired is true, the IDE should be restarted.

Return Value

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

A single VSPackage can support more than one Custom Settings Point. Therefore, implementations of ImportSettings must check the Custom Settings Point GUID that is passed in and then choose the correct mechanism for retrieving the state that is specified by that Custom Settings Point.

The settings information is contained in .xml files. These .xml files can be corrupted on disk, may contain version-specific settings, andor could be used as a vehicle for malicious attack. Therefore, validation of inputs is an important part of retrieving settings configuration data.

If invalid data is found, an implementation of ImportSettings can automatically prompt the user, through the ReportError method.

The IDE itself prompts users to restart Visual Studio when a VSPackage that implements ImportSettings indicates that the IDE must be restarted by returning pfRestartRequired with a value of true after the import of settings data. You do not have to implement a dialog box or a restart as part of your VSPackage.

In this example, the implementation of ImportSettings is enabled to choose 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;
}

Community Additions

ADD
Show:
© 2014 Microsoft