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

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:

Recibir parámetros en tu script con ActionCallingContext
Usar GetParameter() para leer valores pasados al script
Pasar múltiples parámetros complejos a comandos
Crear scripts parametrizables y reutilizables
Combinar AddParameter() y GetParameter()

Requisitos previos

Antes de comenzar este capítulo debes:

Haber completado el Capítulo 18 (comandos con parámetros)
Entender ActionCallingContext y AddParameter()
Saber ejecutar comandos con parámetros

Introducción

En el capítulo anterior aprendiste a pasar parámetros a comandos usando AddParameter(). Pero, ¿qué pasa si quieres que tu propio script reciba parámetros?

Imagina que quieres crear un script reutilizable que configure un proyecto, pero que los valores (nombre de cliente, ubicación, etc.) cambien cada vez que lo ejecutas.

Para esto necesitas recibir parámetros en tu script usando GetParameter().

1. Dos usos de ActionCallingContext

1.1 Pasar parámetros (AddParameter)

Uso: Enviar parámetros a un comando de EPLAN

ActionCallingContext acc = new ActionCallingContext();
acc.AddParameter("PROJECTNAME", "MiProyecto");
cli.Execute("comando", acc);

1.2 Recibir parámetros (GetParameter)

Uso: Recibir parámetros en tu script desde fuera

[Start]
public void Execute(ActionCallingContext oActionCallingContext)
{
    string valorRecibido = "";
    oActionCallingContext.GetParameter("NOMBRE_PARAMETRO", ref valorRecibido);
}

Nota: Puedes hacer ambas cosas en el mismo script.

2. Recibir parámetros con GetParameter()

2.1 Sintaxis básica

oActionCallingContext.GetParameter(string nombre, ref string variable);

Parámetros:

nombre - Nombre del parámetro a obtener
variable - Variable donde se almacenará el valor (debe usar ref)

Importante: La variable debe declararse antes de usarla y debe ser ref.

2.2 Ejemplo básico

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

public class ScriptConParametros
{
    [Start]
    public void Execute(ActionCallingContext oActionCallingContext)
    {
        // Declarar variable para recibir el parámetro
        string nombreProyecto = "";

        // Obtener parámetro
        oActionCallingContext.GetParameter("ProjectName", ref nombreProyecto);

        // Usar el parámetro
        MessageBox.Show("Nombre del proyecto: " + nombreProyecto);
    }
}

2.3 Análisis línea por línea

Línea 9: Método con ActionCallingContext

public void Execute(ActionCallingContext oActionCallingContext)

Tu método recibe el contexto como parámetro.

Línea 12: Declarar variable

string nombreProyecto = "";

Inicializas la variable que recibirá el valor.

Línea 15: Obtener parámetro

oActionCallingContext.GetParameter("ProjectName", ref nombreProyecto);

Obtienes el valor del parámetro “ProjectName” y lo almacenas en nombreProyecto.

Nota: ref es obligatorio para que GetParameter() pueda modificar la variable.

3. Múltiples parámetros

3.1 Recibir varios parámetros

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

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

public class ConfigurarProyecto
{
    [Start]
    public void Execute(ActionCallingContext oActionCallingContext)
    {
        // Declarar variables para recibir parámetros
        string nombreProyecto = "";
        string cliente = "";
        string ubicacion = "";
        string desarrollador = "";

        // Obtener múltiples parámetros
        oActionCallingContext.GetParameter("ProjectName", ref nombreProyecto);
        oActionCallingContext.GetParameter("Customer", ref cliente);
        oActionCallingContext.GetParameter("Location", ref ubicacion);
        oActionCallingContext.GetParameter("Developed", ref desarrollador);

        // Usar los parámetros
        string mensaje = "Configurando proyecto:\n\n" +
                        "Proyecto: " + nombreProyecto + "\n" +
                        "Cliente: " + cliente + "\n" +
                        "Ubicación: " + ubicacion + "\n" +
                        "Desarrollado por: " + desarrollador;

        MessageBox.Show(mensaje, "Configuración de Proyecto");
    }
}

3.2 Parámetros opcionales con validación

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

