Capítulo 18: Comandos con parámetros

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

Objetivos de aprendizaje

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

Entender qué es ActionCallingContext
Pasar parámetros a comandos de EPLAN
Usar AddParameter() correctamente
Ejecutar comandos que requieren configuración
Combinar múltiples parámetros en un mismo comando

Requisitos previos

Antes de comenzar este capítulo debes:

Haber completado los Capítulos 16-17
Saber ejecutar comandos simples y múltiples con CommandLineInterpreter
Entender el método Execute()

Introducción

Hasta ahora has ejecutado comandos simples como cli.Execute("check"). Pero muchos comandos de EPLAN necesitan parámetros adicionales:

Exportar a una ruta específica
Abrir un archivo concreto
Configurar propiedades con valores específicos
Ejecutar acciones con opciones personalizadas

Para pasar parámetros a los comandos, necesitas ActionCallingContext.

1. ¿Qué es ActionCallingContext?

1.1 Definición

ActionCallingContext es un contenedor de parámetros que se pasa a los comandos cuando estos requieren configuración adicional.

Analogía: Es como pasar argumentos a una función en C#:

// En C#:
MiMetodo(parametro1, parametro2);

// Con EPLAN API:
ActionCallingContext acc = new ActionCallingContext();
acc.AddParameter("nombre1", "valor1");
acc.AddParameter("nombre2", "valor2");
cli.Execute("comando", acc);

1.2 ¿Dónde se define?

ActionCallingContext está en el mismo namespace que CommandLineInterpreter:

using Eplan.EplApi.ApplicationFramework;

2. Estructura básica con parámetros

2.1 Script del ejemplo oficial

Basado en EPLAN-Scripting-4.0/02_RunActions/03_ActionsWithParameter.cs:

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

public class ComandoConParametros
{
    [Start]
    public void Function()
    {
        CommandLineInterpreter cli = new CommandLineInterpreter();
        ActionCallingContext acc = new ActionCallingContext();

        // Según la documentación, los parámetros de interacción van en el Name
        acc.AddParameter("Name", "XGedIaFormatText/height:20");

        cli.Execute("XGedStartInteractionAction", acc);
    }
}

2.2 Análisis línea por línea

Línea 9: Crear CommandLineInterpreter

CommandLineInterpreter cli = new CommandLineInterpreter();

Como siempre, necesitas el intérprete de comandos.

Línea 10: Crear ActionCallingContext

ActionCallingContext acc = new ActionCallingContext();

Creas el contenedor de parámetros vacío.

Línea 12: Agregar parámetro con interacción

acc.AddParameter("Name", "XGedIaFormatText/height:20");

Según la documentación oficial, los parámetros de interacción se concatenan al nombre con barra (/). El formato es: NombreInteraccion/param1:valor1/param2:valor2.

Línea 14: Ejecutar comando con parámetros

cli.Execute("XGedStartInteractionAction", acc);

Pasas el contexto como segundo parámetro de Execute().

3. AddParameter() en detalle

3.1 Sintaxis

acc.AddParameter(string nombre, string valor);

Parámetros:

nombre - Nombre del parámetro (definido por la acción)
valor - Valor del parámetro (siempre como string)

3.2 Tipos de valores

Aunque AddParameter() siempre recibe strings, los valores pueden representar diferentes tipos:

ActionCallingContext acc = new ActionCallingContext();

// String
acc.AddParameter("FILENAME", "reporte.pdf");

// Número (como string)
acc.AddParameter("height", "20");

// Booleano (como string)
acc.AddParameter("OVERWRITE", "1");  // 1 = true, 0 = false

// Ruta
acc.AddParameter("EXPORTFILE", @"C:\temp\export.xml");

Importante: Todos los valores se pasan como string, incluso números y booleanos.

3.3 Múltiples parámetros

Puedes agregar tantos parámetros como necesites:

ActionCallingContext acc = new ActionCallingContext();
acc.AddParameter("parametro1", "valor1");
acc.AddParameter("parametro2", "valor2");
acc.AddParameter("parametro3", "valor3");
// ... etc

4. Comando Execute() con parámetros

4.1 Sintaxis completa

bool Execute(string actionName, ActionCallingContext context);

Parámetros:

actionName - Nombre del comando
context - Contexto con los parámetros (opcional)

Valor de retorno:

bool - true si éxito, false si falló

4.2 Comparación: Con y sin parámetros

Sin parámetros:

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

Con parámetros:

CommandLineInterpreter cli = new CommandLineInterpreter();
ActionCallingContext acc = new ActionCallingContext();
acc.AddParameter("PARAMETRO", "valor");
cli.Execute("comando", acc);

5. Ejemplo práctico: Configurar acción

5.1 Script completo con validación

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

public class ConfigurarAccion
{
    [Start]
    public void Function()
    {
        try
        {
            // Crear intérprete y contexto
            CommandLineInterpreter cli = new CommandLineInterpreter();
            ActionCallingContext acc = new ActionCallingContext();

            // Configurar parámetros (interacción con parámetros concatenados)
            acc.AddParameter("Name", "XGedIaFormatText/height:20");

            // Ejecutar comando con parámetros
            bool resultado = cli.Execute("XGedStartInteractionAction", acc);

            // Verificar resultado
            if (resultado)
            {
                MessageBox.Show("Comando ejecutado correctamente");
            }
            else
            {
                MessageBox.Show("Error al ejecutar comando");
            }
        }
        catch (Exception ex)
        {
            MessageBox.Show("Error: " + ex.Message);
        }
    }
}

6. Reutilizar ActionCallingContext

6.1 Un contexto por comando

Recomendado: Crear un nuevo contexto para cada comando:

