GCHandle.Alloc Method

Definition

Allocates a handle for the specified object.

Overloads

Alloc(Object)

Allocates a Normal handle for the specified object.

Alloc(Object, GCHandleType)

Allocates a handle of the specified type for the specified object.

Alloc(Object)

Source:
GCHandle.cs
Source:
GCHandle.cs
Source:
GCHandle.cs

Allocates a Normal handle for the specified object.

[System.Security.SecurityCritical]
public static System.Runtime.InteropServices.GCHandle Alloc (object value);
public static System.Runtime.InteropServices.GCHandle Alloc (object? value);
public static System.Runtime.InteropServices.GCHandle Alloc (object value);

Parameters

value
Object

The object that uses the GCHandle.

Returns

A new GCHandle that protects the object from garbage collection. This GCHandle must be released with Free() when it is no longer needed.

Attributes

Examples

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.

using System;
using System.IO;
using System.Threading;
using System.Windows.Forms;
using System.Runtime.InteropServices;

public delegate bool CallBack(int handle, IntPtr param);

internal static class NativeMethods
{
    // passing managed object as LPARAM
    // BOOL EnumWindows(WNDENUMPROC lpEnumFunc, LPARAM lParam);

    [DllImport("user32.dll")]
    internal static extern bool EnumWindows(CallBack cb, IntPtr param);
}

public class App
{
    public static void Main()
    {
        Run();
    }

    public static void Run()
    {
        TextWriter tw = Console.Out;
        GCHandle gch = GCHandle.Alloc(tw);

        CallBack cewp = new CallBack(CaptureEnumWindowsProc);

        // platform invoke will prevent delegate to be garbage collected
        // before call ends

        NativeMethods.EnumWindows(cewp, GCHandle.ToIntPtr(gch));
        gch.Free();
    }

    private static bool CaptureEnumWindowsProc(int handle, IntPtr param)
    {
        GCHandle gch = GCHandle.FromIntPtr(param);
        TextWriter tw = (TextWriter)gch.Target;
        tw.WriteLine(handle);
        return true;
    }
}

Remarks

Normal handles are opaque, which means that you cannot resolve the address of the object it contains through the handle.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

Alloc(Object, GCHandleType)

Source:
GCHandle.cs
Source:
GCHandle.cs
Source:
GCHandle.cs

Allocates a handle of the specified type for the specified object.

[System.Security.SecurityCritical]
public static System.Runtime.InteropServices.GCHandle Alloc (object value, System.Runtime.InteropServices.GCHandleType type);
public static System.Runtime.InteropServices.GCHandle Alloc (object? value, System.Runtime.InteropServices.GCHandleType type);
public static System.Runtime.InteropServices.GCHandle Alloc (object value, System.Runtime.InteropServices.GCHandleType type);

Parameters

value
Object

The object that uses the GCHandle.

type
GCHandleType

One of the GCHandleType values, indicating the type of GCHandle to create.

Returns

A new GCHandle of the specified type. This GCHandle must be released with Free() when it is no longer needed.

Attributes

Exceptions

An instance with nonprimitive (non-blittable) members cannot be pinned.

See also

Applies to

.NET 9 and other versions
Product Versions
.NET Core 1.0, Core 1.1, Core 2.0, Core 2.1, Core 2.2, Core 3.0, Core 3.1, 5, 6, 7, 8, 9
.NET Framework 1.1, 2.0, 3.0, 3.5, 4.0, 4.5, 4.5.1, 4.5.2, 4.6, 4.6.1, 4.6.2, 4.7, 4.7.1, 4.7.2, 4.8, 4.8.1
.NET Standard 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0