GC.SuppressFinalize(Object) 方法

定義

要求 Common Language Runtime 不要為指定之物件呼叫完成項。

public static void SuppressFinalize (object obj);

參數

obj
Object

完成項不得執行的物件。

例外狀況

objnull

範例

下列範例示範如何使用 SuppressFinalize 資源類別中的 方法,以防止呼叫多餘的垃圾收集。 此範例會使用 dispose 模式 來釋放 managed 資源 (也就是實 IDisposable 作) 和 Unmanaged 資源的物件。

using System;
using System.ComponentModel;
using System.Runtime.InteropServices;

public class ConsoleMonitor : IDisposable
{
   const int STD_INPUT_HANDLE = -10;
   const int STD_OUTPUT_HANDLE = -11;
   const int STD_ERROR_HANDLE = -12;

   [DllImport("kernel32.dll", SetLastError = true)]
   static extern IntPtr GetStdHandle(int nStdHandle);

   [DllImport("kernel32.dll", SetLastError = true)]
   static extern bool WriteConsole(IntPtr hConsoleOutput, string lpBuffer,
          uint nNumberOfCharsToWrite, out uint lpNumberOfCharsWritten,
          IntPtr lpReserved);

   [DllImport("kernel32.dll", SetLastError = true)]
   static extern bool CloseHandle(IntPtr handle);

   private bool disposed = false;
   private IntPtr handle;
   private Component component;

   public ConsoleMonitor()
   {
      handle = GetStdHandle(STD_OUTPUT_HANDLE);
      if (handle == IntPtr.Zero)
         throw new InvalidOperationException("A console handle is not available.");

      component = new Component();

      string output = "The ConsoleMonitor class constructor.\n";
      uint written = 0;
      WriteConsole(handle, output, (uint) output.Length, out written, IntPtr.Zero);
   }

   // The finalizer represents Object.Finalize override.
   ~ConsoleMonitor()
   {
      if (handle != IntPtr.Zero) {
         string output = "The ConsoleMonitor finalizer.\n";
         uint written = 0;
         WriteConsole(handle, output, (uint) output.Length, out written, IntPtr.Zero);
      }
      else {
         Console.Error.WriteLine("Object finalization.");
      }
      Dispose(disposing: false);
   }

   public void Write()
   {
      string output = "The Write method.\n";
      uint written = 0;
      WriteConsole(handle, output, (uint) output.Length, out written, IntPtr.Zero);
   }

   public void Dispose()
   {
      string output = "The Dispose method.\n";
      uint written = 0;
      WriteConsole(handle, output, (uint) output.Length, out written, IntPtr.Zero);

      Dispose(disposing: true);
      GC.SuppressFinalize(this);
   }

   private void Dispose(bool disposing)
   {
      string output = String.Format("The Dispose({0}) method.\n", disposing);
      uint written = 0;
      WriteConsole(handle, output, (uint) output.Length, out written, IntPtr.Zero);

      // Execute if resources have not already been disposed.
      if (!disposed) {
         // If the call is from Dispose, free managed resources.
         if (disposing) {
            Console.Error.WriteLine("Disposing of managed resources.");
            if (component != null)
               component.Dispose();
         }
         // Free unmanaged resources.
         output = "Disposing of unmanaged resources.";
         WriteConsole(handle, output, (uint) output.Length, out written, IntPtr.Zero);

         if (handle != IntPtr.Zero) {
            if (!CloseHandle(handle))
               Console.Error.WriteLine("Handle cannot be closed.");
         }
      }
      disposed = true;
   }
}

public class Example
{
   public static void Main()
   {
      Console.WriteLine("ConsoleMonitor instance....");
      ConsoleMonitor monitor = new ConsoleMonitor();
      monitor.Write();
      monitor.Dispose();
   }
}
// If the monitor.Dispose method is not called, the example displays the following output:
//       ConsoleMonitor instance....
//       The ConsoleMonitor class constructor.
//       The Write method.
//       The ConsoleMonitor finalizer.
//       The Dispose(False) method.
//       Disposing of unmanaged resources.
//
// If the monitor.Dispose method is called, the example displays the following output:
//       ConsoleMonitor instance....
//       The ConsoleMonitor class constructor.
//       The Write method.
//       The Dispose method.
//       The Dispose(True) method.
//       Disposing of managed resources.
//       Disposing of unmanaged resources.

備註

這個方法會在 的物件標頭 obj 中設定位,執行時間會在呼叫完成項時檢查。 方法所 Object.Finalize 代表的完成項是用來在垃圾收集物件之前釋放 Unmanaged 資源。 如果沒有 obj 完成項,或 GC 已經發出完成項執行緒執行完成項的信號,則方法的 SuppressFinalize 呼叫不會有任何作用。

實作 IDisposable 介面的物件可以從物件的 IDisposable.Dispose 實作呼叫這個方法,以防止垃圾收集行程在不需要它的物件上呼叫 Object.Finalize 。 一般而言,這是為了防止完成項釋放已由 IDisposable.Dispose 實作釋放的 Unmanaged 資源。

適用於

產品 版本
.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.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.0, 2.1
UWP 10.0

另請參閱