文档WCF接口的最佳方式？

Question

因此，我使用WCF，并希望记录我的接口和服务，以便为另一家公司提供内部应用程序。什么是记录这些接口的最佳方式？我宁愿让文档与代码内联，然后有一些美化输出HTML的东西，但我不确定是否有推荐的方法来执行此操作。

Answer 1

请使用XML文档。有很多智能元标签可以让你把代码样本放在其中，操作之间的引用，抛出的异常等。

然后你可以使用Sandcastle（+你可以在Codeplex上找到的一些GUI）来生成chm或html文档。

Answer 2

使用来自编译器的XML输出的是好的...但它是我的经验，这是难以表达的服务的完整的复杂性和它的预期不变，相关性等，在单独的意见。你最好维护一个单独的真实文档（Word，HTML，Wiki）来覆盖它。

Answer 3

我用两个XSL文件 - 一个记录的WSDL的操作，一个记录了XSD为正在传递数据。

遗憾的是，到目前为止，我还没有找到一个单一的解决方案凝聚力，所以我与改造WSDL和XSD分别为HTML文档2个XSLT文件。

WSDL Viewer完成WSDL的工作并生成第一个HTML文档，而xs3p对XSD文件中的数据包含也是如此。

Answer 4

我会把我的界面合同放到一个普通的dll中，并发布出来。它给他们提供了合同上的xml注释，而不用提供服务的细节，并允许他们在脱机模式下实施服务，直到他们准备使用它。最重要的是，他们可以绕过wsdl并使用ChannelFactory创建一个频道。

Answer 5

我们使用的是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等）。 2.0版还包括一个客户端WSDL导入器，它将这些WSDL注释转换为生成的代理代码中的XML注释。