IVsUserSettings.ImportSettings Method

public:
 int ImportSettings(System::String ^ pszCategoryGUID, Microsoft::VisualStudio::Shell::Interop::IVsSettingsReader ^ pSettings, System::UInt32 flags, [Runtime::InteropServices::Out] int % pfRestartRequired);

int ImportSettings(std::wstring const & pszCategoryGUID, Microsoft::VisualStudio::Shell::Interop::IVsSettingsReader const & pSettings, unsigned int flags, [Runtime::InteropServices::Out] int & pfRestartRequired);

public int ImportSettings (string pszCategoryGUID, Microsoft.VisualStudio.Shell.Interop.IVsSettingsReader pSettings, uint flags, out int pfRestartRequired);

abstract member ImportSettings : string * Microsoft.VisualStudio.Shell.Interop.IVsSettingsReader * uint32 * int -> int

Public Function ImportSettings (pszCategoryGUID As String, pSettings As IVsSettingsReader, flags As UInteger, ByRef pfRestartRequired As Integer) As Integer

Parameters

Returns

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

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

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.

Applies to