私はWCFを使用しており、社内のアプリケーションのために他の会社に提供するインタフェースとサービスを文書化したいと考えています。これらのインタフェースを文書化する最良の方法は何ですか?私は、コードとインラインでドキュメントを持っていることを好むだろうし、HTMLを出力するために何かを持っているが、それを行うための推奨された方法があるか分からない。WCFインターフェイスを文書化する最も良い方法は?
答えて
XMLドキュメントを使用してください。コードサンプルを入れたり、操作間の参照、例外を投げたりするスマートなメタタグがたくさんあります。
次に、Sandcastle(Codeplexで見つけることができるGUI)を使用して、 chm、またはhtmlのドキュメントを参照してください。
コンパイラからのXML出力を使用するといいです...しかし、それだけでは、サービスの完全な複雑さを表現するのは難しいですし、不変量、依存性などはコメントだけでは予測できません。別の実際の文書(Word、HTML、Wiki)を維持して、それをすべてカバーする方がよいでしょう。
2つのXSLファイルを使用します.1つは操作用にWSDLを文書化し、もう1つは渡されるデータ用にXSDを文書化します。
残念ながら、これまでのところ、単一の結束ソリューションは見つかっていないため、WSDLとXSDをそれぞれHTMLドキュメントに変換する2つのXSLTファイルを使用しています。
WSDL Viewer WSDLのジョブを実行し、最初のHTML文書を生成し、xs3pは、XSDファイルに含まれるデータに対して同じ処理を行います。
私は、共通のdllに私のインタフェースコントラクトを入れ、それを渡します。これは、サービスの詳細を提供することなく、契約のxmlコメントを提供するだけでなく、サービスをオフラインモードで実装して、使用準備が整うまでテストすることを可能にします。さらに、wsdlをバイパスしてChannelFactoryを使用してチャネルを作成することもできます。
私たちはWCFExtras(http://www.codeplex.com/WCFExtras)を使用しています。
<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>
:
/// <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に反映されます。他の機能の中で
は、それは例えば、これらのXMLコメントがどのように確認し、生成されたWSDLにあなたのコードのXMLコメントのライブエクスポートすることができます
docsからの抜粋:
ソースコードからのWSDLドキュメントの追加コメント この拡張子では、ソースファイルのXMLコメントからWSDLドキュメント(annotation)を直接追加することができます。これらのコメントは、WSDLの一部として公開され、WSDLツール(たとえばApache Axis wsdl2javaなど)を活用する方法を理解しているツールで利用できます。リリース2.0には、生成されたプロキシコード内のWSDLコメントをXMLコメントに変換するクライアント側WSDLインポータも含まれています。
- 1. C++でインターフェイスを通過する最も良い方法は?
- 2. AMD + Backbone + JSDoc3を文書化する最良の方法
- 3. UITableViewのインデックスをアニメーション化する最も良い方法は?
- 4. f#コードを文書化する最良の方法は何ですか?
- 5. ソフトウェア最適化を学ぶ最も良い方法
- 6. wcfクライアントを使用する最も良い方法は何ですか? (メモリワイズ)
- 7. WCF Web APIをバージョンアップする最も良い方法は何ですか?
- 8. .NETでRESTfulなサービス "クライアント"を書く最も良い方法は?
- 9. イメージにテキストを書き込む最も良い方法は?
- 10. よく書かれていないWebサービスを文書化する最良の方法は何ですか?
- 11. インターフェイスを使用して読み書きの問題を分ける最も良い方法は?
- 12. Compact FrameworkでWCFを使用して保護する最も良い方法は?
- 13. Silverlight/C# - WCFデータを動的にロードする最も良い方法は?
- 14. jsonの文字列を暗号化/復号化する最も良い方法は何ですか
- 15. 文字列のXMLスニペットをXML文書に追加する最も良い方法は?
- 16. ベクトルsvgファイルのサイズを最小化する最も良い方法
- 17. Clearcaseで最も良い方法は?
- 18. 何千ものif文を避ける最良の方法は?
- 19. 複数の文書の類似性に基づいて文章をランク付けする最も良い方法
- 20. ASP/ASP.NET書き込み権限を処理する最も良い方法は?
- 21. 開発とQA部門のチームワークを強化する最も良い方法は?
- 22. WPFアプリケーションの非ビジュアルメソッドを構造化する最も良い方法は?
- 23. jQueryが必要なJavaScriptライブラリをパッケージ化する最も良い方法は?
- 24. Androidアプリケーションで大量のテキストデータを暗号化する最も良い方法は?
- 25. セグメント化されたプログレスバーを作成する最も良い方法は?
- 26. .NETで短い文字列を暗号化する最も良い方法は何ですか?
- 27. PowerShellのコンソールに書き込む最も良い方法
- 28. Python/Pandas - 条件別にグループ化する最も良い方法は?
- 29. RubyでWord文書の形式でファイルをプログラムで出力する最も良い方法は何ですか?
- 30. 文書内のgridFSファイルへの参照を格納する最も良い方法は何ですか?
WCFExtrasの実装は優れた選択肢です。 – TylerY86
[elaboration] XML文書を直接記述子に結びつけます。 XMLドキュメントを使用するのが適切ですが、SandcastleまたはSHFBはスタンドアロンのドキュメントには絶対的に適していますが、WCFExtrasと同様のサードパーティですが、シナリオは限定されていません。 – TylerY86