Generar archivos de documentación (.chm) para programas desarrollados en C# usando SandCastle

Generar archivos de documentación (.chm) para programas desarrollados en C# usando SandCastle

Una pequeña introducción

Los principios de la programación orientada a objetos nos dicen que debemos programar de tal manera que agrupemos métodos y atributos que puedan ser aplicados a un objeto y que dicho objeto pueda ser utilizado y reutilizado de forma eficiente, una de las formas más eficientes para la reutilización de código es la creación de librerías o paquetes, en el caso de C# se llaman librerías y tienen la extensión .dll, las cuales pueden ser utilizadas posteriormente en otra aplicación y por otra persona, pero ya sea que creémos o no una librería, habrá momentos en los que querramos volver a utilizar un segmento de código desarrollado anteriormente y para ello debemos tener en mente la forma en que este código trabaja, esto es una razón muy importante entre otras para documentar nuestro código. Personalmente no lo consideraba tan importante hasta que tuve la necesidad de reutilizar mi código y entonces tuve que volver a estudiarlo en parte para recordar cómo trabajaba, qué hacía cada método y qué representaba cada parámetro de entrada, pero bueno, de ahora en adelante documentaré bien mis programas y librerías para que esto no vuelva a pasar :).

Entremos en materia:

Dentro del entorno de programación IDE de C# como Visual Studio 2010, un comentario se escribe simplemente escribiendo en el renglón superior de la porción a documentar tres veces el símbolo slash (///), esto solicitará la descripción de los datos correspondientes, se puede documentar en general cualquier parte

del código que se requiera, pero la parte principal son los constructores, métodos y atributos. para mayor información de cómo documentar y las etiquetas permitidas referirse a la página web: http://msdn.microsoft.com/es-es/library/b2s063f7(v=vs.100).aspx

El motivo de esta entrada es compartir una aplicación que me pareció muy buena para generar los archivos de ayuda de forma similar a una API, esta aplicación se llama SandCastle, así que explicaré sus funciones básicas (que realmente fué las que utilicé) y la forma de trabajar con él:

Primero que todo la página oficial del proyecto es: http://shfb.codeplex.com/

Una vez se descargue su más reciente versión (Microsoft dejó de mantener este software desde el año 2010 , pero el proyecto ha sido acogido  por codePlex) simplemente abrimos el instalador y seguimos las sencillas instrucciones y tenemos SandCastle instalado!

El siguiente paso para documentar nuestro software es indicarle al IDE de programación  que queremos que se genere el archivo XML con la representación de los comentarios (los cuales han sido incluidos en el archivo editor de la clase, anteponiendo ). Vamos al menú proyecto-> propiedades->build y buscamos la opción "XML Documentation File", activamos el checkbox si es el caso e indicamos el path relativo donde queremos que el archivo .xml sea generado. (El path o ruta es relativo con respecto al directorio de ubicación del proyecto, a mí me parece mejor indicar el path donde se genera el archivo dll en el caso de una librería por facilidad de acceso)

Listo, ahora cada vez que compilemos el proyecto, este archivo xml se actualizará  y podemos usar SandCastle para generar el archivo de ayuda basándose en él. 

Abrimos SandCastle, creamos un proyecto (File-new project) y obtendremos la pantalla de bienvenida y presentación donde en la parte izquierda tenemos las propiedades del proyecto, (aquí hay mucho por explorar, desde colocar la referencia al copyright, notas aclaratorias y opciones de visualización) pero para generar un archivo básico inicialmente estos parámetros pueden ser ignorados, lo importante por ahora es indicarle a SandCastle en qué lugar se encuentran ubicados nuestros archivos fuente para la documentación, esto se hace dando click derecho al elemento "Documentation Sources" y posteriormente a "Add Documentation Source", vamos al lugar donde se generó el archivo dll y lo seleccionamos, el archivo .xml también debe ser agregado, es por esta razón que recomendé ubicar el archivo .xml en el mismo directorio donde se genera el archivo .dll, En este caso al hacer doble click sobre alguno de ellos el otro se agregará automáticamente, la pantalla en este punto del proceso debe ser similar a la siguiente:

