Практическое руководство. Экспорт параметров с помощью сборок взаимодействия
VSPackage может экспортировать параметры из Visual Studio интегрированная среда разработки (ide). Интегрированная среда разработки использует реализацию VSPackage IVsUserSettings интерфейс. Если пакет также предоставляет IVsUserSettingsQuery интерфейс, после чего IVsUserSettingsQuery интерфейс используется для определения того, как конфигурация VSPackage должны быть сохранены.
Примечание
Управляемый пакет .NET Framework (MPF) предоставляет набор управляемых классов, чтобы упростить создание расширений Visual Studio.Для выполнения этой задачи, используя MPF, эти Практическое руководство. Экспорт параметров с помощью MPF.
Реализовать экспорт параметров в VSPackage
Реализуйте базовую поддержку Visual Studio механизм параметров.
Зарегистрируйте VSPackage, как обеспечить механизм параметров, указав одно или более пользовательских точек параметров.
Дополнительные сведения см. в разделе Сохранение параметров.
Объявите, что VSPackage реализует IVsUserSettings. Если необходимо, VSPackage может также реализовать IVsUserSettingsQuery интерфейс. Примеры.
public class MyPackage : IVsPackage, IVsUserSettings, IVsUserSettingsQueryУбедитесь, что реализация VSPackage QueryInterface предоставляет метода IVsUserSettings интерфейс вызывается с IID_IVsUserSettings.
Дополнительно QueryInterface позволяет задавать IVsUserSettingsQuery интерфейс вызывается с IID_IVsUserSettingsQuery интерфейс.
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 может выбрать для условного сохранить параметр, пользовательское состояние точки параметров. Например, сохраните только если пользователь явно указывает параметр, который необходимо сохранить.
В этом случае IVsUserSettingsQuery интерфейс должен быть реализован.
Если VSPackage не реализует IVsUserSettingsQueryвесь сведения о состоянии сохранена во время экспорта параметров.
VSPackage может поддерживать несколько параметров укажите пользовательское (категорию параметров). Реализации NeedExport метод должен проверять аргумент категории GUID или параметра, передаваемого пользовательский пункта параметры для определения, является ли указанная группа в составе параметры должны быть сохранены.
В примере, приведенном ниже, VSPackage всегда запрашивает, что ее состояние панели команд сохраняется, но только запрашивающий, что его ключевое состояние привязки сохраняется, если пометить задан.
Сведения о параметрах записи в файл параметров.
Для поддержки экспортировать параметров VSPackage должно всегда реализация ExportSettings метод.
Реализация должна обрабатывать аргументы, передаваемые интегрированной средой разработки, GUID этой пользовательской категории параметров и точек IVsSettingsWriter интерфейс.
VSPackage может поддерживать несколько параметров укажите пользовательское (категорию параметров). В примере, приведенном ниже, ExportSettings вызовы метода другую реализацию для сохранения состояния панели команд в отличие от сохранения ключевого состояния привязки.
VSPackage необходимо использовать предоставленное IVsSettingsWriter интерфейс, чтобы сохранять данные в файле параметра.
interface IVsSettingsWriter : IUnknown
{
HRESULT WriteSettingString( LPCOLESTR pszSettingName, LPCOLESTR pszSettingValue);
HRESULT WriteSettingLong( LPCOLESTR pszSettingName, long lSettingValue);
HRESULT WriteSettingBoolean( LPCOLESTR pszSettingName, BOOL fSettingValue);
HRESULT WriteSettingBytes( LPCOLESTR pszSettingName, BYTE *pSettingValue, long lDataLength);
HRESULT WriteSettingAttribute( LPCOLESTR pszSettingName, LPCOLESTR pszAttributeName, LPCOLESTR pszSettingValue);
HRESULT WriteSettingXml( IUnknown *pIXMLDOMNode);
HRESULT WriteSettingXmlFromString( LPCOLESTR szXML);
HRESULT ReportError( LPCOLESTR pszError, VSSETTINGSERRORTYPES dwErrorType);
};
Значение pszSettingName аргумент, указанный в IVsSettingsWriter интерфейс должен уникально идентифицировать каждый элемент данных, сохраненный в категории параметров.
Примечание
Имена должны быть уникальными в пределах пользовательской точки параметров, поскольку интегрированная среда разработки и использует его значение GUID pszSettingName сохраненный идентифицировать каждый параметр.Если несколько объектов IVsSettingsWriter метод вызывается с тем же значением pszSettingName(исходное значение перезаписывается в файле параметров.
Файл параметров поддерживает случайный доступ к данным. Поэтому порядок операций чтения и записи параметров не имеет значения.
Это продемонстрировано в реализациях экспортировать и импортировать состояние панели команд (ExportSettings_CommandBar и ImportSettings_CommandBarв примере, приведенном ниже.)
Если реализация может данные карты в один из поддерживаемых форматов 4, отсутствие ограничений на объем или каком тип данных можно записать.
Примечание
В дополнение к данным, написанным с явно и прозрачному ExportSettings реализация api-интерфейса также сохраняет параметры Visual Studio сведения о версии.Сохраненные параметры можно сравнить с версии интегрированной среды разработки, сформировавшего их во время импорта параметров.
Пример
В следующем примере показано, как импортировать и экспортировать данные о параметрах.
// --------------------------------------------------------------------------
// IVsUserSettings methods used for configuration export.
// 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 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 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 import can be treated 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-through cache methodology is essential to allow us
// to work in multi-instance IDE scenarios.
hr = UpdateState_KeyBindings(bstrBreakPointWindow);
Error:
return hr;
}
См. также
Задачи
Практическое руководство. Использование сборок взаимодействия для задания параметров импорта