References the specified object, which makes it ineligible for garbage collection from the start of the current routine to the point where this method is called.
Assembly: mscorlib (in mscorlib.dll)
The purpose of the method is to ensure the existence of a reference to an object that is at risk of being prematurely reclaimed by the garbage collector. A common scenario where this might happen is when there are no references to the object in managed code or data, but the object is still in use in unmanaged code such as Win32 APIs, unmanaged DLLs, or methods using COM.
This method references the obj parameter, making that object ineligible for garbage collection from the start of the routine to the point, in execution order, where this method is called. Code this method at the end, not the beginning, of the range of instructions where obj must be available.
The method performs no operation and produces no side effects other than extending the lifetime of the object passed in as a parameter.
The following code example creates an object at the beginning of its Main method and does not refer to the object again until the end, when the method is called. The object persists for the 30-second duration of the Main method, despite calls to the Collect and WaitForPendingFinalizers methods.
Imports System Imports System.Threading Imports System.Runtime.InteropServices ' A simple class that exposes two static Win32 functions. ' One is a delegate type and the other is an enumerated type. Public Class MyWin32 ' Declare the SetConsoleCtrlHandler function as external ' and receiving a delegate. <DllImport("Kernel32")> _ Public Shared Function SetConsoleCtrlHandler(ByVal Handler As HandlerRoutine, _ ByVal Add As Boolean) As Boolean End Function ' A delegate type to be used as the handler routine ' for SetConsoleCtrlHandler. Delegate Function HandlerRoutine(ByVal CtrlType As CtrlTypes) As [Boolean] ' An enumerated type for the control messages ' sent to the handler routine. Public Enum CtrlTypes CTRL_C_EVENT = 0 CTRL_BREAK_EVENT CTRL_CLOSE_EVENT CTRL_LOGOFF_EVENT = 5 CTRL_SHUTDOWN_EVENT End Enum End Class Public Class MyApp ' A private static handler function in the MyApp class. Shared Function Handler(ByVal CtrlType As MyWin32.CtrlTypes) As [Boolean] Dim message As [String] = "This message should never be seen!" ' A select case to handle the event type. Select Case CtrlType Case MyWin32.CtrlTypes.CTRL_C_EVENT message = "A CTRL_C_EVENT was raised by the user." Case MyWin32.CtrlTypes.CTRL_BREAK_EVENT message = "A CTRL_BREAK_EVENT was raised by the user." Case MyWin32.CtrlTypes.CTRL_CLOSE_EVENT message = "A CTRL_CLOSE_EVENT was raised by the user." Case MyWin32.CtrlTypes.CTRL_LOGOFF_EVENT message = "A CTRL_LOGOFF_EVENT was raised by the user." Case MyWin32.CtrlTypes.CTRL_SHUTDOWN_EVENT message = "A CTRL_SHUTDOWN_EVENT was raised by the user." End Select ' Use interop to display a message for the type of event. Console.WriteLine(message) Return True End Function Public Shared Sub Main() ' Use interop to set a console control handler. Dim hr As New MyWin32.HandlerRoutine(AddressOf Handler) MyWin32.SetConsoleCtrlHandler(hr, True) ' Give the user some time to raise a few events. Console.WriteLine("Waiting 30 seconds for console ctrl events...") ' The object hr is not referred to again. ' The garbage collector can detect that the object has no ' more managed references and might clean it up here while ' the unmanaged SetConsoleCtrlHandler method is still using it. ' Force a garbage collection to demonstrate how the hr ' object will be handled. GC.Collect() GC.WaitForPendingFinalizers() GC.Collect() Thread.Sleep(30000) ' Display a message to the console when the unmanaged method ' has finished its work. Console.WriteLine("Finished!") ' Call GC.KeepAlive(hr) at this point to maintain a reference to hr. ' This will prevent the garbage collector from collecting the ' object during the execution of the SetConsoleCtrlHandler method. GC.KeepAlive(hr) Console.Read() End Sub End Class
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, Xbox 360, Zune
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.