CommandLineInterpreter cli = new CommandLineInterpreter();

// Primer comando
ActionCallingContext acc1 = new ActionCallingContext();
acc1.AddParameter("param1", "valor1");
cli.Execute("comando1", acc1);

// Segundo comando
ActionCallingContext acc2 = new ActionCallingContext();
acc2.AddParameter("param2", "valor2");
cli.Execute("comando2", acc2);

6.2 Limpiar y reutilizar contexto

Si quieres reutilizar el mismo contexto, puedes limpiarlo:

CommandLineInterpreter cli = new CommandLineInterpreter();
ActionCallingContext acc = new ActionCallingContext();

// Primer comando
acc.AddParameter("param1", "valor1");
cli.Execute("comando1", acc);

// Limpiar contexto (crear nuevo)
acc = new ActionCallingContext();

// Segundo comando
acc.AddParameter("param2", "valor2");
cli.Execute("comando2", acc);

Nota: Es más simple y claro crear un nuevo contexto cada vez.

7. Workflow con múltiples comandos parametrizados

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

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

            // Comando 1: Sin parámetros
            cli.Execute("check");

            // Comando 2: Con parámetros (concatenados al Name)
            ActionCallingContext acc = new ActionCallingContext();
            acc.AddParameter("Name", "XGedIaFormatText/height:20");
            cli.Execute("XGedStartInteractionAction", acc);

            MessageBox.Show("Workflow completado");
        }
        catch (Exception ex)
        {
            MessageBox.Show("Error: " + ex.Message);
        }
    }
}

Nota: Puedes mezclar comandos con y sin parámetros en el mismo workflow.

8. Buenas prácticas

8.1 Validar parámetros antes de agregar

string rutaArchivo = @"C:\temp\export.xml";

// Validar que la ruta es válida
if (string.IsNullOrEmpty(rutaArchivo))
{
    MessageBox.Show("Ruta de archivo no válida");
    return;
}

// Agregar parámetro
ActionCallingContext acc = new ActionCallingContext();
acc.AddParameter("EXPORTFILE", rutaArchivo);

8.2 Usar nombres de parámetros correctos

Los nombres de parámetros son case-sensitive y específicos de cada comando.

Mal:

acc.AddParameter("filename", "archivo.pdf");  // Puede no funcionar

Bien:

acc.AddParameter("FILENAME", "archivo.pdf");  // Nombre correcto

¿Cómo saber el nombre correcto? Consulta la documentación de EPLAN API o los scripts de ejemplo oficiales.

8.3 Comentar qué hace cada parámetro

ActionCallingContext acc = new ActionCallingContext();
// Para interacciones, los parámetros van concatenados al Name
acc.AddParameter("Name", "XGedIaFormatText/height:20");

8.4 Validar resultado del comando

bool resultado = cli.Execute("comando", acc);
if (!resultado)
{
    MessageBox.Show("El comando falló. Verifica los parámetros.");
}

9. Errores comunes

9.1 Olvidar crear el ActionCallingContext

Error:

CommandLineInterpreter cli = new CommandLineInterpreter();
// Falta crear ActionCallingContext
cli.Execute("comando", acc);  // acc no existe

Corrección:

CommandLineInterpreter cli = new CommandLineInterpreter();
ActionCallingContext acc = new ActionCallingContext();  // Crear contexto
acc.AddParameter("param", "value");
cli.Execute("comando", acc);

9.2 Pasar valores con tipo incorrecto

Error:

acc.AddParameter("height", 20);  // int, no string

Corrección:

acc.AddParameter("height", "20");  // Siempre string

9.3 Nombre de parámetro incorrecto

Error:

acc.AddParameter("altura", "20");  // Nombre incorrecto

Corrección:

acc.AddParameter("height", "20");  // Nombre correcto según documentación

10. ¿Qué comandos requieren parámetros?

10.1 Indicadores comunes

Comandos que suelen requerir parámetros:

Comandos de exportación (ruta de destino)
Comandos de importación (ruta de origen)
Comandos de configuración (valores a establecer)
Comandos de acciones específicas (opciones de ejecución)

10.2 Fuentes de información

Para saber qué parámetros requiere un comando:

Documentación EPLAN API (EplanAPI.chm)
Scripts oficiales de EPLAN-Scripting-4.0
Experimentación con validación de resultados
Foros y comunidad EPLAN

Resumen

En este capítulo aprendiste:

ActionCallingContext es el contenedor de parámetros para comandos
Usar AddParameter(nombre, valor) para agregar parámetros
Todos los valores se pasan como string
Sintaxis: cli.Execute(comando, contexto)
Puedes combinar comandos con y sin parámetros
Los nombres de parámetros son case-sensitive
Siempre validar el resultado del comando
Crear un contexto nuevo para cada comando es más claro

Preguntas frecuentes

P: ¿Puedo pasar números directamente a AddParameter()?

R: No, debes convertirlos a string: acc.AddParameter("height", "20") o acc.AddParameter("height", altura.ToString())

P: ¿Cuántos parámetros puedo agregar?

R: No hay límite específico. Depende del comando.

P: ¿Qué pasa si paso un parámetro que el comando no espera?

R: Generalmente se ignora, pero puede causar errores. Verifica la documentación.

P: ¿Puedo modificar un parámetro después de agregarlo?

R: No directamente. Debes crear un nuevo ActionCallingContext.

Conexiones

Capítulo anterior

Capítulo 17: Ejecutar múltiples comandos

Próximo capítulo

Capítulo 19: Parámetros múltiples en ActionCallingContext

En el próximo capítulo verás ejemplos más avanzados de pasar múltiples parámetros complejos.

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