Add comprehensive COM object cleanup documentation and examples for Excel Interop

docs/csharp/advanced-topics/interop/snippets/OfficeInterop/program.cs

@@ -8,6 +8,8 @@
 
 using System;
 using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
 //<Snippet1>
 using Excel = Microsoft.Office.Interop.Excel;
 using Word = Microsoft.Office.Interop.Word;
@@ -48,39 +50,127 @@ static void Main(string[] args)
         //<Snippet4>
         static void DisplayInExcel(IEnumerable<Account> accounts)
         {
-            var excelApp = new Excel.Application();
-            // Make the object visible.
-            excelApp.Visible = true;
+            DisplayInExcelCore(accounts);
+        }
 
-            // Create a new, empty workbook and add it to the collection returned
-            // by property Workbooks. The new workbook becomes the active workbook.
-            // Add has an optional parameter for specifying a particular template.
-            // Because no argument is sent in this example, Add creates a new workbook.
-            excelApp.Workbooks.Add();
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        static void DisplayInExcelCore(IEnumerable<Account> accounts)
+        {
+            Excel.Application excelApp = null;
+            Excel.Workbook workbook = null;
+            Excel.Worksheet workSheet = null;
+
+            try
+            {
+                excelApp = new Excel.Application();
+                // Make the object visible.
+                excelApp.Visible = true;
 
-            // This example uses a single workSheet. The explicit type casting is
-            // removed in a later procedure.
-            Excel._Worksheet workSheet = (Excel.Worksheet)excelApp.ActiveSheet;
+                // Create a new, empty workbook and add it to the collection returned
+                // by property Workbooks. The new workbook becomes the active workbook.
+                // Add has an optional parameter for specifying a particular template.
+                // Because no argument is sent in this example, Add creates a new workbook.
+                workbook = excelApp.Workbooks.Add();
+
+                // This example uses a single workSheet. The explicit type casting is
+                // removed in a later procedure.
+                workSheet = (Excel.Worksheet)excelApp.ActiveSheet;
+
+                // Establish column headings in cells A1 and B1.
+                workSheet.Cells[1, "A"] = "ID Number";
+                workSheet.Cells[1, "B"] = "Current Balance";
+
+                var row = 1;
+                foreach (var acct in accounts)
+                {
+                    row++;
+                    workSheet.Cells[row, "A"] = acct.ID;
+                    workSheet.Cells[row, "B"] = acct.Balance;
+                }
+
+                workSheet.Columns[1].AutoFit();
+                workSheet.Columns[2].AutoFit();
+
+                // Put the spreadsheet contents on the clipboard.
+                workSheet.Range["A1:B3"].Copy();
+
+                // Save the workbook before closing
+                string fileName = System.IO.Path.Combine(
+                    Environment.GetFolderPath(Environment.SpecialFolder.Desktop), 
+                    "BankAccounts.xlsx");
+                workbook.SaveAs(fileName);
+            }
+            finally
+            {
+                // Clean up COM objects in reverse order of creation
+                if (workSheet != null)
+                {
+                    Marshal.FinalReleaseComObject(workSheet);
+                }
+                if (workbook != null)
+                {
+                    workbook.Close(true); // Save changes
+                    Marshal.FinalReleaseComObject(workbook);
+                }
+                if (excelApp != null)
+                {
+                    excelApp.DisplayAlerts = true;
+                    excelApp.Quit();
+                    Marshal.FinalReleaseComObject(excelApp);
+                }
+            }
         }
         //</Snippet4>
 
         //<Snippet9>
         static void CreateIconInWordDoc()
         {
-            var wordApp = new Word.Application();
-            wordApp.Visible = true;
-
-            // The Add method has four reference parameters, all of which are
-            // optional. Visual C# allows you to omit arguments for them if
-            // the default values are what you want.
-            wordApp.Documents.Add();
-
-            // PasteSpecial has seven reference parameters, all of which are
-            // optional. This example uses named arguments to specify values
-            // for two of the parameters. Although these are reference
-            // parameters, you do not need to use the ref keyword, or to create
-            // variables to send in as arguments. You can send the values directly.
-            wordApp.Selection.PasteSpecial( Link: true, DisplayAsIcon: true);
+            CreateIconInWordDocCore();
+        }
+
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        static void CreateIconInWordDocCore()
+        {
+            Word.Application wordApp = null;
+            Word.Document document = null;
+
+            try
+            {
+                wordApp = new Word.Application();
+                wordApp.Visible = true;
+
+                // The Add method has four reference parameters, all of which are
+                // optional. Visual C# allows you to omit arguments for them if
+                // the default values are what you want.
+                document = wordApp.Documents.Add();
+
+                // PasteSpecial has seven reference parameters, all of which are
+                // optional. This example uses named arguments to specify values
+                // for two of the parameters. Although these are reference
+                // parameters, you do not need to use the ref keyword, or to create
+                // variables to send in as arguments. You can send the values directly.
+                wordApp.Selection.PasteSpecial( Link: true, DisplayAsIcon: true);
+
+                // Save the document
+                string fileName = System.IO.Path.Combine(
+                    Environment.GetFolderPath(Environment.SpecialFolder.Desktop), 
+                    "BankAccountsLink.docx");
+                document.SaveAs(fileName);
+            }
+            finally
+            {
+                // Clean up COM objects in reverse order of creation
+                if (document != null)
+                {
+                    document.Close(true); // Save changes
+                    Marshal.FinalReleaseComObject(document);
+                }
+                if (wordApp != null)
+                {
+                    wordApp.Quit(true); // Save changes to all documents
+                    Marshal.FinalReleaseComObject(wordApp);
+                }
+            }
         }
         //</Snippet9>
 

