记录WCF接口的最佳方法是什么？

Question

所以我正在使用WCF,并希望记录我的界面和服务,以便为另一家公司提供内部应用程序.记录这些界面的最佳方法是什么？我更喜欢将文档与代码内联,然后对输出HTML有一些美化,但我不确定是否有推荐的方法来实现它.

Answer 1

我们使用WCFExtras(http://www.codeplex.com/WCFExtras).

除了其他功能之外,它还允许将代码xml注释实时导出到生成的WSDL中,例如检查这些xml注释的方式:

    /// <summary>
    /// Retrieve the tickets information for the specified order
    /// </summary>
    /// <param name="orderId">Order ID</param>
    /// <returns>Tickets data</returns>
    [OperationContract]
    TicketsDto GetTickets(int orderId);

反映在该接口的WSDL中:

    <wsdl:operation name="GetTickets">
    <wsdl:documentation>
    <summary> Retrieve the tickets information for the specified order </summary> <param name="orderId">Order ID</param> <returns>Tickets data</returns>
    </wsdl:documentation>
    <wsdl:input wsaw:Action="xxxx" message="tns:PartnerAPI_GetTickets_InputMessage"/>
    <wsdl:output wsaw:Action="xxxx" message="tns:PartnerAPI_GetTickets_OutputMessage"/>
    </wsdl:operation>

摘自他们的文档:

从源代码XML注释添加WSDL文档此扩展允许您直接从源文件中的XML注释添加WSDL文档(annotaiton).这些注释将作为WSDL的一部分发布,并且可用于知道如何利用它们的WSDL工具(例如Apache Axis wsdl2java和其他).Release 2.0还包括一个客户端WSDL导入器,它将这些WSDL注释转换为生成的代理代码中的XML注释.

Answer 2

为此使用XML文档.有很多智能元标记允许您将代码示例放入其中,操作之间的引用,抛出异常等.

然后你可以使用Sandcastle(你可以在Codeplex上找到一些GUI)来生成chm或html文档.