爲什麼C＃文檔XML生成器對COM導入的接口不能正常工作？

Question

當在C＃中使用XML文檔註釋在VS2010 SP1中生成文檔.XML文件時，我注意到在某個特定情況下似乎無法正常工作：對於COM導入接口成員（方法和屬性）。

讓我們這個C＃文件，同時從微軟Word主Interop大會的一些類型的（我猜是衆所周知的大多數人）爲例：

using Microsoft.Office.Interop.Word; 
namespace TestProject 
{ 
    /// <summary> 
    /// Documentation test class. This documentation references a COM interface: <see cref="_Document"/> 
    /// and a method in that interface: <see cref="_Document.Activate"/>, as well as a property 
    /// <see cref="_Document.ActiveTheme"/>. 
    /// </summary> 
    public class DocumentedClass 
    { 
    } 
} 

生成的.XML文件文件包含此：

<member name="T:TestProject.DocumentedClass"> 
    <summary> 
    Documentation test class. This documentation references a COM interface: <see cref="T:Microsoft.Office.Interop.Word._Document"/> 
    and a method in that interface: <see cref="!:_Document.Activate"/>, as well as a property 
    <see cref="!:_Document.ActiveTheme"/>. 
    </summary> 
</member> 

當你在生成的XML文件片段仔細觀察，你會發現參考COM接口解析（T:Microsoft.Office.Interop.Word._Document），但沒有解決的接口成員（例如!:_Document.Activate）。

我試圖完全限定文檔註釋內部接口部件如下，但結果是一樣的：現在

namespace TestProject 
{ 
    /// <summary> 
    /// Documentation test class. This documentation references 
    /// a COM interface: <see cref="Microsoft.Office.Interop.Word._Document"/> 
    /// and a method in that interface: <see cref="Microsoft.Office.Interop.Word._Document.Activate"/>, 
    /// as well as a property: <see cref="Microsoft.Office.Interop.Word._Document.ActiveTheme"/>. 
    /// </summary> 
    public class DocumentedClass2 
    { 
    } 
} 

，是什麼奇怪的是，它似乎爲COM進口類工作成員，例如本文檔：

using Microsoft.Office.Interop.Word; 
namespace TestProject 
{ 
    /// <summary> 
    /// Now, let's reference a COM class <see cref="ParagraphFormatClass"/> and its member property 
    /// <see cref="ParagraphFormatClass.Alignment"/>. 
    /// </summary> 
    public class DocumentedClass3 
    { 
    } 
} 

結果在以下XML文檔文件片段：

<member name="T:TestProject.DocumentedClass3"> 
    <summary> 
    Now, let's reference a COM class <see cref="T:Microsoft.Office.Interop.Word.ParagraphFormatClass"/> and its member 
    <see cref="P:Microsoft.Office.Interop.Word.ParagraphFormatClass.Alignment"/>. 
    </summary> 
</member> 

爲COM類屬性被正確解析爲P:Microsoft.Office.Interop.Word.ParagraphFormatClass.Alignment這是完全有效的。

這確實發生在COM導入接口上，正常接口成員在生成的文檔XML文件中被正確地引用。如果COM導入的接口來自PIA，或者您通過tlbimp.exe自行導入類型庫，則沒有區別。

我的問題是這樣的：是否有這種行爲的原因，或者它是一個錯誤？在生成的XML文檔文件中，如何正確引用COM導入的接口成員，我該怎麼做？

Answer 1

真的很有趣的問題。我可以重現這一點，但對於ParagraphFormatClass.Alignment這對我仍然不正確。更有趣的是，如果您實際在代碼中使用這些成員（按給定的方法），即使在if (false)區塊中，也會正確解析XML cref引用。但不幸的是，這個技巧只適用於方法，而不適用於類。所以我覺得你別無選擇，只能手動鍵入成員參考ID：

<see cref="M:Microsoft.Office.Interop.Word._Document.Activate"/> 

<see cref="P:Microsoft.Office.Interop.Word._Document.ActiveTheme"/> 

Answer 2

這是一個.NET 4.0應用程序嗎？如果是這樣，它可能是編譯器在後臺使用動態類型造成的。如果您的項目包含對Microsoft.CSharp的引用，則表明可以使用動態類型。如果刪除引用並執行構建，則會出現編譯器錯誤，說明無法解析動態代碼所需的類型（如果是這種情況）。在我的加載項項目中這樣做會標記我正在使用Document的實例以及其他幾種需要動態聯編程序類型的類型。這可能是編譯器解析類成員而不是接口的原因。對於使用動態類型的實例，直到運行時纔會解析它們。因此，編譯器沒有用於XML註釋成員ID的任何內容。無論如何，這是我的理論。