Automatización EPLAN 2026

Capítulo 15: Registrar acciones en EPLAN

5 min de lectura

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

Objetivos de aprendizaje

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

  • Entender qué son los atributos DeclareRegister y DeclareUnregister
  • Hacer que tus scripts se carguen automáticamente al iniciar EPLAN
  • Implementar inicialización y limpieza de recursos
  • Combinar Register/Unregister con otros atributos de scripting
  • Conocer casos de uso típicos de carga automática

Requisitos previos

Antes de comenzar este capítulo debes:

  • Haber completado los Capítulos 12-14 (Start, DeclareAction, DeclareEventHandler)
  • Entender el ciclo de vida de scripts en EPLAN
  • Conocer conceptos básicos de inicialización y limpieza de recursos

Introducción

En los capítulos anteriores has aprendido diferentes formas de ejecutar código:

  • Start - Ejecución manual al abrir el script
  • DeclareAction - Ejecución al llamar la acción por nombre
  • DeclareEventHandler - Ejecución automática al ocurrir un evento

Pero todos estos tienen un problema: debes ejecutar o registrar el script manualmente cada vez que abres EPLAN.

¿Qué pasa si quieres que tu script:

  • Se cargue automáticamente al iniciar EPLAN?
  • Configure elementos de interfaz (ribbon, menús) al arrancar?
  • Registre event handlers permanentemente?
  • Se limpie correctamente al cerrar EPLAN?

Para eso existen DeclareRegister y DeclareUnregister.

1. ¿Qué son DeclareRegister y DeclareUnregister?

1.1 Definiciones

DeclareRegister: Atributo que marca un método que se ejecuta automáticamente cuando EPLAN carga el script.

DeclareUnregister: Atributo que marca un método que se ejecuta automáticamente cuando EPLAN descarga el script.

Analogía:

  • [DeclareRegister] es como el constructor de una aplicación
  • [DeclareUnregister] es como el destructor o método Dispose

1.2 Sintaxis básica

[DeclareRegister]
public void Register()
{
    // Código de inicialización
}

[DeclareUnregister]
public void UnRegister()
{
    // Código de limpieza
}

Componentes:

  • Métodos públicos sin parámetros
  • Devuelven void
  • Los nombres pueden ser cualquiera, pero por convención se usan Register/UnRegister
  • Solo puede haber un DeclareRegister y un DeclareUnregister por script

1.3 ¿Dónde se definen?

Están en el mismo namespace que los otros atributos:

using Eplan.EplApi.Scripting;

2. Ciclo de vida del script

2.1 Cuándo se ejecutan

DeclareRegister se ejecuta:

  • Al iniciar EPLAN (si el script está configurado para carga automática)
  • Al ejecutar manualmente el script por primera vez

DeclareUnregister se ejecuta:

  • Al cerrar EPLAN
  • Al descargar manualmente el script

2.2 Diagrama del ciclo de vida

┌─────────────────────────────────────────────┐
│         INICIO DE EPLAN                     │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
         ┌────────────────────┐
         │  [DeclareRegister] │ ← Inicialización
         └────────┬───────────┘
                  │
                  ▼
         ┌────────────────────┐
         │   Script activo    │
         │  - [DeclareAction] │
         │  - [EventHandler]  │
         └────────┬───────────┘
                  │
                  ▼
       ┌──────────────────────┐
       │ [DeclareUnregister]  │ ← Limpieza
       └──────────┬───────────┘
                  │
                  ▼
         ┌────────────────────┐
         │    CIERRE DE EPLAN  │
         └────────────────────┘

3. Tu primer script con Register/Unregister

3.1 Ejemplo básico

Este ejemplo está basado directamente en EPLAN-Scripting-4.0/01_FirstSteps/04_DeclareRegisterUnregister.cs:

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

public class RegisterBasico
{
    [DeclareRegister]
    public void Register()
    {
        MessageBox.Show("Script loaded.");
    }

    [DeclareUnregister]
    public void UnRegister()
    {
        MessageBox.Show("Script unloaded.");
    }
}

3.2 ¿Cómo probar este script?

Paso 1: Ejecutar el script

  • Utilidades > Scripts > Ejecutar
  • Seleccionar el archivo .cs
  • Verás el mensaje "Script loaded."

