文檔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註釋。