À l’aide d’assemblys PIA Visual StudioUsing Visual Studio Interop Assemblies

Les assemblys PIA Visual Studio autorisent les applications managées accéder aux interfaces COM qui fournissent une extensibilité de Visual Studio.Visual Studio interop assemblies allow managed applications to access the COM interfaces that provide Visual Studio extensibility. Il existe certaines différences entre les interfaces COM droites et à leurs versions interop.There are some differences between straight COM interfaces and their interop versions. Par exemple, les valeurs HRESULT sont généralement représentées sous forme de valeurs de type int et doivent être traités de la même façon en tant qu’exceptions, et paramètres (en particulier les paramètres de sortie) sont traités différemment.For example, HRESULTs are generally represented as int values and need to be handled in the same way as exceptions, and parameters (especially out parameters) are treated differently.

Gestion des HRESULT retournés au code managé à partir de COMHandling HRESULTs Returned to Managed Code from COM

Quand vous appelez une interface COM à partir de code managé, examinez la valeur HRESULT et levez une exception si nécessaire.When you call a COM interface from managed code, examine the HRESULT value and throw an exception if required. Le ErrorHandler classe contient la ThrowOnFailure méthode qui lève une exception COM, selon la valeur de la valeur HRESULT qui lui sont passés.The ErrorHandler class contains the ThrowOnFailure method, which throws a COM exception, depending on the value of the HRESULT passed to it.

Par défaut, ThrowOnFailure lève une exception lorsqu’il est passé à une valeur HRESULT qui a une valeur inférieure à zéro.By default, ThrowOnFailure throws an exception whenever it is passed an HRESULT that has a value less than zero. Dans le cas où ces valeurs HRESULT est des valeurs acceptables et aucune exception ne doit être levée, les valeurs des HRESULT supplémentaires doivent être passées à ThrowOnFailure une fois que les valeurs sont testées.In cases where such HRESULTs are acceptable values and no exception should be thrown, the values of additional HRESULTS should be passed to ThrowOnFailure after the values are tested. Si la valeur HRESULT testée correspond à une valeur HRESULT explicitement passée à ThrowOnFailure, aucune exception n’est levée.If the HRESULT being tested matches any HRESULT values explicitly passed to ThrowOnFailure, no exception is thrown.

Note

Le VSConstants classe contient des constantes pour les valeurs HRESULT courantes, par exemple, S_OK et E_NOTIMPL, et Visual StudioVisual Studio HRESULT, par exemple, VS_E_INCOMPATIBLEDOCDATA et VS_E_UNSUPPORTEDFORMAT.The VSConstants class contains constants for common HRESULTS, for example, S_OK and E_NOTIMPL, and Visual StudioVisual Studio HRESULTS, for example, VS_E_INCOMPATIBLEDOCDATA and VS_E_UNSUPPORTEDFORMAT. VSConstants fournit également la Succeeded et Failed méthodes qui correspondent aux macros SUCCEEDED et FAILED dans COM.VSConstants also provides the Succeeded and Failed methods, which correspond to the SUCCEEDED and FAILED macros in COM.

Par exemple, considérez l’appel de fonction suivant, dans lequel E_NOTIMPL est une valeur de retournée acceptable, mais les autres valeurs HRESULT inférieures à zéro représente une erreur.For example, consider the following function call, in which E_NOTIMPL is an acceptable return value but any other HRESULT less than zero represents an error.

Dim hr As Integer = MyInterface.MyFunction(cmdID)
ErrorHandler.ThrowOnFailure(hr, VSConstants.E_NOTIMPL)
int hr = MyInterface.MyFunction(cmdID);
ErrorHandler.ThrowOnFailure(hr, VSConstants.E_NOTIMPL);

S’il existe plusieurs valeurs de retour acceptables, les autres valeurs HRESULT peuvent être simplement ajoutées à la liste dans l’appel à ThrowOnFailure.If there are more than one acceptable return values, additional HRESULT values can just be appended to the list in the call to ThrowOnFailure.

