是否可以在 C# 代码中向 COM 对象添加注释？答案

【问题标题】：Is it possible to add comments to COM objects inside C# code?是否可以在 C# 代码中向 COM 对象添加注释？
【发布时间】：2011-05-03 14:17:20
【问题描述】：

我想知道是否可以手动将 cmets 添加到我在项目中使用的 COM 类或枚举中。

我们的大多数程序员都可以毫无问题地使用 then，但是由于这里有一些没有经验的程序员，我想知道是否可以改进文档，为我们公司使用的 COM 对象、接口和枚举添加一些 cmets。

类似：


///&lt;summary&gt;This is a enum that doesn't do anything&lt;/summary&gt;
enum ComApi.FooBar
{
  ///&lt;summary&gt;Does Foo&lt;/summary&gt;
  Foo,
  ///&lt;summary&gt;Does Bar&lt;/summary&gt;
  Bar,
  ///&lt;summary&gt;Does Foo and Bar, and divid by zero!&lt;/summary&gt;
  Baz
}

如果上面的方法不可行，那么是否可以直接在COM dll中添加cmets？

顺便说一句，我正在使用 c# 在 VS 2008 上进行开发。我正在尝试通过向 COM 对象添加一些 cmets 来改善我们的程序员体验，以便 Visual Studio 在其文档界面中显示。

【问题讨论】：

请不要这么偷懒。当您尝试上述代码时会发生什么？
你试过了吗？添加一些 cmets 并构建。如果构建成功（它将成功），则意味着是的，它是可能的 :) 您可以找到自己的答案。
首先，感谢您的回答，但我认为我们在这里失去了意义。在这篇文章中，我只是想找出一些为我的 COM 对象添加 cmets 的方法。顺便说一句，Passant 先生和 Qwertie 先生都给了我很好的答案。谢谢你们。

标签： c# .net com

【解决方案1】：

你这样做的方式行不通。使用三斜杠表示注释会导致 VS 期望 XML 格式的文档。阅读this article了解详情。如果操作正确，您的程序员将通过 IntelliSense 查看文档。

【讨论】：

