C# 记录 WCF 界面的最佳方式？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/823148/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Best way to document WCF interface?
提问by XPav
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，但我不确定是否有推荐的方法来做到这一点。
采纳答案by Krzysztof Kozmic
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 文档。
回答by Paul Alexander
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）来涵盖所有内容。
回答by marc_s
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 Viewerdoes the job for the WSDL and produces a first HTML document, and xs3pdoes the same for the data contain in the XSD file.
WSDL Viewer为 WSDL 完成工作并生成第一个 HTML 文档，而xs3p为包含在 XSD 文件中的数据执行相同的操作。
回答by Joshua Belden
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 创建通道。
回答by Aleksander Belov
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 和其他工具）。2.0 版还包括一个客户端 WSDL 导入器，它将在生成的代理代码中将这些 WSDL 注释转换为 XML 注释。