Dim hr As Integer = MyInterface.MyFunction(cmdID)
ErrorHandler.ThrowOnFailure(hr, VSConstants.E_NOINTERFACE, VSConstants.E_NOTIMPL)
int hr = MyInterface.MyFunction(cmdID);
ErrorHandler.ThrowOnFailure(hr, VSConstants.E_NOINTERFACE, VSConstants.E_NOTIMPL);

Retour de valeurs HRESULT à COM à partir de code managéReturning HRESULTS to COM from Managed Code

Si aucune exception ne se produit, le code managé retourne S_OK à la fonction COM qui l’a appelée.If no exception occurs, managed code returns S_OK to the COM function that called it. COM interop prend en charge les exceptions courantes qui sont fortement typées dans du code managé.COM interop supports common exceptions that are strongly typed in managed code. Par exemple, une méthode qui reçoit un inacceptable null argument lève une ArgumentNullException.For example, a method that receives an unacceptable null argument throws an ArgumentNullException.

Si vous ne savez pas quelle exception lever, mais que vous connaissez la valeur HRESULT que vous souhaitez retourner à COM, vous pouvez utiliser la ThrowExceptionForHR méthode pour lever une exception appropriée.If you are not certain which exception to throw, but you know the HRESULT you want to return to COM, you can use the ThrowExceptionForHR method to throw an appropriate exception. Cela fonctionne même avec une erreur non standard, par exemple, VS_E_INCOMPATIBLEDOCDATA.This works even with a nonstandard error, for example, VS_E_INCOMPATIBLEDOCDATA. ThrowExceptionForHR essaie de mapper des HRESULT lui sont transmises à une exception fortement typée.ThrowExceptionForHR attempts to map the HRESULT passed to it to a strongly typed exception. Si ce n’est pas possible, une exception COM générique est levée.If it cannot, it throws a generic COM exception instead. Le résultat final est que la valeur HRESULT que vous passez à ThrowExceptionForHR à partir du code managé est retournée à la fonction COM qui l’a appelée.The ultimate result is that the HRESULT you pass to ThrowExceptionForHR from managed code is returned to the COM function that called it.

Note

Les exceptions nuisent aux performances et ont vocation à indiquer des conditions anormales pour le programme.Exceptions compromise performance and are intended to indicate abnormal program conditions. Les conditions qui se produisent souvent doivent être gérées instantanément, au lieu de lever une exception.Conditions that occur often should be handled inline, instead of a thrown exception.

Paramètres de IUnknown passés en tant que Type void IUnknown parameters passed as Type void

Rechercher des [paramètres qui sont définis en tant que type out] void ** dans le modèle COM interface, mais qui sont définis comme [``iid_is``] dans le Visual StudioVisual Studio prototype de méthode d’assembly d’interopérabilité.Look for [out] parameters that are defined as type void ** in the COM interface, but that are defined as [``iid_is``] in the Visual StudioVisual Studio interop assembly method prototype.

Parfois, une interface COM génère une IUnknown objet et l’interface COM puis passe en tant que type void **.Sometimes, a COM interface generates an IUnknown object, and the COM interface then passes it as type void **. Ces interfaces sont particulièrement importants, car si la variable est définie en tant que [out] dans le fichier IDL, puis le IUnknown objet est décompte avec la AddRef (méthode).These interfaces are especially important because if the variable is defined as [out] in the IDL, then the IUnknown object is reference-counted with the AddRef method. Une fuite de mémoire se produit si l’objet n’est pas gérée correctement.A memory leak occurs if the object is not handled correctly.

Note

Un IUnknown objet créé par l’interface COM et retournée dans une variable [out] entraîne une fuite de mémoire si elle n’est pas explicitement libéré.An IUnknown object created by the COM interface and returned in an [out] variable causes a memory leak if it is not explicitly released.

Les méthodes managées qui gèrent ces objets à considérer IntPtr comme un pointeur vers un IUnknown et appelez le GetObjectForIUnknown méthode pour obtenir l’objet.Managed methods that handle such objects should treat IntPtr as a pointer to an IUnknown object, and call the GetObjectForIUnknown method to obtain the object. L’appelant doit alors convertir la valeur de retour pour tout type est approprié.The caller should then cast the return value to whatever type is appropriate. Lorsque l’objet n’est plus nécessaire, appelez Release pour le libérer.When the object is no longer needed, call Release to release it.