Paso 2: Cerrar EPLAN

  • Al cerrar EPLAN, verás el mensaje "Script unloaded."

Paso 3: Configurar carga automática

  • Copia el script a la carpeta de scripts de EPLAN
  • Configura EPLAN para cargar scripts al inicio
  • La próxima vez que abras EPLAN, verás "Script loaded." automáticamente

4. Casos de uso típicos

4.1 Registrar event handlers permanentemente

Uno de los usos más comunes es registrar event handlers para que persistan entre sesiones:

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

public class EventHandlerPermanente
{
    [DeclareRegister]
    public void Register()
    {
        // Al cargar el script, los event handlers se registran automáticamente
        MessageBox.Show("Event handlers registrados");
    }

    [DeclareUnregister]
    public void UnRegister()
    {
        // Limpieza al cerrar
        MessageBox.Show("Event handlers desregistrados");
    }

    [DeclareEventHandler("Eplan.EplApi.OnUserPreCloseProject")]
    public void AlCerrarProyecto()
    {
        MessageBox.Show("Proyecto cerrándose");
    }
}

Ventaja: El event handler estará activo siempre que EPLAN esté abierto, sin necesidad de ejecutar el script manualmente cada vez.

4.2 Crear elementos de Ribbon permanentes

Los scripts con DeclareRegister pueden crear pestañas, grupos y botones en la cinta de opciones automáticamente.

Este ejemplo está simplificado de EPLAN-Scripting-4.0/07_RibbonContextMenus/01_Ribbon.cs:

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

public class CrearRibbon
{
    private const string ACTION_NAME = "MiAccion";

    [DeclareRegister]
    public void Register()
    {
        // Crear elementos de Ribbon al cargar
        RibbonBar ribbonBar = new RibbonBar();

        // Crear tab con MultiLangString
        MultiLangString tabName = new MultiLangString();
        tabName.AddString(ISOCode.Language.L_en_US, "My Tab");

        RibbonTab ribbonTab = ribbonBar.GetTab(tabName, true);
        if (ribbonTab == null)
        {
            ribbonTab = ribbonBar.AddTab(tabName);
        }

        // Agregar grupo de comandos
        RibbonCommandGroup group = ribbonTab.AddCommandGroup("My Group");

        // Agregar botón con acción
        RibbonIcon icon = new RibbonIcon(CommandIcon.Accumulator);
        group.AddCommand("My Action", ACTION_NAME, icon);
    }

    [DeclareUnregister]
    public void UnRegister()
    {
        // Limpiar elementos del Ribbon al descargar
        RibbonBar ribbonBar = new RibbonBar();

        MultiLangString tabName = new MultiLangString();
        tabName.AddString(ISOCode.Language.L_en_US, "My Tab");

        RibbonTab ribbonTab = ribbonBar.GetTab(tabName, true);
        if (ribbonTab != null)
        {
            ribbonTab.Remove();
        }
    }

    [DeclareAction(ACTION_NAME)]
    public void Function()
    {
        MessageBox.Show("Action was executed!");
    }
}

Resultado: Al cargar EPLAN, aparecerá automáticamente una nueva pestaña "My Tab" con un botón que ejecuta tu acción.

5. Combinar con otros atributos

5.1 Register + Action + EventHandler

Puedes combinar DeclareRegister con otros atributos en el mismo script:

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

public class ScriptCompleto
{
    // Inicialización: Se ejecuta al cargar
    [DeclareRegister]
    public void Register()
    {
        MessageBox.Show("Script cargado y listo");
    }

    // Limpieza: Se ejecuta al descargar
    [DeclareUnregister]
    public void UnRegister()
    {
        MessageBox.Show("Script descargado");
    }

    // Acción: Se ejecuta al llamar por nombre
    [DeclareAction("MiAccion")]
    public void MiAccion()
    {
        MessageBox.Show("Acción ejecutada");
    }

    // Event Handler: Se ejecuta automáticamente al cerrar proyecto
    [DeclareEventHandler("Eplan.EplApi.OnUserPreCloseProject")]
    public void AlCerrarProyecto()
    {
        MessageBox.Show("Cerrando proyecto");
    }

    // Start: Se ejecuta al ejecutar el script manualmente
    [Start]
    public void Ejecutar()
    {
        MessageBox.Show("Script ejecutado manualmente");
    }
}

