Marshal.ReleaseComObject(Object) Méthode
Définition
Important
Certaines informations portent sur la préversion du produit qui est susceptible d’être en grande partie modifiée avant sa publication. Microsoft exclut toute garantie, expresse ou implicite, concernant les informations fournies ici.
Décrémente le décompte de références du wrapper RCW (Runtime Callable Wrapper) associé à l’objet COM indiqué.
public:
static int ReleaseComObject(System::Object ^ o);[System.Security.SecurityCritical]
public static int ReleaseComObject (object o);[System.Runtime.Versioning.SupportedOSPlatform("windows")]
public static int ReleaseComObject (object o);public static int ReleaseComObject (object o);[<System.Security.SecurityCritical>]
static member ReleaseComObject : obj -> int[<System.Runtime.Versioning.SupportedOSPlatform("windows")>]
static member ReleaseComObject : obj -> intstatic member ReleaseComObject : obj -> intPublic Shared Function ReleaseComObject (o As Object) As IntegerParamètres
- o
- Object
Objet COM à libérer.
Retours
Nouvelle valeur du décompte de références du wrapper RCW (Runtime Callable Wrapper) associé à o. Cette valeur est généralement zéro puisque le wrapper RCW (Runtime Callable Wrapper) ne conserve qu'une seule référence à l'objet COM inclus dans un wrapper indépendamment du nombre de clients managés qui l'appellent.
- Attributs
Exceptions
o n'est pas un objet COM valide.
o a la valeur null.
Remarques
Cette méthode est utilisée pour contrôler explicitement la durée de vie d’un objet COM utilisé à partir du code managé. Vous devez utiliser cette méthode pour libérer l’objet COM sous-jacent qui contient des références aux ressources en temps opportun ou lorsque les objets doivent être libérés dans un ordre spécifique.
Chaque fois qu’un pointeur d’interface COM entre dans le Common Language Runtime (CLR), il est encapsulé dans une instance RCW.
RcW a un nombre de références incrémenté chaque fois qu’un pointeur d’interface COM est mappé à celui-ci. La ReleaseComObject méthode décrémente le nombre de références d’un RCW. Lorsque le nombre de références atteint zéro, le runtime libère toutes ses références sur l’objet COM non managé et lève une System.NullReferenceException valeur si vous tentez d’utiliser l’objet plus loin. Si la même interface COM est passée plusieurs fois du code non managé au code managé, le nombre de références sur le wrapper est incrémenté chaque fois et l’appel ReleaseComObject retourne le nombre de références restantes.
Cette méthode vous permet de forcer une version de nombre de références RCW afin qu’elle se produise précisément lorsque vous le souhaitez. Toutefois, une utilisation incorrecte peut entraîner l’échec de ReleaseComObject votre application ou provoquer une violation d’accès.
Envisagez un scénario dans lequel le code managé dans un domaine d’application tient sur un RCW qui représente un composant COM. Si vous appelez la ReleaseComObject méthode sur RCW, le code managé ne pourra pas accéder à RCW et déclenchera une InvalidComObjectException exception.
Une erreur plus grave peut se produire si un appel au RCW s’exécute lorsque le RCW est libéré. Dans ce cas, il est possible que le thread qui effectue l’appel entraîne une violation d’accès. Toutefois, la mémoire du processus peut devenir endommagée et le processus peut continuer à s’exécuter jusqu’à ce qu’il échoue pour des raisons très difficiles à déboguer.
Ce risque est composé lorsque le composant COM utilisé est un singleton, pour la raison suivante : le CLR active les composants COM en appelant la fonction COM CoCreateInstance , qui retourne le même pointeur d’interface chaque fois qu’il est appelé pour les composants COM singleton. Par conséquent, des parties distinctes et indépendantes du code managé dans un domaine d’application peuvent utiliser le même RCW pour un composant COM singleton, et si l’une ou l’autre appelle la ReleaseComObject méthode sur le composant COM, l’autre sera rompue.
Par conséquent, utilisez le ReleaseComObject seul s’il est absolument nécessaire. Si vous souhaitez appeler cette méthode pour vous assurer qu’un composant COM est publié à un moment déterminé, envisagez plutôt d’utiliser la FinalReleaseComObject méthode. FinalReleaseComObject libère le composant COM sous-jacent, quel que soit le nombre de fois qu’il a entré à nouveau le CLR. Le nombre de références internes du RCW est incrémenté d’un chaque fois que le composant COM entre à nouveau dans le CLR. Par conséquent, vous pouvez appeler la ReleaseComObject méthode dans une boucle jusqu’à ce que la valeur retournée soit égale à zéro. Cela permet d’obtenir le même résultat que la FinalReleaseComObject méthode.