docs/csharp/advanced-topics/interop/snippets/OfficeWalkthrough/ThisAddIn.cs

@@ -1,6 +1,8 @@
 using System;
 //<Usings>
 using System.Collections.Generic;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
 using Excel = Microsoft.Office.Interop.Excel;
 using Word = Microsoft.Office.Interop.Word;
 //</Usings>
@@ -43,13 +45,45 @@ private void ThisAddIn_Startup(object sender, System.EventArgs e)
             //</CallDisplay>
 
             //<PasteIntoWord>
-            var wordApp = new Word.Application();
-            wordApp.Visible = true;
-            wordApp.Documents.Add();
-            wordApp.Selection.PasteSpecial(Link: true, DisplayAsIcon: true);
+            CreateWordDocumentWithCleanup();
             //</PasteIntoWord>
         }
 
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        private void CreateWordDocumentWithCleanup()
+        {
+            Word.Application wordApp = null;
+            Word.Document document = null;
+
+            try
+            {
+                wordApp = new Word.Application();
+                wordApp.Visible = true;
+                document = wordApp.Documents.Add();
+                wordApp.Selection.PasteSpecial(Link: true, DisplayAsIcon: true);
+
+                // Save the document
+                string fileName = System.IO.Path.Combine(
+                    Environment.GetFolderPath(Environment.SpecialFolder.Desktop), 
+                    "BankAccountsLink.docx");
+                document.SaveAs(fileName);
+            }
+            finally
+            {
+                // Clean up COM objects
+                if (document != null)
+                {
+                    document.Close(true);
+                    Marshal.FinalReleaseComObject(document);
+                }
+                if (wordApp != null)
+                {
+                    wordApp.Quit(true);
+                    Marshal.FinalReleaseComObject(wordApp);
+                }
+            }
+        }
+
         //<Display>
         void DisplayInExcel(IEnumerable<Account> accounts,
                    Action<Account, Excel.Range> DisplayFunc)
@@ -72,6 +106,109 @@ void DisplayInExcel(IEnumerable<Account> accounts,
         }
         //</Display>
 
