Capítulo 12: El atributo [Start]

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 qué es un atributo en C#
Comprender el propósito del atributo [Start]
Escribir tu primer script funcional en EPLAN
Conocer la estructura mínima de un script
Diferenciar entre MessageBox y BaseException para mostrar información

Requisitos previos

Antes de comenzar este capítulo debes:

Haber completado la Parte I (Capítulos 1-11) sobre fundamentos de C#
Tener EPLAN Electric P8 instalado
Saber ejecutar scripts (Fichero > Extras > Interfaces > Ejecutar script…)
Conocer clases, métodos y namespaces de C#

Introducción

Bienvenido a tu primer contacto con la EPLAN API. Hasta ahora has aprendido C# de forma genérica, pero a partir de este capítulo comenzarás a aplicar esos conocimientos para automatizar EPLAN Electric P8.

La pregunta fundamental es: ¿Cómo sabe EPLAN qué método ejecutar cuando abres un archivo .cs?

La respuesta es simple: mediante atributos de scripting. El más básico y fundamental es [Start].

1. ¿Qué es un atributo en C#?

1.1 Definición

Un atributo en C# es una etiqueta de metadatos que se coloca encima de una clase, método, propiedad o parámetro para indicar información adicional al compilador o al runtime.

Sintaxis:

[NombreDelAtributo]
public void MiMetodo()
{
    // código
}

Los atributos van entre corchetes [] y se colocan justo antes del elemento al que afectan.

1.2 ¿Para qué sirven los atributos?

Los atributos permiten:

Marcar elementos con información especial
Modificar el comportamiento de clases o métodos
Indicar al runtime cómo debe tratar cierto código
Documentar características especiales del código

1.3 Ejemplos de atributos comunes en C#

[Obsolete("Este método está obsoleto, usa el nuevo")]
public void MetodoViejo()
{
    // ...
}

[Serializable]
public class MiClase
{
    // Esta clase puede serializarse
}

[DllImport("user32.dll")]
public static extern int MessageBeep(uint beepType);

En EPLAN, usamos atributos de scripting para indicar qué métodos debe ejecutar el motor de scripts.

2. El atributo [Start]

2.1 ¿Qué es [Start]?

[Start] es un atributo de EPLAN que marca el punto de entrada de un script.

Cuando ejecutas un script en EPLAN (Fichero > Extras > Interfaces > Ejecutar script…), EPLAN busca un método marcado con [Start] y lo ejecuta automáticamente.

Analogía: Es como el método Main() en aplicaciones de consola C#, pero para scripts de EPLAN.

2.2 ¿Dónde se define [Start]?

El atributo [Start] está definido en el namespace:

using Eplan.EplApi.Scripting;

Este namespace contiene todos los atributos de scripting de EPLAN:

[Start] - Punto de entrada
[DeclareAction] - Acciones personalizadas
[DeclareEventHandler] - Manejadores de eventos
[DeclareRegister] / [DeclareUnregister] - Carga automática

2.3 Reglas del atributo [Start]

Para que [Start] funcione correctamente:

Debe aplicarse a un método público

[Start]
public void MiMetodo()  // ✓ Correcto

El método debe ser void (no devolver valor)

[Start]
public void Ejecutar()  // ✓ Correcto

[Start]
public string Ejecutar()  // ✗ Incorrecto

El método no debe tener parámetros (en su forma básica)

[Start]
public void Ejecutar()  // ✓ Correcto

[Start]
public void Ejecutar(string param)  // ✗ Incorrecto

Solo puede haber un método [Start] por script
Debe estar dentro de una clase pública

2.4 ¿Qué pasa si no pongo [Start]?

Si tu script no tiene ningún método marcado con [Start], EPLAN mostrará un error al intentar ejecutarlo:

No se encontró un punto de entrada en el script.

El atributo [Start] es obligatorio para scripts ejecutables.

3. Tu primer script con [Start]

3.1 El script más simple posible

Veamos el script más básico que puedes escribir en EPLAN:

Archivo: 01_HolaMundo.cs

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

namespace MisPrimerosScripts
{
    public class HolaMundo
    {
        [Start]
        public void Ejecutar()
        {
            MessageBox.Show("Scripting is great!");
        }
    }
}

3.2 Análisis línea por línea

Analicemos cada parte del script:

Línea 1-2: Namespaces necesarios

using System.Windows.Forms;      // Para MessageBox
using Eplan.EplApi.Scripting;    // Para el atributo [Start]

System.Windows.Forms - Proporciona MessageBox.Show() para mostrar ventanas de diálogo
Eplan.EplApi.Scripting - Proporciona el atributo [Start]

Línea 4: Namespace (opcional pero recomendado)

namespace MisPrimerosScripts

Organiza tu código. No es obligatorio, pero es buena práctica.

Línea 6: Clase pública

public class HolaMundo

Toda clase que contenga [Start] debe ser pública.

Línea 8-9: Método con [Start]

[Start]
public void Ejecutar()

[Start] - Marca este método como punto de entrada
public - Debe ser público para que EPLAN pueda acceder
void - No devuelve ningún valor
Ejecutar() - El nombre puede ser cualquiera (Ejecutar, Function, Main, Run, etc.)

