Практическое руководство. Использование сборок взаимодействия для задания параметров импорта

Статья
05/18/2015

VSPackage может импортировать параметры из Visual Studio интегрированная среда разработки (ide). Интегрированная среда разработки использует реализацию VSPackage IVsUserSettings интерфейс для определения того, как конфигурация VSPackage требуется извлечь.

Примечание

Управляемый пакет .NET Framework (MPF) предоставляет набор управляемых классов, чтобы упростить создание расширений Visual Studio.Для выполнения этой задачи, используя MPF, эти Практическое руководство. Параметры импорта с помощью MPF.

Реализовать импорт параметров VSPackage

Реализуйте базовую поддержку Visual Studio механизм параметров.

Зарегистрируйте VSPackage, как обеспечить механизм параметров, указав одно или более пользовательских точек параметров.

Дополнительные сведения см. в разделе Сохранение параметров.
Объявите, что VSPackage реализует IVsUserSettings интерфейс, например:
```
public class MyPackage : IVsPackage, IVsUserSettings, IVsUserSettingsQuery
```

Убедитесь, что реализация VSPackage QueryInterface предоставляет a метода IVsUserSettings интерфейс вызывается с IID_IVsUserSettings. Примеры.

STDMETHODIMP MyPackage::QueryInterface(THIS_ REFIID riid, LPVOID FAR* ppvObj)
{
    if (ppvObj == NULL)
        return E_POINTER;

    *ppvObj = NULL;

    if (riid == IID_IUnknown)
        *ppvObj = (LPVOID)(IUnknown *)(IClassFactory*)this;
    else if (riid == IID_IClassFactory)
        *ppvObj = (LPVOID)(IClassFactory *)this;
    else if (riid == IID_IVsPackage)
        *ppvObj = (LPVOID)(IVsPackage *)this;
    else if (riid == IID_IVsPersistSolutionOpts)
        *ppvObj = (LPVOID)(IVsPersistSolutionOpts *)this;
    else if (riid == IID_IVsPersistSolutionProps)
        *ppvObj = (LPVOID)(IVsPersistSolutionProps *)this;
    else if (riid == IID_IVsComponentSelectorProvider)
        *ppvObj = (LPVOID)(IVsComponentSelectorProvider *)this;
    else if (riid == IID_IVsUserSettings)
        *ppvObj = (LPVOID)(IVsUserSettings *)this;
    else if (riid == IID_IVsUserSettingsQuery)
        *ppvObj = (LPVOID)(IVsUserSettingsQuery *)this;

    if (*ppvObj)
    {
        AddRef();
        return NOERROR;
    }
    return E_NOINTERFACE;
}

Извлечение сведений о параметрах.

Для поддержки извлечения данных параметров VSPackage должен реализовать ImportSettings метод.

Чтение данных, реализация VSPackage IVsUserSettings интерфейс должен использовать первые 2 аргумента, передаваемого в интегрированной средой разработки: идентификатор GUID этой пользовательской категории параметров и точек IVsSettingsReader интерфейс.
1. Реализация VSPackage ImportSettings метод должен проверить, передаваемое GUID категории и выбрать правильный механизм для восстановления состояния.
  
  В примере, приведенном ниже, ImportSettings вызовы метода другую реализацию для восстановления состояния панели команд в отличие от восстановления состояния ключ-привязки.
2. VSPackage необходимо использовать предоставленное IVsSettingsReader интерфейс для получения данных к файлу параметров.
  
  Примечание
  
  Если сведения о параметрах изменяются как функция a ReadFileVersion версия реализация VSPackage ImportSettings метод должен использовать Visual Studio метод до данных чтения, чтобы проверка версии интегрированной среды разработки.
  
  Интерфейс содержит методы для чтения различные типы данных из файла параметров.
  
  interface IVsSettingsReader : IUnknown
  
  {
  
      HRESULT ReadSettingString(WCHAR *pszSettingName, BSTR *pbstrSettingValue);
  
      HRESULT ReadSettingLong(WCHAR *pszSettingName, long *plSettingValue);
  
      HRESULT ReadSettingBoolean(WCHAR *pszSettingName, BOOL *pfSettingValue);
  
      HRESULT ReadSettingAttribute(LPCOLESTR pszSettingName,LPCOLESTR pszAttributeName, BSTR *pbstrSettingValue); //Internal use only
  
      HRESULT ReadSettingBytes(WCHAR *pszSettingName, BYTE *pSettingValue, long *plDataLength, long lDataMax);
  
      HRESULT ReadVersion(int *pnMajor, int *pnMinor, int *pnBuild);
  
      HRESULT ReportError(WCHAR *pszError);
  
  };
Файл параметров поддерживает случайный доступ к данным, поэтому порядок операций чтения и записи параметров не имеет значения.

Это продемонстрировано в состоянии импортирования и экспортирования панели команд (ExportSettings_CommandBar и ImportSettings_CommandBarреализации в примере ниже.)
Validate извлечения данных.

Сведения о параметрах содержащихся в xml-файле, можно изменить вручную.

Примечание по безопасности
Сведения о параметрах могут быть поврежден на диске, могут содержать параметры для конкретной версии, и могут использоваться в качестве корабль для злостой атаки.Допустимость каждого элемента данных, возвращаемых IVsSettingsReader метод должен быть установлен.

