Add comprehensive COM object cleanup documentation and examples for Excel Interop

[Copilot]

The Excel Interop programming walkthrough was missing critical information about proper COM object cleanup, which is essential for production applications. The original examples skipped saving/closing operations and didn't demonstrate how to prevent orphaned Excel processes.

Key Issues Addressed

Missing cleanup leads to orphaned processes: The original examples would leave excel.exe processes running in Task Manager after the application closed, as noted in the issue feedback.

Incomplete examples: The walkthrough skipped the "most difficult steps (saving and exiting)" that developers actually need in real applications.

No guidance on resource management: Developers were left to discover the complex COM cleanup requirements on their own.

Changes Made

New Documentation Section

• Added "Important: COM object cleanup and resource management" section explaining why cleanup is necessary
• Added "Common questions about COM object cleanup" addressing developer concerns about garbage collection, null assignment, and consequences of improper cleanup

Enhanced Code Examples

• Updated DisplayInExcel method to include complete try/finally cleanup pattern
• Updated CreateIconInWordDoc method with proper Word document cleanup
• Added new DisplayInExcelWithCleanup method demonstrating full lifecycle with saving
• Added CleanupComObject helper method showing the standard pattern

Cleanup Pattern Demonstrated

finally
{
    // Clean up COM objects in reverse order of creation
    if (worksheet != null)
    {
        Marshal.FinalReleaseComObject(worksheet);
        worksheet = null;
    }
    if (workbook != null)
    {
        workbook.Close(true); // Save changes
        Marshal.FinalReleaseComObject(workbook);
        workbook = null;
    }
    if (excelApp != null)
    {
        excelApp.DisplayAlerts = true;
        excelApp.Quit();
        Marshal.FinalReleaseComObject(excelApp);
        excelApp = null;
    }
    
    GC.Collect();
    GC.WaitForPendingFinalizers();
}

The documentation now properly addresses the critical aspects of Office Interop programming, providing developers with the knowledge they need to build reliable applications that don't leave orphaned Office processes.

Fixes #22316.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[jkotas]

.NET runtime does not guarantee that objects above gets collected. The JIT is free to extend lifetimes till end of the method. Assigning null to local variables like excelApp = null; may help, but it is not 100% reliable.

The only reliable way to get objects collected is by factoring out the code where it is not desirable to extend lifetimes into its own non-inlineable method.

[Copilot]

You're absolutely right. I've updated the COM cleanup pattern to use separate non-inlineable methods that guarantee object references go out of scope. The new pattern removes the unreliable null assignments and GC.Collect() calls, using MethodImpl(MethodImplOptions.NoInlining) to ensure reliable cleanup. Fixed in commit 69cdbfc.

[jkotas]

The sample do not call GC.Collect and GC.WaitForPendingFinalizers anymore. Should they?

[Copilot]

Updated the documentation to clarify that GC.Collect() and GC.WaitForPendingFinalizers() are optional with the reliable separate method pattern. The samples use the more reliable approach without needing these calls. Fixed in commit 94b85e8.

[jkotas]

This is not correct.

The non-inlinable method is only needed when the user wants to deterministically cleanup all objects using GC.Collect() and GC.WaitForPendingFinalizers().

The non-inlinable method alone does not help.

[Copilot]

You're absolutely correct. I've updated the documentation and code to reflect the proper relationship between the non-inlinable method pattern and GC calls. The pattern is only beneficial when using GC.Collect() and GC.WaitForPendingFinalizers(), not by itself. The examples now use the straightforward cleanup pattern that directly addresses the orphaned process issue. Fixed in commit 5d03bf1.

[jkotas]

I believe that the non-inlinable method in combination with explicit calls to GC.Collect() and GC.WaitForPendingFinalizers() is very advanced scenario that most users should not be concerned with.

[Copilot]

You're absolutely right. I've simplified the documentation to remove the advanced non-inlinable method discussion and focus on the basic cleanup pattern that most developers need. The documentation now emphasizes the essential Marshal.FinalReleaseComObject() pattern without overcomplicating things. Fixed in commit 59e3252.

[jkotas]

These assignments of null have no impact. The JIT compiler is likely to optimize them out.

[Copilot]

Correct, I've removed all the null assignments since the JIT compiler optimizes them out anyway. The cleanup now focuses only on the effective Marshal.FinalReleaseComObject() calls. Fixed in commit 59e3252.

[jkotas]

This sample is called "DisplayInExcel". The name suggests that the Excel is expected to say open, displaying the content when the sample finishes executing. Should this be dropped in this sample?

[Copilot]

Good point about the semantic mismatch. I've removed the excelApp.Quit() call from the DisplayInExcel method since it's intended to display data to users. Added documentation explaining that for display scenarios, Excel remains open for user interaction, while automation scenarios should include the Quit() call. Fixed in commit 59e3252.

[jkotas]

, but the RCW doesn't automatically release the underlying COM object when it's garbage collected.

This is invalid statement. RCW does release the underlying COM object when it's garbage collected. The problem is the delayed nature of garbage collection. not that the RCW is not released.

[Copilot]

You're correct. Fixed the inaccurate statement to reflect that RCWs do release underlying COM objects when garbage collected - the issue is the non-deterministic timing of garbage collection, not that RCWs don't release objects. Fixed in commit ce5d34f.

[jkotas]

I do not think that this pattern should be followed by most production applications out there.

The delayed release of the COM objects that is a side-effect of garbage collection is not a problem for most production applications. Vast majority of developers love that .NET garbage collection takes care of it for them and they are perfectly fine paying a small price for it.

Stepping back, this is introductory sample for Office Interop. it is appropriate to complicate it by manual lifetime management. I think it may be better to leave this sample alone, and move the advanced topic of manual lifetime management to a new advanced sample.

[Copilot]

You're absolutely right. I've simplified the walkthrough to remove the complex manual cleanup patterns and restored the original simple examples that rely on .NET garbage collection. The introductory sample now maintains the appropriate level of complexity for beginners, and the delayed COM object release is acceptable for most applications. Fixed in commit c097dc9.