public class ScriptConValidacion
{
    [Start]
    public void Execute(ActionCallingContext oActionCallingContext)
    {
        // Parámetros obligatorios
        string nombreProyecto = "";
        oActionCallingContext.GetParameter("ProjectName", ref nombreProyecto);

        if (string.IsNullOrEmpty(nombreProyecto))
        {
            MessageBox.Show("Error: ProjectName es obligatorio");
            return;
        }

        // Parámetros opcionales con valor por defecto
        string cliente = "";
        oActionCallingContext.GetParameter("Customer", ref cliente);

        if (string.IsNullOrEmpty(cliente))
        {
            cliente = "Cliente no especificado";
        }

        MessageBox.Show(
            "Proyecto: " + nombreProyecto + "\n" +
            "Cliente: " + cliente
        );
    }
}

4. Combinar AddParameter() y GetParameter()

4.1 Recibir parámetros y ejecutar comandos

Un patrón común es recibir parámetros en tu script y luego usarlos para ejecutar comandos:

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

public class ConfigurarYEjecutar
{
    [Start]
    public void Execute(ActionCallingContext oActionCallingContext)
    {
        try
        {
            // 1. Recibir parámetros
            string nombreProyecto = "";
            string rutaExportacion = "";

            oActionCallingContext.GetParameter("ProjectName", ref nombreProyecto);
            oActionCallingContext.GetParameter("ExportPath", ref rutaExportacion);

            // Validar parámetros
            if (string.IsNullOrEmpty(nombreProyecto))
            {
                MessageBox.Show("Error: ProjectName es obligatorio");
                return;
            }

            // 2. Usar parámetros para ejecutar comandos
            CommandLineInterpreter cli = new CommandLineInterpreter();

            // Generar reportes
            ActionCallingContext acc = new ActionCallingContext();
            acc.AddParameter("TYPE", "PROJECT");
            acc.AddParameter("PROJECTNAME", nombreProyecto);
            cli.Execute("reports", acc);

            MessageBox.Show("Configuración completada para: " + nombreProyecto);
        }
        catch (Exception ex)
        {
            MessageBox.Show("Error: " + ex.Message);
        }
    }
}

5. Tipos de parámetros

5.1 Todos son strings

Aunque GetParameter() siempre trabaja con strings, puedes convertir los valores:

// Recibir como string
string alturaStr = "";
string sobrescribirStr = "";

oActionCallingContext.GetParameter("height", ref alturaStr);
oActionCallingContext.GetParameter("overwrite", ref sobrescribirStr);

// Convertir a otros tipos
int altura = int.Parse(alturaStr);
bool sobrescribir = sobrescribirStr == "1" || sobrescribirStr.ToLower() == "true";

// Usar los valores convertidos
if (sobrescribir && altura > 20)
{
    // Hacer algo...
}

5.2 Manejo seguro de conversiones

string alturaStr = "";
oActionCallingContext.GetParameter("height", ref alturaStr);

int altura;
if (int.TryParse(alturaStr, out altura))
{
    MessageBox.Show("Altura: " + altura);
}
else
{
    MessageBox.Show("Error: altura debe ser un número");
}

6. Ejemplo práctico completo

6.1 Script para configurar propiedades de proyecto

Basado en patrones de EGCExecutor.cs:

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

public class ConfigurarPropiedadesProyecto
{
    [Start]
    public void Execute(ActionCallingContext oActionCallingContext)
    {
        try
        {
            // Recibir parámetros
            string cliente = "";
            string descripcion = "";
            string ubicacion = "";

            oActionCallingContext.GetParameter("Customer", ref cliente);
            oActionCallingContext.GetParameter("Description", ref descripcion);
            oActionCallingContext.GetParameter("Location", ref ubicacion);

            // Validar que al menos un parámetro esté presente
            if (string.IsNullOrEmpty(cliente) &&
                string.IsNullOrEmpty(descripcion) &&
                string.IsNullOrEmpty(ubicacion))
            {
                MessageBox.Show("Error: Debe proporcionar al menos un parámetro");
                return;
            }

            // Configurar propiedades del proyecto
            if (!string.IsNullOrEmpty(cliente))
            {
                SetProjectProperty("10102", cliente);
            }

            if (!string.IsNullOrEmpty(descripcion))
            {
                SetProjectProperty("10011", descripcion);
            }

            if (!string.IsNullOrEmpty(ubicacion))
            {
                SetProjectProperty("10032", ubicacion);
            }

            MessageBox.Show(
                "Propiedades configuradas correctamente:\n\n" +
                "Cliente: " + cliente + "\n" +
                "Descripción: " + descripcion + "\n" +
                "Ubicación: " + ubicacion,
                "Éxito"
            );
        }
        catch (Exception ex)
        {
            MessageBox.Show("Error: " + ex.Message, "Error");
        }
    }

