Capítulo 16: Ejecutar un comando simple

Parte II: Primeros pasos con EPLAN API - Sección 6: CommandLineInterpreter básico - Nivel: Principiante

Objetivos de aprendizaje

Al finalizar este capítulo serás capaz de:

Entender qué es CommandLineInterpreter y para qué sirve
Crear una instancia de CommandLineInterpreter
Ejecutar comandos básicos de EPLAN
Conocer la estructura de un comando simple
Manejar errores en ejecución de comandos

Requisitos previos

Antes de comenzar este capítulo debes:

Haber completado los Capítulos 12-15 (atributos de scripting)
Conocer el atributo [Start]
Entender try-catch para manejo de errores

Introducción

Hasta ahora has aprendido a estructurar scripts con diferentes atributos ([Start], [DeclareAction], etc.), pero todos tus scripts solo mostraban mensajes al usuario.

¿Cómo puedes hacer que EPLAN realmente haga algo? ¿Cómo ejecutas las acciones que normalmente harías desde los menús o botones de EPLAN?

La respuesta es: CommandLineInterpreter.

1. ¿Qué es CommandLineInterpreter?

1.1 Definición

CommandLineInterpreter (CLI) es una clase de EPLAN API que permite ejecutar acciones de EPLAN programáticamente, como si las ejecutaras desde el menú o la línea de comandos de EPLAN.

Analogía: Es como tener acceso a la consola de comandos de EPLAN desde tu código.

1.2 ¿Dónde se define?

CommandLineInterpreter está en el namespace:

using Eplan.EplApi.ApplicationFramework;

1.3 ¿Para qué sirve?

Con CommandLineInterpreter puedes ejecutar cualquier acción disponible en EPLAN:

Abrir reportes
Guardar proyectos
Generar conexiones
Exportar documentos
Sincronizar datos
Y muchas más…

Importante: Solo puedes ejecutar acciones que ya existen en EPLAN. No puedes inventar comandos nuevos (aunque sí puedes crear acciones personalizadas con [DeclareAction]).

2. Tu primer comando con CommandLineInterpreter

2.1 Script más simple posible

Este ejemplo está basado directamente en EPLAN-Scripting-4.0/02_RunActions/01_SingleAction.cs:

using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Scripting;

public class ComandoSimple
{
    [Start]
    public void Function()
    {
        CommandLineInterpreter cli = new CommandLineInterpreter();
        cli.Execute("check");
    }
}

2.2 Análisis línea por línea

Línea 1-2: Namespaces necesarios

using Eplan.EplApi.ApplicationFramework;  // Para CommandLineInterpreter
using Eplan.EplApi.Scripting;             // Para [Start]

Línea 9: Crear instancia de CLI

CommandLineInterpreter cli = new CommandLineInterpreter();

Crea un objeto que puede ejecutar comandos de EPLAN.

Línea 10: Ejecutar comando

cli.Execute("check");

Ejecuta el comando “check”, que verifica el proyecto en busca de errores.

2.3 ¿Qué hace este script?

Al ejecutar este script:

Se crea un CommandLineInterpreter
Se ejecuta el comando “check”
EPLAN verifica el proyecto en busca de errores

Es equivalente a ir manualmente a: Utilidades > Verificar > Verificar proyecto

3. Estructura básica de Execute()

3.1 Sintaxis

cli.Execute(string actionName);

Parámetros:

actionName - String con el nombre de la acción a ejecutar

Valor de retorno:

bool - true si el comando se ejecutó correctamente, false si falló

3.2 Ejemplo con validación de retorno

using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Scripting;
using System.Windows.Forms;

public class ComandoConValidacion
{
    [Start]
    public void Function()
    {
        CommandLineInterpreter cli = new CommandLineInterpreter();

        bool resultado = cli.Execute("check");

        if (resultado)
        {
            MessageBox.Show("Comando ejecutado correctamente");
        }
        else
        {
            MessageBox.Show("Error al ejecutar comando");
        }
    }
}

4. Comandos verificados en scripts oficiales

Estos son comandos que aparecen en los scripts oficiales de EPLAN-Scripting-4.0:

4.1 check

Comando: check Qué hace: Verifica el proyecto en busca de errores Equivalente en menú: Utilidades > Verificar > Verificar proyecto

CommandLineInterpreter cli = new CommandLineInterpreter();
cli.Execute("check");

4.2 generate

Comando: generate Qué hace: Genera conexiones y numeración del proyecto

CommandLineInterpreter cli = new CommandLineInterpreter();
cli.Execute("check");

Nota: La acción check soporta parámetros como TYPE (“PROJECT”, “PAGES”) y VERIFICATIONSCHEME que veremos en capítulos posteriores.

5. Buenas prácticas

5.1 Siempre usar try-catch

Los comandos pueden fallar por diversas razones (proyecto no abierto, permisos, etc.). Siempre maneja errores:

using System;
using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Scripting;
using System.Windows.Forms;

public class ComandoSeguro
{
    [Start]
    public void Function()
    {
        try
        {
            CommandLineInterpreter cli = new CommandLineInterpreter();
            bool resultado = cli.Execute("check");

            if (!resultado)
            {
                MessageBox.Show("El comando no se pudo ejecutar");
            }
        }
        catch (Exception ex)
        {
            MessageBox.Show("Error: " + ex.Message);
        }
    }
}

5.2 Crear la instancia de CLI una sola vez

Si vas a ejecutar varios comandos, crea el CLI una sola vez:

Mal:

new CommandLineInterpreter().Execute("check");
new CommandLineInterpreter().Execute("generate");

Bien:

CommandLineInterpreter cli = new CommandLineInterpreter();
cli.Execute("check");
cli.Execute("generate");