Flujo de ejecución:

  1. Al iniciar EPLAN: Register() se ejecuta
  2. Si ejecutas el .cs: Ejecutar() se ejecuta (además de Register si es la primera vez)
  3. Si llamas "MiAccion": MiAccion() se ejecuta
  4. Al cerrar proyecto: AlCerrarProyecto() se ejecuta
  5. Al cerrar EPLAN: UnRegister() se ejecuta

6. Configurar carga automática en EPLAN

6.1 Ubicación de scripts

Para que un script se cargue automáticamente, debe estar en una de estas ubicaciones:

C:\Users\[TuUsuario]\EPLAN\Scripts\

O en la carpeta de scripts configurada en EPLAN.

6.2 Verificar configuración

  1. Abre EPLAN
  2. Ve a: Opciones > Configuración > Usuario > Gestión > Scripts
  3. Verifica que la opción de carga automática esté activada

6.3 Ver scripts cargados

Para ver qué scripts están actualmente cargados:

  • Utilidades > Scripts > Gestionar scripts cargados

Aquí puedes ver, cargar y descargar scripts manualmente.

7. Buenas prácticas

7.1 Mantén Register rápido

El método Register se ejecuta al iniciar EPLAN. Si tarda mucho, retrasará el inicio.

Mal:

[DeclareRegister]
public void Register()
{
    // Operación muy lenta
    for (int i = 0; i < 10000000; i++)
    {
        // procesamiento pesado
    }
}

Bien:

[DeclareRegister]
public void Register()
{
    // Solo configuración básica y rápida
    Settings settings = new Settings();
    settings.SetBoolSetting("USER.MiConfiguracion", true, 0);
}

7.2 Siempre implementa UnRegister

Si creas recursos en Register (archivos, conexiones, elementos de UI), límpialos en UnRegister.

Principio: Si lo creas en Register, destrúyelo en UnRegister.

[DeclareRegister]
public void Register()
{
    // Crear ribbon tab
    RibbonBar ribbonBar = new RibbonBar();
    ribbonTab = ribbonBar.AddTab(tabName);
}

[DeclareUnregister]
public void UnRegister()
{
    // Remover ribbon tab
    if (ribbonTab != null)
    {
        ribbonTab.Remove();
    }
}

7.3 Manejo de errores

Siempre usa try-catch en Register y UnRegister para evitar que un error bloquee EPLAN:

[DeclareRegister]
public void Register()
{
    try
    {
        // Inicialización
    }
    catch (Exception ex)
    {
        MessageBox.Show("Error al cargar: " + ex.Message);
    }
}

8. Diferencias con otros atributos

CaracterísticaDeclareRegisterStartDeclareActionDeclareEventHandler
Cuándo se ejecutaAl cargar scriptAl ejecutar .csAl llamar acciónAl ocurrir evento
Carga automáticaSíNoNoSolo si Register lo carga
PersistenciaHasta cerrar EPLANUna vezMúltiples vecesMúltiples veces
Uso típicoInicializaciónScripts standaloneAcciones reutilizablesAutomatización reactiva

9. Proyecto del capítulo: Suite de herramientas autocargable

9.1 Objetivo

Crear un script que:

  • Se cargue automáticamente al iniciar EPLAN
  • Registre un event handler permanente
  • Cree una acción ejecutable
  • Se limpie correctamente al cerrar

9.2 Implementación completa

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

public class SuiteAutocargable
{
    // Inicialización al cargar EPLAN
    [DeclareRegister]
    public void Register()
    {
        try
        {
            MessageBox.Show(
                "Suite de Herramientas cargada.\n\n" +
                "Características:\n" +
                "- Event handler al cerrar proyecto\n" +
                "- Acción: MostrarInfo\n" +
                "- Carga automática al iniciar EPLAN",
                "Suite Cargada",
                MessageBoxButtons.OK,
                MessageBoxIcon.Information
            );
        }
        catch (Exception ex)
        {
            MessageBox.Show("Error al cargar: " + ex.Message);
        }
    }