Сведения о параметрах могут быть поврежден на диске, могут содержать параметры для конкретной версии, и могут использоваться в качестве корабль для злостой атаки.Допустимость каждого элемента данных, возвращаемых IVsSettingsReader метод должен быть установлен.

Проверить поддержку версии ReadFileVersion используется для создания извлеченные параметры, вызовите Visual Studio метод для получения версии.
Вызвать интегрированную среду разработки уведомления пользователя о том, что импортированного элемента данных не проверяет, вызовы VSPackage ReportError метод.

Примените сведения о параметрах.
1. Реализация ImportSettings метод должен учитывать значение третьего аргумента, интегрированная среда разработки передала к ней. Поддерживаемые значения членов __UserSettingsFlags перечисление. Дополнительные сведения см. в разделе __UserSettingsFlags.
  
  В примере, приведенном ниже, реализация импортировать параметры панели команд (ImportSettings_Commandbar) значение этого аргумента, чтобы определить, использует ли применить параметры, чтобы перезаписать существующие значения или аддитивно обновить их.
2. Необходимо реализовать a запись-через методологии кэша при применении импортированные параметры.
  
  Сведения о состоянии в реестре или в файловой системе необходимо обновить в то время как параметры применяются к интегрированной среде разработки. Это гарантирует сцепление конфигурации и поддерживает сценарии интегрированной среды разработки нескольких экземпляров.
Интегрированная среда разработки предупреждений, как обрабатывать импорт параметров.

Используйте возвращенный ImportSettings аргумент pfRestartRequired метод advise интегрированной среде разработки, если требуется перезапуск импортированные применяет параметры.

Если реализация VSPackage ImportSettings метод возвращает trueпользователь, предлагается перезагрузить интегрированная среда разработки.

Пример

В этом примере показано, как импортировать и экспортировать данные о параметрах.

static const WCHAR c_szFirstSettingName[] = L"FirstSettingName";
static const WCHAR c_szRandomTrashBytes[] = L"RandomTrashBytes";
static const WCHAR c_szRandomTrashLength[] = L"RandomTrashLength";
static const WCHAR c_szBreakPointWindow[] = L"Breakpoints Window";
// --------------------------------------------------------------------------
//    IVsUserSettings methods used for configuration export and import
//    Delegate to the right shell object based on the category GUID
// --------------------------------------------------------------------------
static const WCHAR c_szFirstSettingName[] = L"FirstSettingName";
static const WCHAR c_szRandomTrashBytes[] = L"RandomTrashBytes";
static const WCHAR c_szRandomTrashLength[] = L"RandomTrashLength";
static const WCHAR c_szBreakPointWindow[] = L"Breakpoints Window";

// Export Settings.

STDMETHOD(NeedExport)(WCHAR* pszCategoryGUID, BOOL *pfNeedExport)
{
    if (!pfNeedExport)
        return E_INVALIDARG;
    
    CLSID clsidCategory;
    HRESULT hr= S_OK;
    
    hr = CLSIDFromString(pszCategoryGUID, &clsidCategory);
    IfFailGo(hr);
    if (GUID_Profiles_CommandBars == clsidCategory) {
        *pfNeedExport = TRUE; //Always export Command Bar Configuration
    }else if (GUID_Profiles_KeyBindings == clsidCategory) {
        *pfNeedExport = FALSE; //By Default don't export key bindings
        if (m_fMake_Permanent)
            *pfNeedExport = TRUE; //Export if user wants current configuration saved.
    }else{
        hr = E_UNEXPECTED;
    }
 Error:
    return hr;
}

STDMETHOD(ExportSettings)(WCHAR *pszCategoryGUID, IVsSettingsWriter *pSettings)
{
    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 = ExportSettings_CommandBars(pSettings);
    }else if (GUID_Profiles_KeyBindings == clsidCategory) {
        hr = ExportSettings_KeyBindings(pSettings);
    }else{
        hr = E_UNEXPECTED;
    }
 Error:
    return hr;
};


HRESULT ExportSettings_CommandBars(IVsSettingsWriter *pSettings)
{
    if (!pSettings)
        return E_INVALIDARG;
    
    hr = pSettings->WriteSettingString(c_szFirstSettingName, L"Value1");
    IfFailGo(hr);
    
    int cRandomTrash = 12345;
    BYTE *pRandomTrash = (BYTE *)VSAlloc(cRandomTrash);
    if (pRandomTrash){
        hr = pSettings->WriteSettingBytes(c_szRandomTrashBytes, pRandomTrash, cRandomTrash);
        IfFailGo(hr);
        hr = pSettings->WriteSettingLong(c_szRandomTrashLength, cRandomTrash);
        IfFailGo(hr);
    }
    
 Error:
    return hr;
};

HRESULT ExportSettings_KeyBindings(IVsSettingsWriter *pSettings)
{
    if (!pSettings)
        return E_INVALIDARG;
    
    hr = pSettings->WriteSettingString(c_szBreakPointWindow, L"Ctrl + Alt + B");
    IfFailGo(hr);
    
 Error:
    return hr;
};

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 to 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-thru cache methodology is essential 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 to 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 work in multi-instance IDE scenarios.
    hr = UpdateState_KeyBindings(bstrBreakPointWindow);
    
    
 Error:
    return hr;
}

См. также

Поделиться через

Практическое руководство. Использование сборок взаимодействия для задания параметров импорта

Реализовать импорт параметров VSPackage

Пример

См. также

Задачи

Основные понятия

Другие ресурсы

Дополнительные ресурсы