您好。我在我的问题上修复了 cmets，然后添加了摘要标签。只是为了说明我知道我的字体上有这些标签，但是由于我是堆栈溢出的新手，所以我忘了在标签之间添加`。不管怎样，谢谢你的提醒。

【解决方案2】：

COM 类型库do 通过 [helpstring] 属性支持 cmets。许多 COM 感知开发环境在其编辑器中显示这些 cmets。但是，.NET 不支持此功能，类型库是从已删除所有 cmets 的已编译代码生成的。 .NET 中没有属性可以让 Regasm.exe 或 Tlbexp.exe 将其发送到 .tlb。

如果您想实现这一点，那么您必须编写一个 .idl 文件。您可以使用 OleView.exe、File + View Typelib 命令从现有的 .tlb 中获取一个。然后您可以编辑该文件以插入 [helpstring] 属性，midl.exe 可以将其转换回类型库。

它的残酷之处在于，当 C# 代码的公共接口发生更改时，您必须重做此操作。没有工具就没有乐趣。您必须将其自动化，以确保此类型库不会与 C# 代码脱节。这会产生无法诊断的可怕运行时异常。像 AccessViolationException。或者更糟糕的是，根本没有例外，只是堆栈不平衡时的错误值。我不知道现有的工具可以做到这一点。

【讨论】：

感谢知识分享。我想我会避免这个解决方案，因为你对我说它可能会导致错误的异常消息，并尝试下面的另一个，但这是一个很好的答案。谢谢。
@Canella - 这是提供智能感知的两种相反方式。我假设您使用 C# 创建了一个 COM 服务器，供其他人使用。 @Qwertie 显示完全相反，在 C# 程序中使用以另一种语言编写的 COM 服务器。如果您使用 C# 编写 C# 程序员使用的 COM 服务器，那么您就完全错误了。目前尚不清楚哪种情况是这种情况，但您不能两者都做。
嗨@Hans。实际上，我的问题符合您描述的@Qwertie cenario。很抱歉我在原帖中没有说清楚。我稍后会修复它。但你的回答也很棒。谢谢你的启发。
啊，我只是假设问题是关于在 C# 中使用非 .NET COM 服务器...但是现在我再次查看该问题，我发现它可能被误解为一个问题关于用 C# 编写 COM 服务器并在某些（非 dot-net）项目中使用它。

【解决方案3】：

在 Visual Studio 中，当您在 DLL 中定义的类上按 F12（转到定义）时，Visual Studio 会显示该类的 C# 表示形式，以及它找到的有关该类的任何文档。通常（总是？）此类文档与 DLL 一起存储在 XML 文件中。例如，名为 Foo.dll 的 DLL 将具有包含文档的 Foo.xml 文件。这是一个显示 XML 外观的示例：

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Interop.MyComLib</name>
    </assembly>
    <members>
        <member name="T:MyComLib.IMyInterface">
            <summary>
            An interface for transforming actionable items into itemed actions.
            </summary>
        </member>
        <member name="M:MyComLib.IMyInterface.Dance(System.Boolean)">
            <summary>
            Causes any pending phat moves to be flushed to corporeal
            form in a visually pleasing manner.
            </summary>
            <param name="b">Must be true, or there will be a FalseException.</param>
            <returns>A <see cref="T:System.Boolean"/> containing the opposite of the 'b' argument.</returns>
        </member>
    </members>
</doc>

XML 文件必须放在主互操作程序集旁边，如果 COM 库是 MyCom.DLL，则该程序集通常具有诸如 Interop.MyComLib.DLL 之类的文件名。如果 COM DLL 没有特制的主 Interop 程序集，则 Visual Studio 将自动生成一个 Interop 程序集，在这种情况下，您的 obj\Debug 文件夹中将有一个副本（用于调试构建），另一个副本在obj\Release 文件夹（用于发布版本）。如果你像这样制作一个 XML 文件，并将它放在 Interop DLL（不是原来的 COM DLL！）旁边，那么 VS 应该能够找到它。

bin\* 文件夹中还有额外的副本，但 Visual Studio 不会在 bin\* 中查找文档。

为了帮助您创建文档，您可以编写一个以 Interop DLL 命名的虚拟项目，其中包含公开的无操作代码：

namespace ComApiLib
{
    /// <summary>This is a enum that doesn't do anything</summary>
    public enum ComApi.FooBar
    {
      ///<summary>Does Foo</summary>
      Foo,
      ///<summary>Does Bar</summary>
      Bar,
    }
    /// <summary>This is a class</summary>
    public class Klass
    {
        ///<summary>Does Foo</summary>
        public void Foo() {}
        ///<summary>Does Bar</summary>
        public void Bar() {}
    }
}

在项目设置的“构建”选项卡中，启用“XML 文档文件”复选框。然后构建您的项目，将 XML 文件复制到 Interop DLL 旁边（并使用 XML 扩展名为其命名），然后查看 Visual Studio 是否识别 XML 文件（您可能需要重新启动 Visual Studio）。

附： “helpstring”属性对我不起作用。我没有看到它在任何地方的 Visual Studio 中显示。有没有办法让它工作？

【讨论】：

这可能是我要适应我的项目的解决方案。感谢@Qwertie 的回答，以及您发布的详细代码。

【解决方案4】：

没有一个答案真正回答了问题。答案很简单。在 C# 中使用 System.ComponentModel.DescriptionAttribute 属性可以记录 COM 对象 ([helpstring("...")])。并且 'Description' 属性从 .Net Framework 1.1 版开始可用。

例如C#类定义：

  /// <summary>
  /// 4. 'Obj_Anforderung' - (Obj_request) <-- this works for documenting in XML for VS docs or documentation generation tools
  /// </summary>
#if COMLIB
  [ComVisible(true)]
  [Guid("E58D82B8-2104-4378-92AB-E63F2FAF1EE8")]
  [Description("4. 'Obj_Anforderung' - (Obj_request)")] // <-- this works for COM interops
#endif 
  [TypeConverter(typeof(ExpandableObjectConverter))]
  public class Obj_Anforderung : GdtObj
  {
  }

当使用 COM Interop true 和 Com Visible 编译 C# 项目时，我们可以使用 OLE-COM 查看器查看它的定义（任何 VS 都有此工具 - 查看 Visual Studio 子组下的 Programs 菜单）：

[
  uuid(E58D82B8-2104-4378-92AB-E63F2FAF1EE8),
  version(1.0),
  helpstring("4. 'Obj_Anforderung' - (Obj_request)"),
  noncreatable,
  custom(0F21F359-AB84-41E8-9A78-36D110E6D2F9, "open.medical.gdt.definitions.Obj_Anforderung")
]
coclass Obj_Anforderung {
    [default] interface _Obj_Anforderung;
    interface _Object;
};

正如您所见，[helpstring] 存在并且可以使用任何支持 COM [helpstring] 的标准 IDE 查看。例如旧的 VB6 将其视为

Class Obj_Anforderung
    Member of open_medical_gdt
    4. 'Obj_Anforderung' - (Obj_request)

是的，这是 .Net COM Interops 支持（简化版）背后的总体思路。如果您有支持 COM 互操作的旧的、庞大的、健壮的应用程序，并且您不想将其移植到另一种语言。您可以在 .Net C# 中编写一段代码，在旧应用程序中只需将 C# 引用为 COM 互操作对象库并正常使用它，因为它是该编程环境的一部分。

【讨论】：