5.3 Verificar que hay proyecto abierto si es necesario

Muchos comandos requieren que haya un proyecto abierto:

using Eplan.EplApi.Base;
using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Scripting;
using System.Windows.Forms;

public class ComandoConVerificacion
{
    [Start]
    public void Function()
    {
        // Verificar que hay proyecto abierto
        string nombreProyecto = PathMap.SubstitutePath("$(PROJECTNAME)");

        if (string.IsNullOrEmpty(nombreProyecto) || nombreProyecto.StartsWith("$("))
        {
            MessageBox.Show("No hay proyecto abierto");
            return;
        }

        // Ejecutar comando
        CommandLineInterpreter cli = new CommandLineInterpreter();
        cli.Execute("check");
    }
}

6. ¿Cómo descubrir nombres de comandos?

Esta es una pregunta común: ¿Cómo sé qué comandos puedo ejecutar?

6.1 Fuentes de información

1. Documentación oficial de EPLAN API

Archivo: EplanAPI.chm (en carpeta de instalación)
Busca por “Actions” o nombres de comandos

2. Scripts de ejemplo oficiales

Carpeta: EPLAN-Scripting-4.0
Muchos scripts usan CommandLineInterpreter

3. Observar la interfaz de EPLAN

Muchas acciones del menú tienen nombres internos
No siempre coinciden exactamente con el texto del menú

4. Trial and error con validación

Prueba comandos y verifica el valor de retorno

6.2 Comandos verificados en documentación oficial

Estos comandos están documentados en la API oficial de EPLAN:

check - Verificar proyecto
generate - Generar conexiones y numeración
compress - Comprimir proyecto
synchronize - Sincronizar datos maestros (requiere parámetro TYPE)
export - Exportar (requiere parámetros, lo veremos en capítulos siguientes)
backup - Crear copia de seguridad (requiere parámetros)

7. Proyecto del capítulo: Verificar proyecto automáticamente

7.1 Objetivo

Crear un script que verifique el proyecto de EPLAN en busca de errores.

7.2 Implementación

using System;
using System.Windows.Forms;
using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Scripting;

public class VerificarProyecto
{
    [Start]
    public void Function()
    {
        try
        {
            // Crear intérprete de línea de comandos
            CommandLineInterpreter cli = new CommandLineInterpreter();

            // Ejecutar comando para verificar proyecto
            bool resultado = cli.Execute("check");

            // Verificar resultado
            if (resultado)
            {
                MessageBox.Show(
                    "Verificación del proyecto completada",
                    "Éxito",
                    MessageBoxButtons.OK,
                    MessageBoxIcon.Information
                );
            }
            else
            {
                MessageBox.Show(
                    "No se pudo verificar el proyecto",
                    "Error",
                    MessageBoxButtons.OK,
                    MessageBoxIcon.Warning
                );
            }
        }
        catch (Exception ex)
        {
            MessageBox.Show(
                "Error al ejecutar comando:\n" + ex.Message,
                "Error",
                MessageBoxButtons.OK,
                MessageBoxIcon.Error
            );
        }
    }
}

8. Limitaciones de comandos simples

8.1 Sin parámetros

Con Execute(string) solo puedes ejecutar comandos sin parámetros.

Para comandos que necesitan parámetros (como exportar a una ruta específica), necesitas ActionCallingContext, que veremos en el Capítulo 18.

8.2 Nombres exactos

Los nombres de comandos son case-sensitive y deben ser exactos:

cli.Execute("check");   // ✓ Funciona
cli.Execute("Check");   // ✗ Puede no funcionar
cli.Execute("CHECK");   // ✗ Puede no funcionar

8.3 Estado de EPLAN

Algunos comandos solo funcionan en ciertos contextos:

Proyecto abierto
Página seleccionada
Modo de edición activo
Etc.

Siempre verifica las precondiciones antes de ejecutar comandos.

Resumen

En este capítulo aprendiste:

CommandLineInterpreter permite ejecutar acciones de EPLAN programáticamente
Se usa con cli.Execute("nombreComando")
El método Execute() devuelve bool indicando éxito o fallo
Comandos verificados: check, generate, compress
Buenas prácticas: try-catch, verificar retorno, crear CLI una vez, validar precondiciones
Los nombres de comandos son case-sensitive y deben ser exactos

Preguntas frecuentes

P: ¿Dónde encuentro la lista completa de comandos disponibles?

R: En la documentación oficial de EPLAN API (EplanAPI.chm) y en los scripts de ejemplo oficiales.

P: ¿Puedo ejecutar comandos que no aparecen en el menú?

R: Sí, existen acciones internas que solo son accesibles mediante CommandLineInterpreter.

P: ¿Qué pasa si ejecuto un comando que no existe?

R: El método Execute() devuelve false y puede lanzar una excepción. Por eso es importante usar try-catch.

P: ¿Puedo crear mis propios comandos?

R: No directamente, pero puedes crear acciones personalizadas con [DeclareAction] y luego ejecutarlas con CLI.

P: ¿Todos los comandos requieren un proyecto abierto?

R: No, pero muchos sí. Depende de la naturaleza del comando.

Conexiones

Capítulo anterior

Capítulo 15: Register/Unregister - Carga automática

Próximo capítulo

Capítulo 17: Ejecutar múltiples comandos

En el próximo capítulo aprenderás a ejecutar múltiples comandos en secuencia y crear workflows básicos.

Última actualización: Enero 2025 Tiempo de lectura estimado: 20-25 minutos Código de ejemplo: code/cap-16/ Script de referencia: EPLAN-Scripting-4.0/02_RunActions/01_SingleAction.cs