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

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:

Al iniciar EPLAN: Register() se ejecuta
Si ejecutas el .cs: Ejecutar() se ejecuta (además de Register si es la primera vez)
Si llamas “MiAccion”: MiAccion() se ejecuta
Al cerrar proyecto: AlCerrarProyecto() se ejecuta
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

Abre EPLAN
Ve a: Opciones > Configuración > Usuario > Gestión > Scripts
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ística	[DeclareRegister]	[Start]	[DeclareAction]	[DeclareEventHandler]
Cuándo se ejecuta	Al cargar script	Al ejecutar .cs	Al llamar acción	Al ocurrir evento
Carga automática	Sí	No	No	Solo si Register lo carga
Persistencia	Hasta cerrar EPLAN	Una vez	Múltiples veces	Múltiples veces
Uso típico	Inicialización	Scripts standalone	Acciones reutilizables	Automatizació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