Voici un exemple de l’appel de la QueryViewInterface (méthode) et la gestion de la IUnknown correctement l’objet :Following is an example of calling the QueryViewInterface method and handling the IUnknown object correctly:

MyClass myclass;  
Object object;  
IntPtr pObj;  
Guid iid = Typeof(MyClass).Guid;  
int hr = windowFrame.QueryViewInterface(ref iid, out pObj);     
if (NativeMethods.Succeeded(hr))   
{  
    try   
    {  
        object = Marshal.GetObjectForIUnknown(pObj);  
        myclass = object;  
    }  
    finally   
    {  
        Marshal.Release(pObj);  
    }  
}  
else   
{  
    // error calling QueryViewInterface  
}  

Note

Les méthodes suivantes sont connues pour passer IUnknown des pointeurs d’objet en tant que type IntPtr.The following methods are known to pass IUnknown object pointers as type IntPtr. Les gérer comme décrit dans cette section.Handle them as described in this section.

Facultatif de [paramètres out]Optional [out] Parameters

Rechercher des paramètres qui sont définis en tant que [out] type de données (int, object, et ainsi de suite) dans le modèle COM interface, mais qui sont définis en tant que tableaux du même type de données dans le Visual StudioVisual Studio prototype de méthode d’assembly d’interopérabilité.Look for parameters that are defined as an [out] data type (int, object, and so on) in the COM interface, but that are defined as arrays of the same data type in the Visual StudioVisual Studio interop assembly method prototype.

Interfaces de certains COM, tels que GetCfgs, traiter les [paramètres comme étant facultatifs out].Some COM interfaces, such as GetCfgs, treat [out] parameters as optional. Si un objet n’est pas requis, le retour de ces interfaces COM un null pointeur en tant que la valeur de ce paramètre au lieu de créer l’objet [out].If an object is not required, these COM interfaces return a null pointer as the value of that parameter instead of creating the [out] object. Ceci est normal.This is by design. Ces interfaces, null pointeurs sont supposées en tant que partie du comportement correct du VSPackage, et aucune erreur n’est retournée.For these interfaces, null pointers are assumed as part of the correct behavior of the VSPackage, and no error is returned.

Étant donné que le CLR n’autorise pas la valeur d’un paramètre [out] d’être null, le comportement de conception de ces interfaces n’est pas directement disponible dans le code managé.Because the CLR does not allow the value of an [out] parameter to be null, part of the designed behavior of these interfaces is not directly available within managed code. Le Visual StudioVisual Studio des méthodes d’assembly d’interopérabilité pour les interfaces affectés contourner le problème en définissant les paramètres pertinents en tant que tableaux, car le CLR permet la transmission de null tableaux.The Visual StudioVisual Studio interop assembly methods for affected interfaces work around the issue by defining the relevant parameters as arrays because the CLR allows the passing of null arrays.

Les implémentations managées de ces méthodes doivent placer un null tableau dans le paramètre quand il n’y a rien à retourner.Managed implementations of these methods should put a null array into the parameter when there is nothing to be returned. Sinon, créez un tableau d’un élément du type approprié et placer la valeur de retour dans le tableau.Otherwise, create a one-element array of the correct type and put the return value in the array.

Méthodes qui reçoivent des informations sur les interfaces avec [out] facultatif managées paramètres reçoivent le paramètre sous forme de tableau.Managed methods that receive information from interfaces with optional [out] parameters receive the parameter as an array. Il suffit d’examiner la valeur du premier élément du tableau.Just examine the value of the first element of the array. Si elle n’est pas null, traite le premier élément comme s’il était le paramètre d’origine.If it is not null, treat the first element as if it were the original parameter.

Constantes de passage de paramètres de pointeurPassing Constants in Pointer Parameters

Rechercher des paramètres qui sont définis comme [in] pointeurs dans l’interface COM, mais qui sont définies comme un IntPtr de type dans le Visual StudioVisual Studio prototype de méthode d’assembly d’interopérabilité.Look for parameters that are defined as [in] pointers in the COM interface, but that are defined as a IntPtr type in the Visual StudioVisual Studio interop assembly method prototype.