    // Limpieza al cerrar EPLAN
    [DeclareUnregister]
    public void UnRegister()
    {
        try
        {
            MessageBox.Show(
                "Suite de Herramientas descargada correctamente.",
                "Suite Descargada",
                MessageBoxButtons.OK,
                MessageBoxIcon.Information
            );
        }
        catch (Exception ex)
        {
            MessageBox.Show("Error al descargar: " + ex.Message);
        }
    }

    // Acción ejecutable
    [DeclareAction("MostrarInfo")]
    public void MostrarInfo()
    {
        try
        {
            string nombreProyecto = PathMap.SubstitutePath("$(PROJECTNAME)");
            string rutaProyecto = PathMap.SubstitutePath("$(PROJECTPATH)");

            MessageBox.Show(
                "Información del Proyecto:\n\n" +
                "Nombre: " + nombreProyecto + "\n" +
                "Ruta: " + rutaProyecto,
                "Información",
                MessageBoxButtons.OK,
                MessageBoxIcon.Information
            );
        }
        catch (Exception ex)
        {
            MessageBox.Show("Error: " + ex.Message);
        }
    }

    // Event handler permanente
    [DeclareEventHandler("Eplan.EplApi.OnUserPreCloseProject")]
    public void AlCerrarProyecto()
    {
        try
        {
            DialogResult resultado = MessageBox.Show(
                "El proyecto se va a cerrar.\n\n¿Deseas continuar?",
                "Confirmación",
                MessageBoxButtons.YesNo,
                MessageBoxIcon.Question
            );

            // Nota: Este ejemplo solo muestra confirmación
            // No cancela el cierre (eso requiere APIs más avanzadas)
        }
        catch (Exception ex)
        {
            MessageBox.Show("Error en event handler: " + ex.Message);
        }
    }
}

9.3 Características del proyecto

Al iniciar EPLAN:

  • Muestra mensaje de bienvenida
  • Event handler queda registrado

Durante uso:

  • Acción "MostrarInfo" disponible en menú
  • Event handler se ejecuta al cerrar proyectos

Al cerrar EPLAN:

  • Muestra mensaje de despedida
  • Limpieza automática

Resumen

En este capítulo aprendiste:

  • Los atributos DeclareRegister y DeclareUnregister permiten carga automática
  • Register se ejecuta al cargar el script (inicio de EPLAN o carga manual)
  • UnRegister se ejecuta al descargar (cierre de EPLAN)
  • Usos típicos: registrar event handlers permanentes, configurar UI, activar debug
  • Se pueden combinar con otros atributos en el mismo script
  • Buenas prácticas: mantener Register rápido, siempre implementar UnRegister, usar try-catch

Preguntas frecuentes

P: ¿El script con DeclareRegister se ejecuta siempre al iniciar EPLAN?

R: Solo si está en la carpeta de scripts configurada y la carga automática está activada. De lo contrario, debes cargarlo manualmente una vez.

P: ¿Puedo tener Start y DeclareRegister en el mismo script?

R: Sí. DeclareRegister se ejecuta al cargar, Start se ejecuta al abrir el .cs manualmente.

P: ¿Qué pasa si no implemento DeclareUnregister?

R: No pasa nada malo, pero si Register crea recursos (UI, archivos, conexiones), no se limpiarán correctamente.

P: ¿Los event handlers registrados con este método persisten entre sesiones?

R: Sí, mientras el script esté configurado para carga automática, los event handlers estarán activos en cada sesión.

P: ¿Puedo descargar el script manualmente?

R: Sí, en Utilidades > Scripts > Gestionar scripts cargados. Al descargar, se ejecutará DeclareUnregister.

Conexiones

Capítulo anterior

Capítulo 14: Event Handlers - Reaccionar a eventos

Próximo capítulo

Capítulo 16: Ejecutar un comando simple con CommandLineInterpreter

En el próximo capítulo comenzarás a explorar el CommandLineInterpreter en profundidad, aprendiendo a ejecutar comandos básicos de EPLAN.

Última actualización: Enero 2025 Tiempo de lectura estimado: 25-30 minutos Código de ejemplo: code/cap-15/Scripts de referencia:

  • EPLAN-Scripting-4.0/01_FirstSteps/04_DeclareRegisterUnregister.cs
  • EPLAN-Scripting-4.0/10_Debug/01_DebugSetting.cs
  • EPLAN-Scripting-4.0/07_RibbonContextMenus/01_Ribbon.cs