+        //<ProperCleanup>
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        static void CreateComObjectsAndCleanup()
+        {
+            Excel.Application excelApp = null;
+            Excel.Workbook workbook = null;
+            Excel.Worksheet worksheet = null;
+
+            try
+            {
+                excelApp = new Excel.Application();
+                workbook = excelApp.Workbooks.Add();
+                worksheet = workbook.ActiveSheet;
+
+                // Use COM objects here...
+            }
+            finally
+            {
+                // Clean up COM objects in reverse order of creation
+                if (worksheet != null)
+                {
+                    Marshal.FinalReleaseComObject(worksheet);
+                }
+                if (workbook != null)
+                {
+                    workbook.Close(true);
+                    Marshal.FinalReleaseComObject(workbook);
+                }
+                if (excelApp != null)
+                {
+                    excelApp.Quit();
+                    Marshal.FinalReleaseComObject(excelApp);
+                }
+            }
+        }
+        //</ProperCleanup>
+
+        //<DisplayWithCleanup>
+        void DisplayInExcelWithCleanup(IEnumerable<Account> accounts,
+                   Action<Account, Excel.Range> DisplayFunc)
+        {
+            DisplayInExcelCore(accounts, DisplayFunc);
+        }
+
+        [MethodImpl(MethodImplOptions.NoInlining)]
+        void DisplayInExcelCore(IEnumerable<Account> accounts,
+                   Action<Account, Excel.Range> DisplayFunc)
+        {
+            Excel.Application excelApp = null;
+            Excel.Workbook workbook = null;
+            Excel.Worksheet worksheet = null;
+
+            try
+            {
+                excelApp = new Excel.Application();
+                excelApp.Visible = true;
+
+                // Add a new Excel workbook.
+                workbook = excelApp.Workbooks.Add();
+                worksheet = workbook.ActiveSheet;
+
+                worksheet.Cells[1, 1].Value = "ID";
+                worksheet.Cells[1, 2].Value = "Balance";
+
+                int row = 2;
+                foreach (var ac in accounts)
+                {
+                    var cell = worksheet.Cells[row, 1];
+                    DisplayFunc(ac, cell);
+                    row++;
+                }
+
+                // Save the workbook
+                string fileName = System.IO.Path.Combine(
+                    Environment.GetFolderPath(Environment.SpecialFolder.Desktop), 
+                    "BankAccounts.xlsx");
+                workbook.SaveAs(fileName);
+
+                // Copy the results to the Clipboard.
+                worksheet.Range["A1:B3"].Copy();
+            }
+            finally
+            {
+                // Always clean up COM objects in reverse order of creation
+                if (worksheet != null)
+                {
+                    Marshal.FinalReleaseComObject(worksheet);
+                }
+                if (workbook != null)
+                {
+                    workbook.Close(true); // Save changes
+                    Marshal.FinalReleaseComObject(workbook);
+                }
+                if (excelApp != null)
+                {
+                    excelApp.DisplayAlerts = true;
+                    excelApp.Quit();
+                    Marshal.FinalReleaseComObject(excelApp);
+                }
+            }
+        }
+        //</DisplayWithCleanup>
+
 
         private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
         {

docs/csharp/advanced-topics/interop/walkthrough-office-programming.md

@@ -96,6 +96,53 @@ This code demonstrates several of the features in C#: the ability to omit the `r
 
 Press F5 to run the application. Excel starts and displays a table that contains the information from the two accounts in `bankAccounts`. Then a Word document appears that contains a link to the Excel table.
 
+## Important: COM object cleanup and resource management
+
+The examples shown above demonstrate basic Office Interop functionality, but they don't include proper cleanup of COM objects. This is a critical issue in production applications because failing to properly release COM objects can result in orphaned Office processes that remain in memory even after your application closes.
+
+### Why COM object cleanup is necessary
+
+COM objects in Office Interop require explicit cleanup because:
+
+- The .NET garbage collector doesn't automatically release COM objects
+- Each Excel or Word object you create holds resources that must be manually released
+- Without proper cleanup, Office applications remain running in the background
+- This applies to all COM objects: Application, Workbooks, Worksheets, Ranges, and more
+
+### Proper cleanup pattern
+
+The most reliable way to ensure COM objects are properly released is to factor out the COM object creation and usage into a separate non-inlineable method. This pattern guarantees that object references go out of scope and can be collected:
+
+:::code language="csharp" source="./snippets/OfficeWalkthrough/ThisAddIn.cs" id="ProperCleanup":::
+
+Add the following enhanced version of the `DisplayInExcel` method that includes proper COM object cleanup:
+
+:::code language="csharp" source="./snippets/OfficeWalkthrough/ThisAddIn.cs" id="DisplayWithCleanup":::
+
+This pattern ensures that:
+
+- COM objects are released even if an exception occurs
+- Object references are guaranteed to go out of scope when the core method returns
+- Excel processes don't remain orphaned in Task Manager
+- Memory is properly freed
+- The application behaves reliably in production environments
+
+For production applications, always implement this cleanup pattern for every COM object you create, including Application, Workbooks, Worksheets, Ranges, and other Office objects.
+
+### Common questions about COM object cleanup
+
+**Why can't garbage collection handle this automatically?**
+COM objects use reference counting for memory management, which is different from .NET's garbage collection. The .NET runtime creates a Runtime Callable Wrapper (RCW) around each COM object, but the RCW doesn't automatically release the underlying COM object when it's garbage collected.
+
+**Why do you use separate methods with MethodImpl(MethodImplOptions.NoInlining)?**
+The .NET JIT compiler can extend object lifetimes until the end of a method, which means local variable assignments to null aren't guaranteed to release references immediately. By factoring out COM object creation and usage into separate non-inlineable methods, you ensure that object references truly go out of scope when the method returns, allowing reliable cleanup.
+
+**Do I need to call GC.Collect() and GC.WaitForPendingFinalizers()?**
+With the separate non-inlineable method pattern, these calls are typically not necessary. The pattern ensures that COM object references go out of scope reliably when the method returns. However, you can optionally add these calls after the separate method call for additional safety in scenarios where you want to force immediate cleanup.
+
+**What happens if I don't follow this pattern?**
+Without proper cleanup, Office applications remain running in the background even after your application exits. You can verify this by checking Task Manager - you'll see excel.exe or winword.exe processes that weren't properly terminated. These orphaned processes consume memory and can cause issues with future Office automation.
+
 ## Clean up the completed project
 
 In Visual Studio, select **Clean Solution** on the **Build** menu. Otherwise, the add-in runs every time that you open Excel on your computer.