Почему XML-генератор C# не работает правильно для COM-импортированных интерфейсов?

Question

При использовании комментариев документации XML в C# для создания документации .XML-файла в VS2010 SP1 я заметил, что не работает должным образом в одном конкретном случае: для COM-импортированные элементы интерфейса (методы и свойства).

Давайте этот C# файл, принимая некоторые виды из MS Word Primary 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.

Мой вопрос заключается в следующем: есть ли причина для этого поведения или это ошибка? Что я могу сделать, чтобы заставить COM-импортированные элементы интерфейса правильно ссылаться в созданных файлах документации XML?

Answer 1

Действительно интересный выпуск. Я мог бы воспроизвести это, но для ParagraphFormatClass.Alignment это все еще неправильно для меня. Более интересно, если вы фактически используете эти элементы в своем коде (в данном методе), даже в блоке if (false), ссылки XML cref разрешены соответствующим образом. Но, к сожалению, этот трюк работает только в методах, а не в классах. Поэтому я думаю, что у вас нет другого выбора, кроме как вручную ввести идентификационные данные для членов:

<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 комментариев. Это моя теория.