Comment : Exporter des paramètres à l'aide de les assemblys d'interopérabilité
Un VSPackage peut exporter des paramètres de l'environnement de développement intégré (IDE) de (IDE) Visual Studio . L'IDE utilise l'implémentation d'un VSPackage de l'interface d' IVsUserSettings . Si le package fournit également l'interface d' IVsUserSettingsQuery , l'interface d' IVsUserSettingsQuery est utilisée pour déterminer comment la configuration d'un VSPackage doit être inscrite.
Notes
Managed package (MPF) fournit un jeu de classes managées pour faciliter la conception des extensions Visual Studio.Pour effectuer cette tâche à l'aide de le MPF, consultez Comment : Exporter des paramètres à l'aide de managed package.
pour implémenter l'exportation de paramètres sur un VSPackage
Implémentez la prise en charge de base du mécanisme de paramètres de Visual Studio .
Enregistrez le VSPackage comme prenant en charge le mécanisme de paramètres en définissant un ou plusieurs points de paramètres personnalisés.
Pour plus d'informations, consultez Rendre des paramètres.
Indiquez que le VSPackage implémente IVsUserSettings. Si vous le souhaitez, le VSPackage peut également implémenter l'interface de IVsUserSettingsQuery . Par exemple :
public class MyPackage : IVsPackage, IVsUserSettings, IVsUserSettingsQueryAssurez -vous que l'implémentation du VSPackage de la méthode d' QueryInterface fournit une interface d' IVsUserSettings lorsqu'elle est appelée avec IID_IVsUserSettings.
éventuellement, QueryInterface peut fournir une interface d' IVsUserSettingsQuery une fois appelé avec l'interface d' 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; }
Éventuellement, alerter l'IDE de la nécessité d'exporter un paramètre particulier.
Un VSPackage peut choisir d'enregistrer sous un paramètre que l'état des points de paramètres personnalisés définit. Par exemple, enregistrez uniquement si l'utilisateur indique explicitement un paramètre à enregistrer.
Dans ce cas, l'interface d' IVsUserSettingsQuery doit être implémenté.
si un VSPackage n'implémente pas IVsUserSettingsQuery, toutes ses informations d'état sont enregistrées pendant une exportation de paramètres.
Un VSPackage peut prendre en charge plusieurs points de paramètres personnalisés (catégorie de paramètres). Les implémentations de la méthode d' NeedExport doivent activer le GUID de point de paramètres personnalisés fourni ou argument de catégorie de paramètres pour déterminer si un groupe particulier de paramètres doit être enregistré.
Dans l'exemple ci-dessous, les demandes d'un VSPackage toujours que son état de barre de commandes est enregistré, mais les demande uniquement que son état de combinaison de touches s'affiche si une balise a été définie.
données de paramètres d'Écriture au fichier de paramètres.
Pour prendre en charge exporter des paramètres, un VSPackage doit toujours implémenter la méthode d' ExportSettings .
L'implémentation doit gérer les arguments passés par l'IDE, un GUID de cette catégorie de point de paramètres personnalisés, et une interface d' IVsSettingsWriter .
Un VSPackage peut prendre en charge plusieurs points de paramètres personnalisés (catégorie de paramètres). Dans l'exemple ci-dessous, les appels de méthode d' ExportSettings une implémentation différente pour rendre persistant l'état de barre de commandes par opposition à rendre persistant l'état de combinaison de touches.
Un VSPackage doit utiliser l'interface fournie d' IVsSettingsWriter pour enregistrer des données dans le fichier de paramètres.
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);
};
La valeur de l'argument d' pszSettingName fourni à une interface d' IVsSettingsWriter doit identifier de manière unique chaque élément de données stockées dans une catégorie de paramètres.
Notes
Les noms doivent être uniques dans un point de paramètres personnalisés car l'IDE utilise son GUID et la valeur d' pszSettingName pour identifier chaque paramètre enregistré.Si plusieurs méthodes d' IVsSettingsWriter est appelée avec la même valeur d' pszSettingName, la valeur d'origine est remplacée dans le fichier de paramètres.
Le fichier de paramètres prend en charge l'accès aux données aléatoires. Par conséquent, l'ordre des opérations de lecture et d'écriture de paramètres n'est pas importante.
Ceci est illustré dans les implémentations d'exporter et d'importer l'état de barre de commandes (ExportSettings_CommandBar et ImportSettings_CommandBar) dans l'exemple ci-dessous.
Si l'implémentation peut des données qui mappent dans l'un des quatre formats pris en charge, il n'existe aucune restriction sur le nombre et le type de données peut être écrit.
Notes
Outre les données explicitement entrées et transparentes à l'implémentation d' ExportSettings , l'API de paramètres enregistre également des informations de version de Visual Studio .Les paramètres stockés peuvent être comparés par rapport à la version de l'IDE qui les a générés lors de l'importation de paramètres.
Exemple
l'exemple suivant montre comment importer et exporter des données de paramètres.
// --------------------------------------------------------------------------
// 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;
}
Voir aussi
Tâches
Comment : Assemblys d'interopérabilité d'utilisation pour importer des paramètres