Una vez tengamos esto simplemente damos click en el botón de compilar o construir y listo, el archivo tardará un poco en generarse dependiendo de nuestro computador y el tamaño del proyecto. El archivo de ayuda .chm quedará guardado en el path que le indicamos al proyecto en SandCastle dentro de una carpeta por defecto llamada "help".

Espero les haya sido útil. Gracias :)

Conectar Java a una base de datos Access

En este documento se explicará como realizar una conexión básica a una base de datos de Microsoft access desde JAVA, el procedimiento aquí contenido aplica para cualquier tipo de base de datos siempre y cuando se disponga del driver adecuado, ya que el código de Java en sí no presenta muchas variaciones al cambiar el tipo de base de datos (BD), únicamente se debe especificar el driver y el DSN(Database Source Name) para el acceso a  la BD. En esta entrada se indica como configurar el driver y el DSN en un sistema operativo  windows.

Primero que todo diré muy resumidamente que un driver realiza  una función de traductor entre Java y el lenguaje de acceso a las bases de datos, existen contenedores de drivers, entidades de software capaces de contener varios driver y brindar esa función para facilitar al programador la gestión de los drivers con los que cuenta y los DSN, una vez creado un DSN, asociarlo a un driver y hacerlo accesible desde Java, el programador puede acceder a la base de datos usando sentencias de SQL.

Para empezar debemos configurar el anteriormente mencionado contenedor de drivers, en este ejemplo utilizaremos el JDBC-ODBC (Java Data base Conector)- (Open Data Base Conector) que viene de manera predeterminada con el JDK (Java Development Kit), puede contener un número considerable de drivers y es gratuito. (También existen drivers que pueden ser más eficientes pero no son gratuitos y requieren un pago y/o licencia).

Se explicará la forma de configurar el JDBC en windows. Primero iremos a Panel de Control, la ruta de acceso podría variar de acuerdo a la versión de windows que se use, por ejemplo, en windows vista accedemos desde la pantalla principal del panel de control a sistema y mantenimiento, una vez ahí dentro buscamos "herramientas administrativas", y luego vamos a "orígenes  de datos ODBC", pero la ruta debe ser muy similar en otras versiones de windows, una forma fácil de acceder es ingresar a panel de control y desde la pantalla principal escribir en el campo de búsqueda "ODBC", el sistema le mostrará la ubicación de la herramienta de configuración de ODBC y se podrá acceder a ella, a continuación se muestra un screenshot que lo ilustra:

 

Ahora entramos dando click a "configurar orígenes de datos(ODBC)" y damos privilegios de usuario si son requeridos y obtendremos la siguiente pantalla:

Nuestro objetivo es crear un DSN al cual hacer referencia desde java, por esta razón seleccionamos la pestaña "DSN de usuario" en caso de no salir seleccionada por defecto, luego hacemos click en "agregar", el sistema nos solicitará que indiquemos el tipo de driver a utilizar, el cual depende del tipo de base de datos, en nuestro caso es una base de datos de Microsoft Access por lo tanto seleccionamos el driver correspondiente, verificamos la extensión del archivo, (los archivos de access tienen una extensión .mdb):

A continuación nos pedirá el ingreso del nombre del origen de datos, es decir, el DSN, el cual será utilizado como identificador en la conexión de Java con la DB, no necesariamente debe coincidir con el nombre de la base de datos, el campo descripción es opcional y es para describir la función del driver y documentación, si se requiere una autenticación para ingresar a la base de datos vamos a la casilla ("avanzadas..") y especificamos los campos necesarios correspondientes al nombre de usuario y contraseña.

 Damos click en seleccionar para indicar cual será la base de datos asociada a ese DSN, luego buscamos el directorio de nuestra base de datos y damos click en aceptar. Ahora nos debe salir en la pantalla de los DSN nuestro nuevo nombre de origen de datos, en mi caso curso1 ( el cual corresponde a un ejemplo dado en un curso de aprendizaje virtual del SENA que tomé). Una vez hecho esto ya podemos hacer uso de este DSN para desde Java consultar y modificar la base de datos.

