System.Runtime.InteropServices.HandleRef Structure

Wraps a managed object holding a handle to a resource that is passed to unmanaged code using platform invoke.

See Also: HandleRef Members


public struct HandleRef


If you use platform invoke to call a managed object, and the object is not referenced elsewhere after the platform invoke call, it is possible for the garbage collector to finalize the managed object. This action releases the resource and invalidates the handle, causing the platform invoke call to fail. Wrapping a handle with System.Runtime.InteropServices.HandleRef guarantees that the managed object is not garbage collected until the platform invoke call completes. For a description of platform invoke services, see [<topic://cpconconsumingunmanageddllfunctions>].

The System.Runtime.InteropServices.HandleRef value type, like System.Runtime.InteropServices.GCHandle, is a special type recognized by the interop marshaler. A normal, nonpinned System.Runtime.InteropServices.GCHandle also prevents untimely garbage collection, yet System.Runtime.InteropServices.HandleRef provides better performance. Although using System.Runtime.InteropServices.HandleRef to keep an object alive for the duration of a platform invoke call is preferred, you can also use the GC.KeepAlive(object) method for the same purpose.

The System.Runtime.InteropServices.HandleRef constructor takes two parameters: an object representing the wrapper, and an IntPtr representing the unmanaged handle. The interop marshaler passes only the handle to unmanaged code, and guarantees that the wrapper (passed as the first parameter to the constructor of the HandleRef) remains alive for the duration of the call.


Namespace: System.Runtime.InteropServices
Assembly: mscorlib (in mscorlib.dll)
Assembly Versions: 1.0.5000.0,,