Partager via


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

'Déclaration
Function ImportSettings ( _
    pszCategoryGUID As String, _
    pSettings As IVsSettingsReader, _
    flags As UInteger, _
    <OutAttribute> ByRef pfRestartRequired As Integer _
) As Integer
'Utilisation
Dim instance As IVsUserSettings
Dim pszCategoryGUID As String
Dim pSettings As IVsSettingsReader
Dim flags As UInteger
Dim pfRestartRequired As Integer
Dim returnValue As Integer

returnValue = instance.ImportSettings(pszCategoryGUID, _
    pSettings, flags, pfRestartRequired)
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
)
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 Persisting Settings.

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

Permissions

See Also

Concepts

Persisting Settings

How to: Export Settings By Using Interop Assemblies

How to: Use Interop Assemblies to Import Settings

Reference

IVsUserSettings Interface

IVsUserSettings Members

Microsoft.VisualStudio.Shell.Interop Namespace

ExportSettings

IVsUserSettingsQuery