Export (0) Print
Expand All

GCHandle Structure

Provides a way to access a managed object from unmanaged memory.

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

[ComVisibleAttribute(true)]
public value class GCHandle

The GCHandle type exposes the following members.

  NameDescription
Public propertySupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsIsAllocatedGets a value indicating whether the handle is allocated.
Public propertySupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsTargetGets or sets the object this handle represents.
Top

  NameDescription
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsAddrOfPinnedObjectRetrieves the address of an object in a GCHandleType::Pinned handle.
Public methodStatic memberSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsAlloc(Object)Allocates a Normal handle for the specified object.
Public methodStatic memberSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsAlloc(Object, GCHandleType)Allocates a handle of the specified type for the specified object.
Public methodSupported by the XNA FrameworkEqualsDetermines whether the specified GCHandle object is equal to the current GCHandle object. (Overrides ValueType::Equals(Object).)

In XNA Framework, this member is overridden by Equals(Object).
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsFreeReleases a GCHandle.
Public methodStatic memberSupported by Portable Class LibrarySupported in .NET for Windows Store appsFromIntPtrReturns a new GCHandle object created from a handle to a managed object.
Public methodSupported by the XNA FrameworkGetHashCodeReturns an identifier for the current GCHandle object. (Overrides ValueType::GetHashCode().)

In XNA Framework, this member is overridden by GetHashCode().
Public methodSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsGetTypeGets the Type of the current instance. (Inherited from Object.)
Public methodStatic memberSupported by Portable Class LibrarySupported in .NET for Windows Store appsToIntPtrReturns the internal integer representation of a GCHandle object.
Public methodSupported by the XNA FrameworkToStringReturns the fully qualified type name of this instance. (Inherited from ValueType.)

In XNA Framework 3.0, this member is inherited from Object::ToString().
Top

  NameDescription
Public operatorStatic memberSupported by Portable Class LibrarySupported in .NET for Windows Store appsEqualityReturns a value indicating whether two GCHandle objects are equal.
Public operatorStatic memberSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsExplicit(GCHandle to IntPtr)A GCHandle is stored using an internal integer representation.
Public operatorStatic memberSupported by the XNA FrameworkSupported by Portable Class LibrarySupported in .NET for Windows Store appsExplicit(IntPtr to GCHandle)A GCHandle is stored using an internal integer representation.
Public operatorStatic memberSupported by Portable Class LibrarySupported in .NET for Windows Store appsInequalityReturns a value indicating whether two GCHandle objects are not equal.
Top

The GCHandle structure is used with the GCHandleType enumeration to create a handle corresponding to any managed object. This handle can be one of four types: Weak, WeakTrackResurrection, Normal, or Pinned. When the handle has been allocated, you can use it to prevent the managed object from being collected by the garbage collector when an unmanaged client holds the only reference. Without such a handle, the object can be collected by the garbage collector before completing its work on behalf of the unmanaged client.

You can also use GCHandle to create a pinned object that returns a memory address to prevent the garbage collector from moving the object in memory.

When the handle goes out of scope you must explicitly release it by calling the Free method; otherwise, memory leaks may occur. When you free a pinned handle, the associated object will be unpinned and will become eligible for garbage collection, if there are no other references to it.

The following example shows an App class that creates a handle to a managed object using the GCHandle.Alloc method, which prevents the managed object from being collected. A call to the EnumWindows method passes a delegate and a managed object (both declared as managed types, but not shown), and casts the handle to an IntPtr. The unmanaged function passes the type back to the caller as a parameter of the callback function.

No code example is currently available or this language may not be supported.

.NET Framework

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

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Portable Class Library

Supported in: Portable Class Library

.NET for Windows Store apps

Supported in: Windows 8

.NET for Windows Phone apps

Supported in: Windows Phone 8.1, Windows Phone Silverlight 8.1, Windows Phone Silverlight 8

Windows Phone 8.1, Windows Phone 8, Windows 8.1, Windows Server 2012 R2, Windows 8, Windows Server 2012, Windows 7, Windows Vista SP2, Windows Server 2008 (Server Core Role not supported), Windows Server 2008 R2 (Server Core Role supported with SP1 or later; Itanium not supported)

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Show:
© 2014 Microsoft