Por lo tanto, estoy usando WCF y quiero documentar mi (s) interfaz (es) y servicios para entregar a otra compañía una aplicación interna. ¿Cuál es la mejor manera de documentar esas interfaces? Preferiría tener la documentación en línea con el código, y luego tener algo embellecido para producir HTML, pero no estoy seguro de si hay una manera recomendada de hacerlo.¿La mejor manera de documentar la interfaz WCF?
Utilice documentos XML para eso. Hay muchas metaetiquetas inteligentes que le permitirán poner muestras de código en ellas, referencias entre operaciones, excepciones lanzadas, etc.
Luego puede usar Sandcastle (+ alguna GUI que puede encontrar en Codeplex) para generar cualquiera chm, o html documentación.
Usar el resultado XML del compilador es agradable ... pero según mi experiencia es difícil expresar la complejidad completa de un servicio y se esperan invariantes, dependencias, etc. solo en los comentarios. Es mejor que mantenga un documento real separado (Word, HTML, Wiki) para cubrirlo todo.
Uso dos archivos XSL, uno para documentar el WSDL para las operaciones, uno para documentar el XSD para los datos que se pasan.
Lamentablemente, hasta ahora, no he encontrado una sola solución coherente, así que trabajo con dos archivos XSLT que transforman el WSDL y el XSD respectivamente en documentación HTML.
WSDL Viewer hace el trabajo para el WSDL y produce un primer documento HTML, y xs3p hace lo mismo con los datos que contiene el archivo XSD.
Pondré mi contrato de interfaz en un dll común y lo entregaré. Les proporciona los comentarios xml del contrato sin dar los detalles del servicio y les permite implementar el servicio en un modo fuera de línea para probarlo hasta que estén listos para usarlo. Además de eso, pueden omitir el wsdl y usar ChannelFactory para crear un canal.
Utilizamos WCFExtras (http://www.codeplex.com/WCFExtras) para eso.
Entre otras características permite exportar en vivo de su código XML comentarios en el WSDL generado, por ejemplo, comprobar cómo estos comentarios 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);
se reflejan en el WSDL de la interfaz:
<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 extracto de sus documentos:
Agregar documentación WSDL del código fuente XML Comentarios Esta extensión permite s usted para agregar documentación WSDL (anotación) directamente desde comentarios XML en su archivo fuente. Estos comentarios se publicarán como parte del WSDL y están disponibles para las herramientas WSDL que saben cómo aprovecharlas (por ejemplo, Apache Axis wsdl2java y otros). La versión 2.0 también incluye un importador WSDL del lado del cliente que convertirá esos comentarios WSDL en comentarios XML en el código proxy generado.
¿También aparecerá en el IDE? Al igual que en Intellisense de Visual Studio? – Farinha
Por si acaso alguien encuentra esto, lo último es [aquí] (https://wcfextrasplus.codeplex.com).También puede descargar usando [nuget] (https://www.nuget.org/packages/WCFExtrasPlus/2.4.0). – Joyce
Aunque no es inmediatamente evidente, el comentario anterior hace referencia a WCFExtras +, un proyecto diferente, pero una continuación del trabajo sobre WCFExtras. Buen material. – TylerY86
La implementación de WCFExtras es la mejor opción. – TylerY86
[elaboración] Vincula los documentos XML al descriptor directamente. Usar XML docs es apropiado, pero mientras que Sandcastle o SHFB son absolutamente apropiados para la documentación independiente, es tan solo de terceros como WCFExtras, pero menos específico de un escenario. – TylerY86