Capítulo 13: El atributo [DeclareAction]

Parte II: Primeros pasos con EPLAN API - Sección 5: Atributos de scripting - Nivel: Principiante

Objetivos de aprendizaje

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

Entender la diferencia entre [Start] y [DeclareAction]
Crear acciones personalizadas con nombres específicos
Llamar acciones desde otros scripts
Tener múltiples acciones en el mismo script
Asignar acciones a botones de la cinta de opciones de EPLAN

Requisitos previos

Antes de comenzar este capítulo debes:

Haber completado el Capítulo 12 (atributo [Start])
Entender qué es un atributo en C#
Saber ejecutar scripts en EPLAN
Conocer la estructura básica de un script

Introducción

En el capítulo anterior aprendiste a usar [Start] para crear scripts que se ejecutan directamente. Pero [Start] tiene limitaciones:

Solo puede haber uno por script
Se ejecuta automáticamente al abrir el archivo
No tiene un nombre específico que puedas llamar

¿Qué pasa si quieres:

Crear múltiples funciones ejecutables en el mismo script?
Asignar una función a un botón personalizado en la cinta de EPLAN?
Llamar una función desde otro script?
Dar un nombre descriptivo a tu acción?

Para eso existe [DeclareAction].

1. ¿Qué es [DeclareAction]?

1.1 Definición

[DeclareAction] es un atributo de EPLAN que convierte un método en una acción registrada en el sistema.

Diferencia clave:

[Start] - Punto de entrada anónimo, se ejecuta al abrir el script
[DeclareAction] - Acción con nombre, se registra en EPLAN y puede llamarse

1.2 Sintaxis básica

[DeclareAction("NombreDeLaAccion")]
public void MiMetodo()
{
    // código
}

Componentes:

[DeclareAction("...")] - Atributo con parámetro (nombre de la acción)
"NombreDeLaAccion" - String que identifica la acción
public void - Igual que [Start], debe ser público y void

1.3 ¿Dónde se define?

El atributo está en el mismo namespace que [Start]:

using Eplan.EplApi.Scripting;

2. Diferencias entre [Start] y [DeclareAction]

Característica	[Start]	[DeclareAction]
Nombre	Anónimo	Con nombre específico
Cantidad por script	Solo uno	Múltiples
Ejecución	Automática al abrir script	Debe llamarse explícitamente
Parámetro	No acepta parámetros	Requiere nombre de acción
Asignable a botón	No	Sí
Llamable desde CLI	No	Sí
Uso típico	Scripts standalone	Acciones reutilizables

2.1 Ejemplo comparativo

Con [Start]:

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

public class MiScript
{
    [Start]
    public void Ejecutar()
    {
        MessageBox.Show("Script ejecutado");
    }
}

Se ejecuta automáticamente al abrir el archivo
No se puede llamar por nombre
No se puede asignar a botón

Con [DeclareAction]:

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

public class MiScript
{
    [DeclareAction("MostrarMensaje")]
    public void Ejecutar()
    {
        MessageBox.Show("Acción ejecutada");
    }
}

No se ejecuta automáticamente
Se puede llamar usando el nombre “MostrarMensaje”
Se puede asignar a un botón de la cinta
Se puede ejecutar desde CommandLineInterpreter

3. Tu primera acción con [DeclareAction]

3.1 Script simple con acción

Archivo: 01_AccionSimple.cs

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

public class AccionSimple
{
    [DeclareAction("MiPrimeraAccion")]
    public void Ejecutar()
    {
        MessageBox.Show("Has ejecutado tu primera acción declarada!");
    }
}

3.2 ¿Cómo ejecutar esta acción?

A diferencia de [Start], esta acción no se ejecuta automáticamente al abrir el archivo.

Formas de ejecutarla:

Desde el menú Utilidades > Scripts > Ejecutar acción
- Buscar la acción por nombre: “MiPrimeraAccion”
Asignándola a un botón de la cinta (lo veremos más adelante)

Desde otro script usando CommandLineInterpreter:

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

3.3 Reglas del nombre de acción

Convenciones importantes:

No usar espacios - “MiAccion” (bien), “Mi Accion” (evitar)
CamelCase o PascalCase - “GuardarYGenerar”, “exportarPDF”
Nombres descriptivos - “ExportarPDF” mejor que “Accion1”
Únicos en el sistema - Si hay dos acciones con el mismo nombre, hay conflicto

Buenos nombres:

ExportarProyectoAPDF
GenerarYSincronizar
ValidarConexiones
CrearInformeTecnico

Malos nombres:

Action1 - No descriptivo
Ejecutar - Demasiado genérico
Mi Accion - Tiene espacio
do_stuff - No sigue convenciones C#

4. Múltiples acciones en el mismo script

4.1 ¿Por qué tener múltiples acciones?

Una de las ventajas de [DeclareAction] es que puedes tener múltiples acciones en el mismo archivo .cs.

Casos de uso:

Agrupar acciones relacionadas (Guardar, Generar, Exportar)
Crear una “suite” de herramientas en un solo script
Organizar mejor el código

4.2 Ejemplo con múltiples acciones

Archivo: 02_MultipleAcciones.cs

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

public class MultipleAcciones
{
    [DeclareAction("MostrarProyecto")]
    public void MostrarProyecto()
    {
        string nombre = PathMap.SubstitutePath("$(PROJECTNAME)");
        MessageBox.Show("Proyecto actual: " + nombre);
    }

    [DeclareAction("MostrarRuta")]
    public void MostrarRuta()
    {
        string ruta = PathMap.SubstitutePath("$(PROJECTPATH)");
        MessageBox.Show("Ruta del proyecto: " + ruta);
    }

    [DeclareAction("MostrarTodo")]
    public void MostrarTodo()
    {
        // Llamar a las otras acciones
        MostrarProyecto();
        MostrarRuta();
    }
}

Análisis:

Tres acciones declaradas: “MostrarProyecto”, “MostrarRuta”, “MostrarTodo”
Cada acción hace una tarea específica
La tercera acción llama a las otras dos (reutilización de código)
Todas están en el mismo archivo .cs

4.3 Ventajas de este enfoque

Organización:

Acciones relacionadas en el mismo lugar
Fácil de mantener
Código reutilizable entre acciones

Eficiencia:

Un solo archivo para cargar
Métodos privados compartidos entre acciones
Menos duplicación de código

5. Combinar [Start] y [DeclareAction]

5.1 ¿Se pueden usar juntos?

Sí, puedes tener ambos en el mismo script.

Ejemplo válido:

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

public class MiScript
{
    [Start]
    public void EjecutarAlAbrir()
    {
        MessageBox.Show("Este método se ejecuta al abrir el script");
    }

    [DeclareAction("AccionPersonalizada")]
    public void MiAccion()
    {
        MessageBox.Show("Esta acción se ejecuta cuando se llama por nombre");
    }
}

5.2 ¿Cuándo usar esta combinación?

Casos de uso:

[Start] para mostrar un menú o configuración inicial
[DeclareAction] para las acciones reales del menú
[Start] para registrar las acciones al cargar EPLAN
[DeclareAction] para las funciones ejecutables

Ejemplo práctico:

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

public class SuiteHerramientas
{
    [Start]
    public void MostrarMenu()
    {
        MessageBox.Show(
            "Suite de herramientas cargada.\n\n" +
            "Acciones disponibles:\n" +
            "- MostrarProyecto\n" +
            "- MostrarRuta\n" +
            "- MostrarPropiedades",
            "Herramientas"
        );
    }

    [DeclareAction("MostrarProyecto")]
    public void MostrarProyecto()
    {
        // implementación
    }

    [DeclareAction("MostrarRuta")]
    public void MostrarRuta()
    {
        // implementación
    }

    [DeclareAction("MostrarPropiedades")]
    public void MostrarPropiedades()
    {
        // implementación
    }
}

Comportamiento:

Al ejecutar el .cs directamente: Se muestra el menú ([Start])
Al llamar “MostrarProyecto”: Se ejecuta solo esa acción
Al llamar “MostrarPropiedades”: Se ejecuta solo esa acción

6. Asignar acciones a la cinta de opciones

6.1 ¿Qué es la cinta de opciones?

La cinta de opciones (Ribbon) es la barra de herramientas superior de EPLAN con pestañas (Inicio, Insertar, Datos, etc.).

Puedes agregar botones personalizados que ejecuten tus acciones declaradas.

6.2 Cómo asignar una acción a un botón

Pasos:

Abre EPLAN Electric P8
Haz clic derecho en la cinta de opciones
Selecciona Personalizar cinta de opciones
Haz clic en Nuevo grupo (dentro de una pestaña existente)
Haz clic en Nuevo botón
En “Acción”, busca el nombre de tu acción (ej: “MiPrimeraAccion”)
Personaliza el nombre del botón y el icono
Acepta

Nota: Esto se explicó en detalle en el Capítulo 2 del libro. No lo repetiremos aquí.

6.3 Ventajas de asignar acciones

Accesibilidad:

Ejecutar acciones con un solo clic
No necesitas abrir el script cada vez

Profesionalismo:

Interfaz personalizada para tu empresa
Flujo de trabajo optimizado

Productividad:

Acciones comunes siempre disponibles
Ideal para tareas repetitivas

7. Llamar acciones desde otros scripts

7.1 CommandLineInterpreter

Puedes ejecutar acciones declaradas desde otros scripts usando CommandLineInterpreter.

Ejemplo:

Script 1: Define las acciones

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

public class Herramientas
{
    [DeclareAction("MostrarProyecto")]
    public void MostrarProyecto()
    {
        string nombre = PathMap.SubstitutePath("$(PROJECTNAME)");
        MessageBox.Show("Proyecto: " + nombre);
    }
}

Script 2: Llama a la acción

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

public class WorkflowCompleto
{
    [Start]
    public void Ejecutar()
    {
        CommandLineInterpreter cli = new CommandLineInterpreter();

        // Llamar a la acción declarada en Herramientas.cs
        cli.Execute("MostrarProyecto");

        MessageBox.Show("Workflow completado");
    }
}

7.2 Ventaja de este enfoque

Modularidad:

Acciones reutilizables entre scripts
No duplicar código
Cambiar la implementación en un solo lugar

Mantenibilidad:

Fácil actualizar herramientas
Menos riesgo de inconsistencias

8. Proyecto del capítulo: Suite de acciones básicas

8.1 Objetivo

Crear un script con múltiples acciones que realicen tareas comunes de EPLAN.

Acciones a implementar:

MostrarProyecto - Muestra nombre del proyecto
MostrarRutas - Muestra rutas importantes
MostrarPropiedades - Muestra propiedades del proyecto
ResumenCompleto - Ejecuta las tres anteriores en orden

8.2 Implementación completa

Archivo: SuiteAcciones.cs

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

public class SuiteAcciones
{
    // Acción 1: Mostrar nombre del proyecto
    [DeclareAction("MostrarProyecto")]
    public void MostrarProyecto()
    {
        try
        {
            string nombre = PathMap.SubstitutePath("$(PROJECTNAME)");

            MessageBox.Show(
                "Proyecto actual: " + nombre,
                "Información de Proyecto",
                MessageBoxButtons.OK,
                MessageBoxIcon.Information
            );
        }
        catch (Exception ex)
        {
            MessageBox.Show(
                "Error al obtener nombre: " + ex.Message,
                "Error",
                MessageBoxButtons.OK,
                MessageBoxIcon.Error
            );
        }
    }

    // Acción 2: Mostrar rutas importantes
    [DeclareAction("MostrarRutas")]
    public void MostrarRutas()
    {
        try
        {
            string rutaProyecto = PathMap.SubstitutePath("$(PROJECTPATH)");
            string rutaDoc = PathMap.SubstitutePath("$(DOC)");

            MessageBox.Show(
                "Rutas del sistema:\n\n" +
                "Proyecto: " + rutaProyecto + "\n" +
                "Documentos: " + rutaDoc,
                "Rutas",
                MessageBoxButtons.OK,
                MessageBoxIcon.Information
            );
        }
        catch (Exception ex)
        {
            MessageBox.Show(
                "Error al obtener rutas: " + ex.Message,
                "Error",
                MessageBoxButtons.OK,
                MessageBoxIcon.Error
            );
        }
    }

    // Acción 3: Mostrar propiedades del proyecto
    [DeclareAction("MostrarPropiedades")]
    public void MostrarPropiedades()
    {
        try
        {
            string campo1 = PathMap.SubstitutePath("$(PROJECTPROPERTYFIELD1)");
            string campo2 = PathMap.SubstitutePath("$(PROJECTPROPERTYFIELD2)");

            MessageBox.Show(
                "Propiedades del proyecto:\n\n" +
                "Campo 1: " + campo1 + "\n" +
                "Campo 2: " + campo2,
                "Propiedades",
                MessageBoxButtons.OK,
                MessageBoxIcon.Information
            );
        }
        catch (Exception ex)
        {
            MessageBox.Show(
                "Error al obtener propiedades: " + ex.Message,
                "Error",
                MessageBoxButtons.OK,
                MessageBoxIcon.Error
            );
        }
    }

