Generar documentación de WCF usando SandCastle

Question

Estoy intentando generar documentación externa para un servicio de WCF usando SandCastle. ¿Cómo puedo decirle a SandCastle que use los atributos de WCF como ServiceContract para nombrar las funciones y entidades en lugar de los nombres que tienen en el ensamblaje?

Answer 1

OK, la siguiente no será una respuesta directa a su pregunta, pero tal vez ayude de todos modos.

Si está diciendo que desea crear "documentación de servicio externo", esa documentación externa probablemente no está destinada realmente a desarrolladores .NET y puede que ni siquiera quiera que los detalles de implementación sean (necesariamente) visibles. Por lo tanto, la documentación típica del estilo API puede no ser adecuada de todos modos.

Junto a esa documentación de estilo API, Sandcastle también admite lo que se denomina "documentación conceptual". Que es básicamente "texto libre", por supuesto en un cierto dialecto XML. Volveré a eso más tarde.

OK, primero generar un archivo WSDL para sus interfaces de servicio (normalmente añadiendo ?WSDL a la URI del servicio o el uso de SVCUTIL.EXE en su conjunto del servicio, que se adapta mejor durante una construcción automatizado).

Luego viene la parte difícil. Necesitaría crear algo que convierta el WSDL a documentos MAML (me viene a la mente una hoja de estilo XML). MAML (lenguaje de marcado de asistencia de Microsoft) es en realidad el formato central utilizado por Sandcastle.

Creo que su mejor opción sería utilizar el Sandcastle Helpfile Builder para crear un proyecto a partir de estos archivos y crear un CHM, páginas HTML o lo que sea.

Básicamente, una vez que tiene los documentos MAML, vuelve a estar en la cadena de herramientas "estándar" de Sandcastle.

Sé que parece bastante trabajo, y probablemente lo sea. He hecho algo comparable en el pasado, donde usaría SMO para consultar una base de datos SQL Server para generar documentos MAML para las tablas, procedimientos, etc. para generar documentación de referencia. En realidad, funcionó bastante bien y al final el esfuerzo no fue tan malo.

De todos modos, voy a seguir esa pregunta quedó en caso de que exista realmente un "off the shelf" solución :-)