记录WCF接口的最佳方法?

So I'm using WCF, and want to document my interface(s) and services to give to another company for an internal app. What's the best way to document those interfaces? I'd prefer having the documentation inline with the code, and then have something prettify to output HTML, but am not sure if there's a recommended way to do it.

所以我在使用WCF，并且想要记录我的接口和服务，以便给另一家公司提供一个内部应用。记录这些接口的最好方法是什么?我更希望文档与代码内联，然后有一些更好的东西来输出HTML，但我不确定是否有推荐的方法。

5 个解决方案

#1

Do use XML docs for that. There are a lot of smart meta-tags that will allow you to put code samples in them, references between operations, thrown exceptions etc.

一定要使用XML文档。有许多智能的元标签可以让您在其中放置代码示例、操作之间的引用、抛出的异常等等。

Then you can use Sandcastle (+ some GUI you can find on Codeplex) to generate either chm, or html documentation.

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

#2

We use WCFExtras (http://www.codeplex.com/WCFExtras) for that.

为此，我们使用WCFExtras (http://www.codeplex.com/WCFExtras)。

Among other features it allows live exporting of your code xml comments into the generated WSDL, for example check how these xml comments:

它还允许将代码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);

get reflected in the WSDL of that interface:

在该接口的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>

An excerpt from their docs:

摘自他们的文档:

Adding WSDL Documentation from Source Code XML Comments This extension allows you to add WSDL documentation (annotaiton) directly from XML comments in your source file. These comments will be published as part of the WSDL and are available for WSDL tools that know how to take advantage of them (e.g. Apache Axis wsdl2java and others). Release 2.0 also includes a client side WSDL importer that will turn those WSDL comments to XML comments in the generated proxy code.

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

#3

I use two XSL files - one to document the WSDL for the operations, one to document the XSD for the data being passed around.

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

Unfortunately, so far, I haven't found a single cohesive solution, so I work with two XSLT files which transform the WSDL and the XSD respectively into HTML documentation.

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

WSDL Viewer does the job for the WSDL and produces a first HTML document, and xs3p does the same for the data contain in the XSD file.

WSDL查看器为WSDL执行该任务并生成第一个HTML文档，xs3p对XSD文件中包含的数据执行相同的操作。

#4

Using the XML output from the compiler is nice...but it's been my experience that it's difficult to express the complete complexity of a service and it's expected invariants, dependencies, etc. in comments alone. You're better off maintaining a separate real document (Word, HTML, Wiki) to cover it all.

使用编译器的XML输出很好……但我的经验是，很难表达一个服务的全部复杂性，它的预期不变量、依赖项等仅在注释中。你最好保持一个独立的真实文档(Word, HTML, Wiki)来覆盖所有的文档。

#5

I will put my interface contract into a common dll and hand that out. It gives them both the xml comments on the contract without giving the details of the service as well as allowing them to implement the service in an offline mode for testing until they're ready to use it. On top of that, they can bypass the wsdl and use ChannelFactory to create a channel.

我将把我的接口契约放到一个公共dll中，并将其分发出去。它向他们提供合同上的xml注释，而不提供服务的细节，并允许他们以离线模式实现服务，以进行测试，直到他们准备好使用它。除此之外，它们还可以绕过wsdl并使用ChannelFactory创建一个通道。

#1