Quindi sto utilizzando WCF e desidero documentare le mie interfacce e i servizi da fornire a un'altra azienda per un'app interna. Qual è il modo migliore per documentare queste interfacce? Preferirei avere la documentazione in linea con il codice, e quindi avere qualcosa di utile per l'output HTML, ma non sono sicuro se c'è un modo consigliato per farlo.Il modo migliore per documentare l'interfaccia WCF?
Utilizzare documenti XML per questo. Ci sono molti meta-tag intelligenti che ti permetteranno di inserire esempi di codice, riferimenti tra operazioni, eccezioni generate ecc.
Quindi puoi usare Sandcastle (+ qualche GUI che puoi trovare su Codeplex) per generare chm o documentazione html.
L'utilizzo dell'output XML dal compilatore è piacevole ... ma è stata la mia esperienza che è difficile esprimere la completa complessità di un servizio e le sue invarianti, dipendenze, ecc. Nei commenti da soli. È meglio mantenere un documento reale separato (Word, HTML, Wiki) per coprire tutto.
Io uso due file XSL: uno per documentare il WSDL per le operazioni, uno per documentare l'XSD per i dati passati.
Purtroppo, finora, non ho trovato una soluzione coesiva, quindi lavoro con due file XSLT che trasformano rispettivamente il WSDL e l'XSD nella documentazione HTML.
WSDL Viewer esegue il lavoro per WSDL e produce un primo documento HTML e xs3p fa lo stesso per i dati contenuti nel file XSD.
Inserirò il mio contratto di interfaccia in una DLL comune e lo consegnerò. Fornisce a entrambi i commenti xml sul contratto senza fornire i dettagli del servizio e consente loro di implementare il servizio in modalità offline per testare fino a quando non sono pronti per usarlo. Inoltre, possono bypassare wsdl e utilizzare ChannelFactory per creare un canale.
Per questo utilizziamo WCFExtras (http://www.codeplex.com/WCFExtras).
Tra le altre caratteristiche che permette di esportare in diretta del codice commenti XML nel WSDL generato, ad esempio, verificare come questi commenti 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);
vengono riflessi nel WSDL di tale interfaccia:
<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>
Un estratto dai loro documenti:
Aggiunta di documentazione WSDL dal codice sorgente Commenti XML Questa estensione consente s per aggiungere la documentazione WSDL (annotaiton) direttamente dai commenti XML nel file sorgente. Questi commenti saranno pubblicati come parte del WSDL e sono disponibili per gli strumenti WSDL che sanno come trarne vantaggio (ad esempio Apache Axis wsdl2java e altri). La versione 2.0 include anche un importatore WSDL lato client che trasformerà i commenti WSDL in commenti XML nel codice proxy generato.
Apparirà anche nell'IDE? Come in Intellisense di Visual Studio? – Farinha
Nel caso in cui qualcuno lo trovi, l'ultimo è [qui] (https://wcfextrasplus.codeplex.com).Puoi scaricare usando [nuget] (https://www.nuget.org/packages/WCFExtrasPlus/2.4.0). – Joyce
Anche se non è immediatamente evidente, il commento sopra fa riferimento a WCFExtras +, un progetto diverso, ma una continuazione del lavoro su WCFExtras. Roba buona. – TylerY86
L'implementazione di WCFExtras è l'opzione superiore. – TylerY86
[elaborazione] Lega direttamente i documenti XML al descrittore. L'uso di documenti XML è appropriato, ma mentre Sandcastle o SHFB sono assolutamente appropriati per la documentazione standalone, è solo di terze parti come WCFExtras, ma meno specifico per lo scenario. – TylerY86