Línea 11: Código funcional

MessageBox.Show("Scripting is great!");

Muestra una ventana emergente con el mensaje.

3.3 ¿Por qué usar MessageBox en vez de Console.WriteLine?

Pregunta común: “En C# básico usábamos Console.WriteLine(), ¿por qué ahora usamos MessageBox.Show()?”

Respuesta:

EPLAN Electric P8 es una aplicación Windows con GUI (interfaz gráfica), NO una aplicación de consola.

Console.WriteLine() - Escribe en la consola de comandos (EPLAN no tiene consola visible)
MessageBox.Show() - Muestra una ventana de diálogo visible en pantalla

Si usas Console.WriteLine() en un script de EPLAN, el texto se imprimirá… ¡pero no lo verás en ningún lado!

3.4 Ejecutar el script

Pasos:

Abre EPLAN Electric P8
Ve a: Fichero > Extras > Interfaces > Ejecutar script…
Navega a la ubicación de 01_HolaMundo.cs
Selecciona el archivo y haz clic en Abrir
Verás una ventana emergente con el mensaje “Scripting is great!“

4. Variaciones del script básico

4.1 Cambiar el nombre del método

El nombre del método con [Start] puede ser cualquiera:

[Start]
public void Function()  // ✓ Funciona
{
    MessageBox.Show("Hola");
}

[Start]
public void Main()  // ✓ Funciona
{
    MessageBox.Show("Hola");
}

[Start]
public void Run()  // ✓ Funciona
{
    MessageBox.Show("Hola");
}

Recomendación: Usa nombres descriptivos como Ejecutar(), Run(), Function(), o Start().

4.2 Simplificar el namespace

El namespace es opcional. Puedes escribir:

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

public class HolaMundo
{
    [Start]
    public void Ejecutar()
    {
        MessageBox.Show("Scripting is great!");
    }
}

Funciona igual, pero es menos organizado.

4.3 Código con comentarios

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

public class HolaMundo
{
    [Start]
    public void Ejecutar()
    {
        // Mostrar mensaje simple al usuario
        MessageBox.Show("Scripting is great!");

        // El método termina aquí
        return;
    }
}

El return; al final es opcional en métodos void, pero puede ayudar a la claridad.

5. MessageBox vs BaseException

5.1 Dos formas de mostrar mensajes en EPLAN

Existen dos formas principales de mostrar información al usuario en scripts EPLAN:

MessageBox.Show() - Ventana emergente (System.Windows.Forms)
BaseException - Mensajes en la ventana “Mensajes de sistema” de EPLAN (Eplan.EplApi.Base)

5.2 MessageBox.Show()

Namespace: System.Windows.Forms

Características:

Muestra una ventana emergente que bloquea EPLAN hasta que el usuario la cierre
Muy visible e intrusivo
Ideal para mensajes importantes que requieren atención inmediata
Puede tener botones (OK, Yes/No, etc.)

Ejemplo:

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

public class EjemploMessageBox
{
    [Start]
    public void Ejecutar()
    {
        MessageBox.Show("Este es un mensaje importante",
                       "Título",
                       MessageBoxButtons.OK,
                       MessageBoxIcon.Information);
    }
}

Cuándo usar:

Confirmaciones (¿Desea continuar?)
Advertencias críticas
Errores que requieren atención inmediata
Información que el usuario DEBE ver

5.3 BaseException

Namespace: Eplan.EplApi.Base

Características:

Muestra mensajes en la ventana “Mensajes de sistema” de EPLAN
No bloquea la interfaz
Menos intrusivo
El usuario puede revisar los mensajes después
Tiene niveles: Message, Warning, Error

Ejemplo:

using Eplan.EplApi.Base;
using Eplan.EplApi.Scripting;

public class EjemploBaseException
{
    [Start]
    public void Ejecutar()
    {
        // Mensaje informativo
        new BaseException("Proceso completado correctamente",
                         MessageLevel.Message).FixMessage();

        // Advertencia
        new BaseException("Atención: Revisa la configuración",
                         MessageLevel.Warning).FixMessage();

        // Error
        new BaseException("Error al procesar archivo",
                         MessageLevel.Error).FixMessage();
    }
}

Cuándo usar:

Logs de operaciones
Mensajes informativos que no requieren acción inmediata
Advertencias no críticas
Registro de progreso de operaciones largas

Importante: Para ver los mensajes de BaseException, debes abrir la ventana “Mensajes de sistema” en EPLAN (Ver > Mensajes de sistema).

5.4 ¿Cuál usar?

Regla general:

MessageBox: Cuando necesitas la atención inmediata del usuario
BaseException: Para registro y logging de operaciones

Muchos scripts usan ambos:

BaseException para logs detallados
MessageBox solo para confirmaciones o errores críticos

6. Proyecto del capítulo: Tres variaciones de Hola Mundo

6.1 Objetivo

Crear tres scripts que demuestren diferentes formas de usar [Start]:

HolaMundo_MessageBox.cs - Usando MessageBox básico
HolaMundo_MessageBoxAvanzado.cs - MessageBox con opciones
HolaMundo_BaseException.cs - Usando BaseException

6.2 Script 1: MessageBox básico

Archivo: 01_HolaMundo_MessageBox.cs

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

public class HolaMundo_MessageBox
{
    [Start]
    public void Ejecutar()
    {
        // Mensaje más simple posible
        MessageBox.Show("¡Hola desde EPLAN API!");
    }
}

Qué hace: Muestra una ventana emergente con mensaje básico.

6.3 Script 2: MessageBox avanzado

Archivo: 02_HolaMundo_MessageBoxAvanzado.cs

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

public class HolaMundo_MessageBoxAvanzado
{
    [Start]
    public void Ejecutar()
    {
        // MessageBox con título, icono y botón personalizado
        MessageBox.Show(
            "Este es tu primer script en EPLAN API.\n\n" +
            "Has usado correctamente el atributo [Start] para " +
            "marcar el punto de entrada del script.",
            "Felicitaciones",
            MessageBoxButtons.OK,
            MessageBoxIcon.Information
        );
    }
}

Qué hace: Muestra mensaje con título, icono y formato multilínea.

6.4 Script 3: BaseException

Archivo: 03_HolaMundo_BaseException.cs

using Eplan.EplApi.Base;
using Eplan.EplApi.Scripting;

public class HolaMundo_BaseException
{
    [Start]
    public void Ejecutar()
    {
        // Mensaje informativo en "Mensajes de sistema"
        new BaseException(
            "Script ejecutado correctamente usando el atributo [Start]",
            MessageLevel.Message
        ).FixMessage();
    }
}

Qué hace: Registra un mensaje en la ventana “Mensajes de sistema” de EPLAN.

Para verlo: Después de ejecutar el script, abre Ver > Mensajes de sistema en EPLAN.

6.5 Prueba los tres scripts

Ejecuta cada script desde EPLAN
Observa las diferencias:
- Scripts 1 y 2: Ventana emergente que debes cerrar
- Script 3: Nada visible hasta que abras “Mensajes de sistema”

7. Errores comunes

7.1 Olvidar el using Eplan.EplApi.Scripting

Error:

using System.Windows.Forms;

public class MiScript
{
    [Start]  // Error: No se reconoce 'Start'
    public void Ejecutar()
    {
        MessageBox.Show("Hola");
    }
}

Solución:

using System.Windows.Forms;
using Eplan.EplApi.Scripting;  // Agregar este using

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

7.2 Método privado

Error:

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

public class MiScript
{
    [Start]
    private void Ejecutar()  // ✗ Private no funciona
    {
        MessageBox.Show("Hola");
    }
}

Solución:

[Start]
public void Ejecutar()  // ✓ Debe ser public
{
    MessageBox.Show("Hola");
}

7.3 Método que devuelve valor

Error:

[Start]
public string Ejecutar()  // ✗ [Start] debe ser void
{
    return "Hola";
}

Solución:

[Start]
public void Ejecutar()  // ✓ Debe ser void
{
    MessageBox.Show("Hola");
}

7.4 Método con parámetros

Error:

[Start]
public void Ejecutar(string mensaje)  // ✗ No puede tener parámetros
{
    MessageBox.Show(mensaje);
}

Solución:

[Start]
public void Ejecutar()  // ✓ Sin parámetros
{
    string mensaje = "Hola";  // Definir dentro del método
    MessageBox.Show(mensaje);
}

Resumen

En este capítulo aprendiste:

Qué son los atributos en C# y para qué sirven
El atributo [Start] marca el punto de entrada de un script EPLAN
Cómo escribir el script más simple posible con [Start]
Las reglas del atributo [Start]: método público, void, sin parámetros
La diferencia entre MessageBox (ventana emergente) y BaseException (mensajes de sistema)
Los errores comunes al usar [Start]

Preguntas frecuentes

P: ¿Puedo tener varios métodos en la misma clase además de [Start]?

R: Sí, puedes tener todos los métodos adicionales que necesites. Solo el método con [Start] se ejecutará automáticamente, pero puedes llamar a otros métodos desde él.

P: ¿El nombre de la clase importa?

R: No. Puedes llamar a la clase como quieras. Solo debe ser pública.

P: ¿Puedo tener múltiples clases con [Start] en el mismo archivo?

R: Técnicamente sí, pero solo se ejecutará el primer [Start] que encuentre EPLAN. No es recomendable. Usa un archivo .cs por script.

P: ¿Qué pasa si mi script tiene un error de sintaxis?

R: EPLAN mostrará un error de compilación al intentar ejecutarlo. Revisa el mensaje de error para identificar el problema.

Conexiones

Capítulo anterior

Capítulo 11: Manejo de errores - Completaste los fundamentos de C#

Próximo capítulo

Capítulo 13: [DeclareAction] - Acciones personalizadas

En el próximo capítulo aprenderás a crear acciones personalizadas que pueden ejecutarse desde el menú de EPLAN y asignarse a botones de la cinta de opciones.

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