Primero que todo importamos el paquete java.sql, para ver sus especificaciones y  las clases que ofrece puede consultarse la página: http://download.oracle.com/javase/7/docs/api/ , aquí encontrará la API (Application Programmer Interface) que ofrece una descripción de las clases, interfaces y los métodos disponibles en Java.

Esto se hace por medio de la sentencia import java.sql.*; 

navegando por la API podemos observar cuatro de las clases que utilizaremos en el programa:

• DriverManager: utilizado para cargar los drivers
• Connection: para establecer las conexiones a las bases de datos.
• Statement: Por medio de esta clase enviamos consultas en el lenguaje de bases de datos
• ResultSet: Esta clase almacena el resultado de las consultas generadas por un Statement.

La estructura de un programa básico que únicamente consulte una base de datos es la siguiente

se debe disponer de una base de datos que tenga una tabla que se llame "lista" en donde hallan dos columnas, una donde se almacene el nombre de un trabajador (String) y otra donde se almacene su sueldo(double)

//importamos el paquete de Java que permite usar las clases que nos comunican con la base de datos
import java.sql.*;   


public class BaseDeDatos{
   
   
    public static void main(String[] args){
//indicamos el contenedor driver que usaremos     
        try{
            Class.forName("sun.jdbc.odbc.JdbcOdbcDriver");
        }catch(ClassNotFoundException ex){
            System.out.println(ex.getMessage());
        }

// con este bloque imprimiremos en consola la lista de drivers disponibles:

            Enumeration<Driver> misdrivers = DriverManager.getDrivers();
            while (misdrivers.hasMoreElements() == true){
                System.out.println(misdrivers.nextElement());
            }
// Creamos la conexión a la base de datos, aquí es importante cambiar la parte donde dice "nombreorigen" por el DSN  que se especificó en la configuración del ODBC 
        try{
            Connection conexion = DriverManager.getConnection("jdbc:odbc:nombreorigen","jdbc","jddb");
            Statement estatuto = conexion.createStatement();

//se ejecuta una consulta en el stament y se almacena el resultado en la variable rs, la cual pertenece a la clase //ResultSet, la consulta se ejecuta sobre una tabla llamada "lista", la cual  debe existir para que no se arroje //una excepción

            ResultSet rs = estatuto.executeQuery("select * FROM lista");                               
            while(rs.next()){
               /*al dar rs.next(), accedemos al siguiente elemento de los resultados, es decir, a la siguiente "fila" o registro, podemos acceder a cada uno de sus diferentes campos, "columnas" conociendo el tipo de datos que contiene, es decir, si es una cadena, un entero, un caracter, etc.. y el nombre o índice que identifica a esa columna, es importante saber que la primera columna recibe el índice de 1, (el 0 no existe y si tratamos de acceder a la columna 0 nos daría error), teniendo esto como base y suponiendo que la tabla contiene dos columnas, una con un nombre (tipo string) y otra con un sueldo (tipo double), podemos acceder a sus elementos de la siguiente forma:

*/

String nombre = rs.getString(1); //porque el nombre es de tipo string y está contenido en la columna 1
double sueldo = rs.getDouble(2); //porque el sueldo es tipo double y está en la columna 2
System.out.println("el trabajador es: "+ nombre + " y gana "+ sueldo);

//también es posible acceder a los resultados si se conoce el nombre de la columna:

String nombre = rs.getString("nombre)";

// Ya tenemos los datos en nuestro poder y podemos hacer lo que queramos con ellos.

            } //fin del while

//Una vez obtenidos nuestros datos cerramos tanto el statement como la connection que abrimos.   

            estatuto.close();
            conexion.close();

//En caso de no poder ejecutar el Query Java nos enviará una excepción la cual debemos atrapar

        }catch(SQLException     e){
            System.out.println(e.getMessage());
        }
       
    }// fin main
} //fin clase

una de las partes más importantes del programa es la siguiente:

ResultSet rs = estatuto.executeQuery("select * FROM lista");
El método executeQuery de la clase statement recibe como parámetro una cadena que represente una consulta válida en SQL, por lo tanto ese "select* FROM lista" dado como ejemplo puede ser cambiado por cualquier consulta válida.

Se indicó como realizar consultas en una base de datos utilizando Java y JDBC, en una entrada posterior se indicará como modificar tablas en las bases de datos.