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

Answer 2

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

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

Answer 3

我使用两个XSL文件 - 一个用于记录操作的WSDL，一个用于记录传递数据的XSD。

不幸的是，到目前为止，我还没有找到一个统一的解决方案，所以我使用了两个XSLT文件，它们分别将WSDL和XSD转换为HTML文档。

WSDL Viewer完成WSDL的工作并生成第一个HTML文档，xs3p对XSD文件中包含的数据执行相同的操作。

Answer 4

使用编译器的XML输出很不错......但是根据我的经验，很难表达服务的完整复杂性，而且仅在评论中就是预期的不变量，依赖关系等。你最好维护一个单独的真实文档（Word，HTML，Wiki）来覆盖它。

Answer 5

我会将我的接口合同放入一个共同的dll并将其交给我。它为合同提供了xml评论，但没有提供服务的详细信息，也允许他们在离线模式下实施服务进行测试，直到他们准备好使用它为止。最重要的是，他们可以绕过wsdl并使用ChannelFactory创建一个频道。

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

5 个答案: