Il modo migliore per documentare l'interfaccia WCF? [chiuso]

StackOverflow https://stackoverflow.com/questions/823148

Domanda

Quindi sto usando WCF e desidero documentare le mie interfacce e i miei servizi da fornire a un'altra società per un'app interna. Qual è il modo migliore per documentare quelle interfacce? Preferirei avere la documentazione in linea con il codice, e quindi avere qualcosa di appropriato per l'output di HTML, ma non sono sicuro che ci sia un modo consigliato per farlo.

È stato utile?

Soluzione

Usa 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 (+ alcune GUI che puoi trovare su Codeplex) per generare documentazione chm o html.

Altri suggerimenti

Per questo utilizziamo WCFExtras ( http://www.codeplex.com/WCFExtras ).

Tra le altre funzionalità, consente l'esportazione live dei commenti xml del codice nel WSDL generato, ad esempio controllare 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);

rifletti nel WSDL di quell'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 della documentazione WSDL dai commenti XML del codice sorgente Questa estensione consente di aggiungere la documentazione WSDL (annotaiton) direttamente dai commenti XML nel file di origine. Questi commenti saranno pubblicati come parte del WSDL e sono disponibili per gli strumenti WSDL che sanno come trarne vantaggio (ad es. Apache Axis wsdl2java e altri). La versione 2.0 include anche un importatore WSDL lato client che trasformerà tali commenti WSDL in commenti XML nel codice proxy generato.

Uso due file XSL: uno per documentare il WSDL per le operazioni, uno per documentare l'XSD per i dati che vengono passati.

Sfortunatamente, finora, non ho trovato un'unica soluzione coerente, quindi lavoro con due file XSLT che trasformano rispettivamente WSDL e XSD in documentazione HTML.

Visualizzatore WSDL fa il lavoro per il WSDL e produce un primo documento HTML e xs3p fa lo stesso per i dati contenuti nel file XSD.

Usare l'output XML dal compilatore è bello ... ma è stata la mia esperienza che è difficile esprimere la completa complessità di un servizio e si prevede invarianti, dipendenze, ecc. solo nei commenti. Stai meglio mantenendo un documento reale separato (Word, HTML, Wiki) per coprire tutto.

Metterò il mio contratto di interfaccia in una dll comune e lo distribuirò. Fornisce loro entrambi i commenti XML sul contratto senza fornire i dettagli del servizio, oltre a consentire loro di implementare il servizio in modalità offline per i test fino a quando non sono pronti per usarlo. Inoltre, possono bypassare wsdl e utilizzare ChannelFactory per creare un canale.

Autorizzato sotto: CC-BY-SA insieme a attribuzione
Non affiliato a StackOverflow
scroll top