在Word文档添加RichTextContentControl时触发异常的问题排查

问题场景 #

尝试在Word文档中添加RichTextContentControl，代码在正文文本框中选中文本添加控件时可正常运行，但当文本框位于文档页眉特定位置时，生成的控件对象存在异常，无法设置Tag、PlaceholderText等属性，触发控件丢失的错误。

添加控件的代码 #

using (var range = new ReleaseComObject<Range>(myRange))
{
    var contentControl = vstoDocument.Controls.AddRichTextContentControl(range.ComObject, $"PROPERTY{Guid.NewGuid()}");
    contentControl.PlaceholderText = propertyContentControl.Key; // 此处触发异常
}

异常信息 #

This document might not function as expected because the following control is missing: MYCONTROL. Data that relies on this control will not be automatically displayed or updated, and other custom functionality will not be available. Contact your administrator or the author of this document for further assistance.

ReleaseComObject类定义 #

public sealed class ReleaseComObject<T> : IDisposable
public ReleaseComObject(T comObject) => this.myComObject = comObject;

异常原因分析 #

• COM对象提前释放：using块会在代码执行完毕后自动调用ReleaseComObject的Dispose方法（推测内部会调用Marshal.ReleaseComObject释放Range的COM实例），但VSTO创建的RichTextContentControl需要依赖该Range对象完成与文档模型的绑定。尤其是页眉这类特殊区域，Word对对象生命周期的管理更严格，提前释放Range会导致控件关联的底层对象失效，触发控件丢失异常。
• 页眉区域对象模型限制：Word的页眉/页脚属于Section层级下的特殊区域，其中文本框的Range对象与正文区域的Range在对象层次、生命周期管理上存在差异。VSTO控件绑定这类Range时，需要Range对象保持有效直到控件完全初始化，否则会导致控件创建不完整。
• ReleaseComObject的潜在风险：如果该包装类的Dispose方法直接调用Marshal.ReleaseComObject，可能会过度释放COM对象。Word对象模型中多个托管对象可能共享同一个底层COM实例，提前释放会破坏依赖链，导致后续操作控件属性时出错。

解决思路 #

• 移除Range的using包装：不要用ReleaseComObject包裹Range对象，让.NET的COM互操作运行时（RCW）自动管理对象生命周期，直到垃圾回收时释放。若必须手动管理，需确保在所有控件属性设置完成后，再手动释放Range对象。
• 调整代码执行顺序：先完成RichTextContentControl的创建，确认控件对象已成功绑定到文档后，再设置PlaceholderText等属性，避免在控件未完全初始化时操作属性。
• 规范页眉Range的获取方式：获取页眉中文本框的Range时，通过明确的对象层次获取（如Document.Sections[1].Headers[WdHeaderFooterIndex.wdHeaderFooterPrimary].Shapes["文本框名称"].TextFrame.TextRange），确保获取到的Range对象稳定有效。
• 优化COM对象释放逻辑：如果必须使用ReleaseComObject，需在Dispose方法中增加引用计数检查，避免过度释放；同时不要在控件创建和属性设置的关键流程中提前释放依赖的COM对象。

内容的提问来源于stack exchange，提问作者user7112196