IVsProvideTargetedToolboxItems.GetInstanceOfExistingTypeForNewFramework Method

Definition

Namespace:

Microsoft.VisualStudio.Shell.Interop

Assembly:

Microsoft.VisualStudio.Interop.dll

Package:

Microsoft.VisualStudio.Interop v17.9.37000

Passes information about the existing packages to the one being added.

public:
 int GetInstanceOfExistingTypeForNewFramework(Microsoft::VisualStudio::OLE::Interop::IDataObject ^ pExistingItem, System::String ^ szNewTFM, Microsoft::VisualStudio::Shell::Interop::IVsAddToolboxItems ^ pAdder);

public:
 int GetInstanceOfExistingTypeForNewFramework(Microsoft::VisualStudio::OLE::Interop::IDataObject ^ pExistingItem, Platform::String ^ szNewTFM, Microsoft::VisualStudio::Shell::Interop::IVsAddToolboxItems ^ pAdder);

int GetInstanceOfExistingTypeForNewFramework(Microsoft::VisualStudio::OLE::Interop::IDataObject const & pExistingItem, std::wstring const & szNewTFM, Microsoft::VisualStudio::Shell::Interop::IVsAddToolboxItems const & pAdder);

public int GetInstanceOfExistingTypeForNewFramework (Microsoft.VisualStudio.OLE.Interop.IDataObject pExistingItem, string szNewTFM, Microsoft.VisualStudio.Shell.Interop.IVsAddToolboxItems pAdder);

abstract member GetInstanceOfExistingTypeForNewFramework : Microsoft.VisualStudio.OLE.Interop.IDataObject * string * Microsoft.VisualStudio.Shell.Interop.IVsAddToolboxItems -> int

Public Function GetInstanceOfExistingTypeForNewFramework (pExistingItem As IDataObject, szNewTFM As String, pAdder As IVsAddToolboxItems) As Integer

Parameters

pExistingItem

IDataObject

[in] The IDataObject with information about providers with the same ID.

szNewTFM

String

[in] The new TFM (target framework moniker).

pAdder

IVsAddToolboxItems

[in] The IVsAddToolboxItems used to add items to the tool box.

Returns

Int32

If the method succeeds, it returns S_OK. If it fails, it returns an error code.

Remarks

Consider a set of toolbox items that have the same type name, assembly name (ignoring version differences), and framework ID (a framework ID is the first component of a TFM, e.g.".NETFramework" in the TFM ".NETFramework,Version=v4.0,Profile=Client") according to their "TypeName", "AssemblyName", and "Frameworks" multitargeting string map fields, respectively (Although an item may support multiple frameworks, all the frameworks supported by an item must have the same ID.) For example, there might be:TypeName = System.Windows.Forms.Button AssemblyName = System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089 Frameworks = .NETFramework,Version=v2.0;.NETFramework,Version=v4.0and:TypeName = System.Windows.Forms.ButtonAssemblyName = System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089Frameworks = .NETFramework,Version=v4.0The toolbox understands that all the items in the set represent the "same" type. Let us call this set a "unique type set". For each unique type set, this method is called by the toolbox when the active designer belongs to a project targeting a version of that framework which is not already supported by an item in that unique type set and for which we have not called this method before. If any items in the unique type set support a framework with a lower version than the project's framework, pExistingItem will be the one of those with the highest assembly version; otherwise, if there is no existing item supporting a TFM with a lower version number than the new TFM, it is the item that supports the lowest-versioned TFM of the same ID. The package on which this method is called is the one identified by the multi-targeting metadata of pExistingItem. Packages should use IVsDataObjectStringMapManager to examine that metadata. This method implementation should use pAdder to do one of the following:

1. If there is no item of the same type as pExistingItem that supports the given TFM, do not call pAdder at all (but still return S_OK).

2. If the existing item should be used with the given TFM, use pAdder to add the existing item. The toolbox will recognize that you are not actually creating a new item and will simply update the framework to support of the existing item. In this case, the item info, item ID, tab name, and package GUID parameters to the methods of IVsAddToolboxItems will be ignored.

3. If the new framework contains a new implementation of this type, create a new toolbox item and use pAdder to add it. Setting the multi-targeting metadata on this object is optional. If the type name, assembly name, or item provider GUID are not set, they will be copied from the existing item. If the framework list is not set, it will be set to szNewTFM; if the framework list is set but does not include szNewTFM, szNewTFM will be added to it. When calling IVsAddToolboxItems methods to add new items, you may pass NULL or an empty string for the tab name to indicate that the item should be placed on the same tab as the existing item.