    // Acción 4: Resumen completo
    [DeclareAction("ResumenCompleto")]
    public void ResumenCompleto()
    {
        try
        {
            MostrarProyecto();
            MostrarRutas();
            MostrarPropiedades();

            MessageBox.Show(
                "Resumen completo ejecutado:\n" +
                "1. Nombre mostrado\n" +
                "2. Rutas mostradas\n" +
                "3. Propiedades mostradas",
                "Resumen Completado",
                MessageBoxButtons.OK,
                MessageBoxIcon.Information
            );
        }
        catch (Exception ex)
        {
            MessageBox.Show(
                "Error en resumen: " + ex.Message,
                "Error",
                MessageBoxButtons.OK,
                MessageBoxIcon.Error
            );
        }
    }

    // [Start] opcional para mostrar información
    [Start]
    public void MostrarInfo()
    {
        MessageBox.Show(
            "Suite de Acciones EPLAN\n\n" +
            "Acciones disponibles:\n" +
            "- MostrarProyecto\n" +
            "- MostrarRutas\n" +
            "- MostrarPropiedades\n" +
            "- ResumenCompleto\n\n" +
            "Asigna estas acciones a botones en la cinta de opciones.",
            "Suite de Acciones",
            MessageBoxButtons.OK,
            MessageBoxIcon.Information
        );
    }
}

8.3 Prueba del proyecto

Paso 1: Ejecutar el script directamente

Se mostrará la información de las acciones disponibles ([Start])

Paso 2: Ejecutar acciones individuales

Usa Utilidades > Scripts > Ejecutar acción
Prueba: MostrarProyecto, MostrarRutas, MostrarPropiedades

Paso 3: Ejecutar resumen completo

Usa Utilidades > Scripts > Ejecutar acción > ResumenCompleto
Verifica que ejecuta las tres acciones en orden

Paso 4: Asignar a botones (opcional)

Personaliza la cinta de opciones
Crea botones para las acciones más usadas

9. Errores comunes

9.1 Olvidar el parámetro del nombre

Error:

[DeclareAction]  // ✗ Falta el nombre de la acción
public void MiMetodo()
{
    // ...
}

Solución:

[DeclareAction("NombreDeLaAccion")]  // ✓ Con nombre
public void MiMetodo()
{
    // ...
}

9.2 Nombre duplicado

Error:

public class Script1
{
    [DeclareAction("MiAccion")]  // ✗ Nombre duplicado
    public void Metodo1() { }
}

public class Script2
{
    [DeclareAction("MiAccion")]  // ✗ Mismo nombre
    public void Metodo2() { }
}

Solución: Usar nombres únicos para cada acción.

9.3 Intentar ejecutar [DeclareAction] directamente

Error común: Abrir un .cs con solo [DeclareAction] esperando que se ejecute.

Realidad: Las acciones con [DeclareAction] no se ejecutan automáticamente. Debes:

Llamarlas por nombre
Asignarlas a botones
O añadir un [Start] que las ejecute

Resumen

En este capítulo aprendiste:

El atributo [DeclareAction] crea acciones con nombre en EPLAN
Diferencias entre [Start] (ejecución automática) y [DeclareAction] (acción registrada)
Puedes tener múltiples [DeclareAction] en el mismo script
Las acciones se pueden asignar a botones de la cinta de opciones
Las acciones se pueden llamar desde otros scripts con CommandLineInterpreter
Puedes combinar [Start] y [DeclareAction] en el mismo script
Las acciones deben tener nombres únicos y descriptivos

Preguntas frecuentes

P: ¿Puedo tener [Start] y [DeclareAction] en el mismo método?

R: No. Un método solo puede tener un atributo de ejecución. Pero puedes tener ambos en diferentes métodos de la misma clase.

P: ¿Cómo sé qué acciones están registradas en EPLAN?

R: Ve a Utilidades > Scripts > Ejecutar acción. Verás todas las acciones disponibles.

P: ¿Las acciones persisten después de cerrar EPLAN?

R: No. Las acciones solo están disponibles mientras el script esté cargado. Para tenerlas siempre, debes usar [DeclareRegister] (siguiente capítulo).

P: ¿Puedo pasar parámetros a una acción?

R: Sí, pero no con [DeclareAction] básico. Hay formas avanzadas que veremos más adelante.

Conexiones

Capítulo anterior

Capítulo 12: El atributo [Start] - Aprendiste el punto de entrada básico de scripts

Próximo capítulo

Capítulo 14: Event Handlers - Reaccionar a eventos

En el próximo capítulo aprenderás a crear event handlers que reaccionan automáticamente a eventos de EPLAN (abrir proyecto, cerrar página, etc.).

Última actualización: Enero 2025 Tiempo de lectura estimado: 25-30 minutos Código de ejemplo: code/cap-13/ Script de referencia: EPLAN-Scripting-4.0/01_FirstSteps/02_DeclareAction.cs