Compartilhar via

Método IVsUserSettings.ImportSettings (String, IVsSettingsReader, UInt32, Int32)

  • Artigo

 

Publicado: abril de 2016

Recupera a configuração do VSPackage usando o Visual Studio mecanismo configurações quando um usuário seleciona a opção de importação do configurações de importação/exportação recurso sobre o IDE ferramentas menu.

Namespace:   Microsoft.VisualStudio.Shell.Interop
Assembly:  Microsoft.VisualStudio.Shell.Interop.8.0 (em Microsoft.VisualStudio.Shell.Interop.8.0.dll)

Sintaxe

int ImportSettings(
    string pszCategoryGUID,
    IVsSettingsReader pSettings,
    uint flags,
    ref int pfRestartRequired
)

int ImportSettings(
    String^ pszCategoryGUID,
    IVsSettingsReader^ pSettings,
    unsigned int flags,
    int% pfRestartRequired
)

abstract ImportSettings : 
        pszCategoryGUID:string *
        pSettings:IVsSettingsReader *
        flags:uint32 *
        pfRestartRequired:int byref -> int

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

Parâmetros

  • pszCategoryGUID
    Type: System.String

    [in] GUID que identifica o grupo de configurações a serem importados. Essa é a identificação do GUID do ponto de configurações personalizadas. Para obter mais informações sobre pontos de configurações personalizadas, consulte suporte a persistência configurações do registro.

  • flags
    Type: System.UInt32

    [in] Sinalizador de sistema indicando como uma implementação de ImportSettings deve para processar configurações recuperadas.

    Os valores com suporte que são membros do __UserSettingsFlags enumeração.

  • pfRestartRequired
    Type: System.Int32

    [out] Sinalizador retornado para o ambiente que indica se uma reinicialização do IDE é necessário para concluir a reconfiguração do ambiente com base em dados recuperados. Se o valor retornado por pfRestartRequired é true, o ambiente deve ser reiniciado.

Valor Retornado

Type: System.Int32

Se o método for bem-sucedido, ele retornará S_OK. Se ele falhar, ele retorna um código de erro.

Comentários

Um único VSPackage pode dar suporte a mais de um ponto de configurações personalizado (configurações de categoria). Portanto, as implementações de ImportSettings deve verificar a categoria GUID passado e escolha o mecanismo correto para recuperar o estado especificado pelo ponto de configurações personalizado específico.

As informações de configurações estão contidas em arquivos XML. Esses arquivos XML manualmente editáveis podem sofrer corrupção no disco, podem conter configurações específicas da versão e pode ser usados como um veículo de ataques mal-intencionados. Portanto, a validação de entradas é importante como parte da recuperação de dados de configuração de configurações.

Se invalidar for encontrado, uma implementação de ImportSettings pode usar o IDE para solicitar automaticamente o usuário por meio de ReportError método.

O Visual Studio próprio IDE solicita que os usuários reiniciem Visual Studio ao implementar um VSPackage ImportSettings indica que o Visual Studio ambiente precisa ser reiniciado após a importação de dados de configurações, retornando pfRestartRequired com um valor de true. Não é necessário para implementar uma caixa de diálogo de usuário ou um desligamento de Visual Studio.

Exemplos

Neste exemplo, a implementação de ImportSettings escolhe entre dois métodos diferentes de recuperação de dados, dependendo do pszCategoryGUID argumento.

No exemplo, a manipulação de __UserSettingsFlags sinalizadores com base também são mostrados.

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

Confira Também

ExportSettings
IVsUserSettingsQuery
Interface IVsUserSettings
Namespace Microsoft.VisualStudio.Shell.Interop
Suporte para configurações de usuário
Como: exportar configurações usando Assemblies de interoperabilidade
Como: usar Assemblies de interoperabilidade para importar configurações

Retornar ao início