IVsUserSettings.ImportSettings Method

Definition

Namespace:

Microsoft.VisualStudio.Shell.Interop

Assembly:

Microsoft.VisualStudio.Interop.dll

Package:

Microsoft.VisualStudio.Interop v17.12.40391

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.

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

pszCategoryGUID

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

IVsSettingsReader

[in]An IVsSettingsWriter interface provided by the environment to the VSPackage providing read access to the Visual Studio settings file.

flags

UInt32

[in] Flag from the system indicating how an implementation of ImportSettings(String, IVsSettingsReader, UInt32, Int32) is supposed to process retrieved settings.The supported values of that are members of the __UserSettingsFlags enumeration.

pfRestartRequired

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.

Returns

Int32

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.