Marshal Methods


.NET Framework Class Library
Marshal..::.ReleaseComObject Method

Decrements the reference count of the supplied runtime callable wrapper.

Namespace:  System.Runtime.InteropServices
Assembly:  mscorlib (in mscorlib.dll)
Syntax
Visual Basic (Declaration) 
<SecurityPermissionAttribute(SecurityAction.LinkDemand, Flags := SecurityPermissionFlag.UnmanagedCode)> _
Public Shared Function ReleaseComObject ( _
    o As Object _
) As Integer
Visual Basic (Usage) 
Dim o As Object
Dim returnValue As Integer

returnValue = Marshal.ReleaseComObject(o)
C# 
[SecurityPermissionAttribute(SecurityAction.LinkDemand, Flags = SecurityPermissionFlag.UnmanagedCode)]
public static int ReleaseComObject(
    Object o
)
Visual C++ 
[SecurityPermissionAttribute(SecurityAction::LinkDemand, Flags = SecurityPermissionFlag::UnmanagedCode)]
public:
static int ReleaseComObject(
    Object^ o
)
JScript 
public static function ReleaseComObject(
    o : Object
) : int

Parameters

o
Type: System..::.Object
The COM object to release.

Return Value

Type: System..::.Int32
The new value of the reference count of the runtime callable wrapper associated with o. This value is typically zero since the runtime callable wrapper keeps just one reference to the wrapped COM object regardless of the number of managed clients calling it.
Exceptions
ExceptionCondition
ArgumentException

o is not a valid COM object.

-or-

o is nullNothingnullptra null reference (Nothing in Visual Basic).
Remarks

Every time a COM interface pointer enters the common language runtime, it is wrapped in a runtime callable wrapper. If you are unfamiliar with the features of this wrapper, see Runtime Callable Wrapper.

This method is used to explicitly control the lifetime of a COM object used from managed code. You should use this method to free the underlying COM object that holds references to resources in a timely manner or when objects must be freed in a specific order.

The runtime callable wrapper has a reference count that is incremented every time a COM interface pointer is mapped to it. The ReleaseComObject method decrements the reference count of a runtime callable wrapper. When the reference count reached zero, the runtime releases all its references on the unmanaged COM object, and throws a System..::.NullReferenceException if you attempt to use the object further. If the same COM interface is passed more than once from unmanaged to managed code, the reference count on the wrapper is incremented every time and calling ReleaseComObject returns the number of remaining references.

NoteNote:

To ensure that the runtime callable wrapper and the original COM object are released, construct a loop from which you call this method until the returned reference count reaches zero.

NoteNote:

This method uses SecurityAction..::.LinkDemand to prevent it from being called from untrusted code; only the immediate caller is required to have SecurityPermissionAttribute..::.UnmanagedCode permission. If your code can be called from partially trusted code, do not pass user input to Marshal class methods without validation. For important limitations on using the LinkDemand member, see Demand vs. LinkDemand.
.NET Framework Security
Platforms

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98, Windows CE, Windows Mobile for Smartphone, Windows Mobile for Pocket PC

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Version Information

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0

.NET Compact Framework

Supported in: 3.5, 2.0
See Also

Reference

Marshal Class
Marshal Members
System.Runtime.InteropServices Namespace
FinalReleaseComObject
NullReferenceException
Tags :


Community Content

MarkLindell
The return value documentation may be interpreted incorrectly.
Be careful when checking the return value. The above documentation seems to imply that it will represent the number of references or 0. But I have found the value will be less than 0 under certain circumstances. This is important to know if you are using a loop that your condition for exiting is <=0 and not == 0 which would cause an endless loop.
Tags : contentbug

Felix Collins
Why loop and release?
As I understand things from the documentation. In a single .net process there will be one RCW per com object. The RCW only addRefs the COM object once so the reference count will only get to one unless the COM object is accessed by multiple processes. In the case of multiple processes if one looped and released until the COM object was destroyed, that would leave the other processes with hanging RCWs pointing to non existant COM objects. So why would one loop?

On another note. The documentation for FinalReleaseComObject states "The FinalReleaseComObject method releases the managed reference to a COM object. Calling this method is equivalent to calling the ReleaseComObject method in a loop until it returns 0." So why is there still a note in this page about looping? Most confusing.

In any case a realistic example of a case where looping or calling FinalReleaseComObject might be justified would be useful.

Also an example of the correct way to ensure the immediate destruction/freeing of a COM object used by a single .net process but with multiple Interface pointers would be a useful clarification.
Tags :

Page view tracker