Un problème similaire se produit lorsqu’une interface COM transmet une valeur spéciale, comme 0, -1 ou -2, au lieu d’un pointeur d’objet.A similar issue occurs when a COM interface passes a special value, such as 0, -1, or -2, instead of an object pointer. Contrairement à Visual C++Visual C++, le CLR n’autorise pas les constantes être considérés comme des objets.Unlike Visual C++Visual C++, the CLR does not allow constants to be cast as objects. Au lieu de cela, le Visual StudioVisual Studio assembly PIA définit le paramètre comme un IntPtr type.Instead, the Visual StudioVisual Studio interop assembly defines the parameter as a IntPtr type.

Les implémentations managées de ces méthodes doivent tirer parti du fait que la IntPtr classe possède à la fois int et void * constructeurs pour créer un IntPtr à partir d’un objet ou une constante entière, le cas échéant.Managed implementations of these methods should take advantage of the fact that the IntPtr class has both int and void * constructors to create an IntPtr from either an object or an integer constant, as appropriate.

Géré des méthodes qui reçoivent IntPtr les paramètres de ce type doivent utiliser le IntPtr pour traiter les résultats des opérateurs de conversion de type.Managed methods that receive IntPtr parameters of this type should use the IntPtr type conversion operators to handle the results. Tout d’abord convertir le IntPtr à int et testez-le par rapport à des constantes entières pertinentes.First convert the IntPtr to int and test it against relevant integer constants. Si aucune valeur ne correspondre, convertissez-le en un objet du type requis et continuer.If no values match, convert it to an object of the required type and continue.

Pour obtenir des exemples, consultez OpenStandardEditor et OpenSpecificEditor.For examples of this, see OpenStandardEditor and OpenSpecificEditor.

OLE retourner valeurs passées comme [paramètres out]OLE Return Values Passed as [out] Parameters

Recherchez les méthodes qui ont un retval valeur de retour dans l’interface COM, mais qui ont un int valeur de retour et un autre [paramètre de tableau dans out] la Visual StudioVisual Studio prototype de méthode d’assembly d’interopérabilité.Look for methods that have a retval return value in the COM interface, but that have an int return value and an additional [out] array parameter in the Visual StudioVisual Studio interop assembly method prototype. Il doit être clair que ces méthodes requièrent un traitement spécial, car le Visual StudioVisual Studio prototypes de méthode d’assembly d’interopérabilité ont un paramètre de plus que les méthodes d’interface COM.It should be clear that these methods require special handling because the Visual StudioVisual Studio interop assembly method prototypes have one more parameter than the COM interface methods.

Plusieurs interfaces COM qui traitent de l’activité OLE envoyer des informations sur l’état de l’OLE au programme appelant stocké dans la retval valeur de retour de l’interface.Many COM interfaces that deal with OLE activity send information about OLE status back to the calling program stored in the retval return value of the interface. Au lieu d’utiliser une valeur de retour correspondants Visual StudioVisual Studio méthodes de l’assembly PIA envoient les informations au programme appelant stocké dans un paramètre [out] paramètre de tableau.Instead of using a return value, the corresponding Visual StudioVisual Studio interop assembly methods send the information back to the calling program stored in an [out] array parameter.

Les implémentations managées de ces méthodes doivent créer un seul élément tableau du même type que le paramètre [out] et le placer dans le paramètre.Managed implementations of these methods should create a single-element array of the same type as the [out] parameter and put it in the parameter. La valeur de l’élément de tableau doit être le même que le modèle COM approprié retval.The value of the array element should be the same as the appropriate COM retval.

Les méthodes managées qui appellent les interfaces de ce type doivent extraire le premier élément hors du tableau [out].Managed methods that call interfaces of this type should pull the first element out of the [out] array. Cet élément peut être traité comme s’il s’agissait d’un retval valeur de retour à partir de l’interface COM correspondante.This element can be treated as if it were a retval return value from the corresponding COM interface.

Voir aussiSee Also

Interopération avec du code non managéInteroperating with Unmanaged Code