Documentación viva con VSTO

Todo proyecto de IT debe ir acompañado de una documentación útil, a ser posible actualizada, en cualquier caso pertinente. Aunque documentar no es la parte más divertida para un desarrollador, somos responsables de esta tarea en distintos niveles, empezando por el propio código.Por ello quiero atraer la atención hacia una tecnología de Microsoft que tiene una extraordinaria potencia a la hora de crear documentación viva. Se trata de Visual Studio Tools for Office (VSTO), con la cual es posible ejecutar código C# (código manejado) al abrir un documento de la suite Microsoft Office, como Word o Excel. VSTO alberga todo un conjunto de herramientas con las que se puede tanto editar de forma dinámica un único documento (document-level customizations) como modificar el comportamiento de la propia aplicación (VSTO add-ins).

¿Pero para qué usar VSTO?

Para mantener la fuente de la documentación dentro de la propia solución. De esta manera se evita la disgregación y se permite la consulta (manual o mediante código) de los datos y la información de los que se nutre.
Crear una documentación viva, actualizada de forma permanente. Gracias a la tecnología VSTO es posible consultar mediante código las bases de datos, los archivos de metadatos o el propio código en C#, asegurándose de que la información obtenida está en la versión más reciente.
Estandarizar la documentación y ofrecer la posibilidad de incluir el proyecto de documentación dentro de una plantilla.

Ejemplo de VSTO con Word

Voy a mostrar un ejemplo completo de cómo leer un archivo “.dacpac” (data-tier application package), en donde se guardan todos los objetos de una base de datos SQL Server, y a mostrarlos en una tabla con formato generada automáticamente dentro de un documento de Word. Este documento podría formar parte de la documentación de una solución que incluyera un proyecto de base de datos SQL Server.

Sobre el proyecto de base de datos, comentaré que tiene una Target platform SQL Server 2012 y en base a él he creado mi DACPAC de ejemplo. Todo está incluido en la solución.

Como siempre, he subido el código a GitHub y puedes descargarlo desde este enlace. En él hay numerosos comentarios para facilitar su comprensión. En este artículo voy a esbozar el dibujo general, mencionando algunos métodos y clases interesantes.

El archivo ThisDocument.cs

Por cada proyecto VSTO añadido existe un único documento «.docx», y vinculado a él hay un archivo «ThisDocument.cs». Este archivo contiene la definición parcial de la clase ThisDocument.

Esta clase contiene los métodos ThisDocument_Startup() y ThisDocument_Shutdown(), que son lanzados al abrir y al cerrar el documento respectivamente. En estos métodos se añade la lógica que realiza las modificaciones dinámicas en el propio documento.
Dentro de estos métodos es posible acceder al documento vinculado y efectuar cualquier acción que puead hacerse desde el propio Word. Por ejemplo:

Desactivar el análisis de ortografía y gramática:

this.ShowSpellingErrors = false;
this.ShowGrammaticalErrors = false;

Actualizar la (única) tabla de contenidos:

TablesOfContents[1].Update();

Obtener la posición de un marcador en el documento e insertar texto a continuación:

Word.Range range = this.Bookmarks[«MarcadorEnElDocumento»].Range.Next();
range.Text = «Texto»;

La forma de editar texto en un documento de Word es por medio del objeto Range. Range contiene métodos para realizar cualquier operación con texto, como añadir, copiar, pegar, seleccionar, formatear, etc. También mediante Range se puede actuar sobre cualquier otro contenido de un documento de Word, como tablas, imágenes…

Después de este aperitivo, os invito a descargaros el ejemplo de GitHub y experimentar con VSTO. Con esta tecnología, las posibilidades de mejorar la documentación de nuestros proyectos en .NET son enormes.

Pedro Pinto Sogeti Pedro Pinto