    private void SetProjectProperty(string propertyId, string value)
    {
        CommandLineInterpreter cli = new CommandLineInterpreter();
        ActionCallingContext acc = new ActionCallingContext();

        acc.AddParameter("PropertyIdentName", propertyId);
        acc.AddParameter("PropertyIndex", "0");
        acc.AddParameter("PropertyValue", value);

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

7. Buenas prácticas

7.1 Inicializar variables antes de GetParameter()

// Bien
string parametro = "";
oActionCallingContext.GetParameter("PARAM", ref parametro);

// Mal - variable no inicializada
string parametro;
oActionCallingContext.GetParameter("PARAM", ref parametro);  // Error

7.2 Validar parámetros recibidos

string ruta = "";
oActionCallingContext.GetParameter("PATH", ref ruta);

if (string.IsNullOrEmpty(ruta))
{
    MessageBox.Show("Error: PATH no puede estar vacío");
    return;
}

7.3 Proporcionar valores por defecto

string idioma = "";
oActionCallingContext.GetParameter("Language", ref idioma);

if (string.IsNullOrEmpty(idioma))
{
    idioma = "es_ES";  // Valor por defecto
}

7.4 Documentar parámetros esperados

/// <summary>
/// Configura propiedades del proyecto.
/// Parámetros esperados:
/// - Customer: Nombre del cliente (opcional)
/// - Description: Descripción del proyecto (opcional)
/// - Location: Ubicación del proyecto (opcional)
/// </summary>
[Start]
public void Execute(ActionCallingContext oActionCallingContext)
{
    // ...
}

8. ¿Cómo pasar parámetros a tu script?

8.1 Desde línea de comandos

Puedes ejecutar tu script desde la línea de comandos de EPLAN pasando parámetros:

ExecuteScript /ScriptPath:"C:\Scripts\MiScript.cs" /Customer:"Acme Corp" /Location:"Madrid"

8.2 Desde otro script

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

acc.AddParameter("Customer", "Acme Corp");
acc.AddParameter("Location", "Madrid");

cli.Execute("MiAccionPersonalizada", acc);

8.3 Desde aplicación externa

Si llamas a EPLAN desde una aplicación externa, puedes pasar parámetros vía línea de comandos.

Resumen

En este capítulo aprendiste:

GetParameter() permite recibir parámetros en tu script
Usar ref es obligatorio con GetParameter()
Puedes recibir múltiples parámetros
Combinar GetParameter() (recibir) y AddParameter() (enviar)
Validar y convertir parámetros recibidos
Proporcionar valores por defecto para parámetros opcionales
Documentar los parámetros que tu script espera

Preguntas frecuentes

P: ¿Por qué necesito ref en GetParameter()?

R: Porque GetParameter() modifica la variable que le pasas. En C#, ref permite que un método modifique el valor de una variable.

P: ¿Qué pasa si pido un parámetro que no fue proporcionado?

R: La variable permanece con su valor inicial (vacía si la inicializaste como ""). Por eso es importante validar.

P: ¿Puedo tener parámetros obligatorios y opcionales?

R: Sí, usa validación para los obligatorios y valores por defecto para los opcionales.

P: ¿GetParameter() y AddParameter() son lo mismo?

R: No. GetParameter() recibe parámetros en tu script. AddParameter() envía parámetros a comandos.

Conexiones

Capítulo anterior

Capítulo 18: Comandos con parámetros

Próximo capítulo

Capítulo 20: PathMap - Variables del sistema

En el próximo capítulo aprenderás a usar PathMap.SubstitutePath() para obtener información del proyecto actual.

Última actualización: Enero 2025 Tiempo de lectura estimado: 25-30 minutos Código de ejemplo: code/cap-19/ Script de referencia: EPLAN-Scripting-4.0/02_RunActions/EGCExecutor.cs (simplificado)