Capítulo 20: PathMap y variables del sistema EPLAN

Parte III: PathMap y mensajes - Sección 7: Trabajar con strings y variables - Nivel: Principiante

Objetivos de aprendizaje

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

• Entender qué es PathMap y por qué existe
• Comprender el concepto de "variables del sistema"
• Usar PathMap.SubstitutePath() para obtener información del proyecto
• Conocer las variables PathMap más importantes y verificadas
• Saber cuándo usar PathMap en lugar de otras alternativas

Requisitos previos

• Conocer el atributo Start
• Entender strings en C#
• Saber mostrar mensajes con MessageBox

Introducción: El problema que resuelve PathMap

Imagina que necesitas saber el nombre del proyecto actual en tu script. ¿Cómo lo obtienes?

Primera idea (errónea): "Simplemente pregunto al usuario"

string nombreProyecto = MessageBox.Show("¿Cuál es el nombre del proyecto?");

Problema: El usuario tendría que escribirlo manualmente cada vez. ¡Terrible experiencia!

Segunda idea (errónea): "Uso DataModel para acceder al proyecto"

// ❌ Requiere licencia premium
Project proyecto = new ProjectManager().OpenProjects[0];
string nombre = proyecto.Name;

Problema: Requiere licencia premium (DataModel). No es gratuito.

Solución correcta: Usar PathMap

// ✅ Gratuito, automático, sin preguntar al usuario
string nombreProyecto = PathMap.SubstitutePath("$(PROJECTNAME)");

PathMap es la forma gratuita y automática de obtener información del proyecto actual.

1. ¿Qué es PathMap?

1.1 Definición

PathMap es una clase de EPLAN API que permite acceder a variables del sistema predefinidas por EPLAN.

Variables del sistema son valores que EPLAN mantiene automáticamente sobre:

• El proyecto actual (nombre, ruta, propiedades)
• Las carpetas de EPLAN (instalación, datos maestros, etc.)
• El entorno (usuario, computadora, etc.)

1.2 ¿Dónde se define?

using Eplan.EplApi.Base;

PathMap está en el namespace Eplan.EplApi.Base.

1.3 Analogía

Piensa en PathMap como un diccionario donde:

• Las claves son nombres de variables como $(PROJECTNAME)
• Los valores son los datos reales como "MiProyecto"

EPLAN mantiene este diccionario actualizado automáticamente.

2. El método SubstitutePath()

2.1 Sintaxis

string valor = PathMap.SubstitutePath("$(NOMBRE_VARIABLE)");

Parámetro:

• "$(NOMBRE_VARIABLE)" - Nombre de la variable a obtener (siempre entre $( ))

Retorno:

• string - El valor de la variable, o la variable sin sustituir si no existe

2.2 Ejemplo del script oficial

Basado en EPLAN-Scripting-4.0/03_Classes/02_StringPathVariable.cs:

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

public class ObtenerNombreProyecto
{
    [Start]
    public void Function()
    {
        string projectName = PathMap.SubstitutePath("$(PROJECTNAME)");
        MessageBox.Show(projectName);
    }
}

¿Qué hace?

1. Llama a PathMap.SubstitutePath("$(PROJECTNAME)")
2. EPLAN busca la variable PROJECTNAME en su diccionario interno
3. Devuelve el nombre del proyecto actual (por ejemplo: "MiProyecto")
4. Lo muestra en un MessageBox

Nota: No necesitas abrir el proyecto manualmente ni saber de antemano su nombre. EPLAN ya lo tiene.

3. ¿Cómo funciona internamente?

3.1 El proceso de sustitución

Cuando ejecutas:

string valor = PathMap.SubstitutePath("$(PROJECTNAME)");

Internamente EPLAN hace:

1. Lee la cadena "$(PROJECTNAME)"
2. Identifica que hay una variable entre $( )
3. Busca PROJECTNAME en su diccionario interno
4. Sustituye la variable por su valor real
5. Devuelve el resultado

Ejemplo visual:

Input:  "$(PROJECTNAME)"
        ↓ (EPLAN busca en su diccionario)
        PROJECTNAME = "MiProyecto_2025"
        ↓
Output: "MiProyecto_2025"

3.2 Variables no existentes

¿Qué pasa si la variable no existe?

string valor = PathMap.SubstitutePath("$(VARIABLE_INVENTADA)");
// valor = "$(VARIABLE_INVENTADA)"  (sin sustituir)

Si la variable no existe, devuelve la cadena original sin cambios.

Cómo detectarlo:

string valor = PathMap.SubstitutePath("$(PROJECTNAME)");

if (valor.StartsWith("$("))
{
    MessageBox.Show("La variable no fue sustituida. Puede que no exista o no haya proyecto abierto.");
}
else
{
    MessageBox.Show("Nombre del proyecto: " + valor);
}

4. Variables PathMap verificadas

Estas variables están verificadas en los scripts oficiales de EPLAN-Scripting-4.0:

4.1 Variables de proyecto

4.2 Variables de carpetas EPLAN

4.3 Variables de propiedades de proyecto

Importante: Solo usa variables que están verificadas en scripts oficiales.

5. Cuándo usar PathMap

5.1 Casos de uso comunes

1. Obtener información del proyecto actual

string nombreProyecto = PathMap.SubstitutePath("$(PROJECTNAME)");
string rutaProyecto = PathMap.SubstitutePath("$(PROJECTPATH)");

2. Construir rutas de archivos relacionadas al proyecto

string directorioProyecto = PathMap.SubstitutePath("$(P)");
string archivoExport = directorioProyecto + "export.xml";

3. Verificar si hay proyecto abierto

string nombreProyecto = PathMap.SubstitutePath("$(PROJECTNAME)");

if (string.IsNullOrEmpty(nombreProyecto) || nombreProyecto.StartsWith("$("))
{
    MessageBox.Show("No hay proyecto abierto");
    return;
}

4. Acceder a datos maestros

string carpetaArticulos = PathMap.SubstitutePath("$(MD_PARTS)");

5.2 Cuándo NO usar PathMap

No uses PathMap si:

• Necesitas información compleja del proyecto (usa DataModel si tienes licencia, o exporta y parsea)
• Necesitas modificar propiedades (usa comandos CLI con ActionCallingContext)
• La variable no está verificada en scripts oficiales

6. Ejemplo pedagógico: Validar proyecto abierto

6.1 El problema

Muchos scripts requieren que haya un proyecto abierto. ¿Cómo verificarlo de forma gratuita?

6.2 La solución con PathMap

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

public class ValidarProyectoAbierto
{
    [Start]
    public void Function()
    {
        // Obtener nombre del proyecto
        string nombreProyecto = PathMap.SubstitutePath("$(PROJECTNAME)");

        // Verificar si se obtuvo un valor válido
        if (string.IsNullOrEmpty(nombreProyecto) || nombreProyecto.StartsWith("$("))
        {
            MessageBox.Show(
                "No hay ningún proyecto abierto.\n\n" +
                "Por favor, abre un proyecto antes de ejecutar este script.",
                "Error",
                MessageBoxButtons.OK,
                MessageBoxIcon.Warning
            );
            return;
        }

        // Si llegamos aquí, hay un proyecto abierto
        MessageBox.Show(
            "Proyecto abierto: " + nombreProyecto,
            "Información",
            MessageBoxButtons.OK,
            MessageBoxIcon.Information
        );
    }
}

6.3 Explicación del código

¿Por qué verificar con StartsWith("$(")?

Cuando no hay proyecto abierto, PathMap devuelve la variable sin sustituir:

• Con proyecto: "MiProyecto"
• Sin proyecto: "$(PROJECTNAME)" (contiene $()

Si el string devuelto empieza con $(, significa que la variable no se sustituyó.

7. Diferencia con otras aproximaciones

7.1 PathMap vs DataModel

Cuándo usar cada uno:

• PathMap: Información básica del proyecto (nombre, ruta, propiedades)
• DataModel: Información detallada (solo si tienes licencia premium)

7.2 PathMap vs Exportar y parsear

Para información compleja (lista de componentes, conexiones, etc.):

Con PathMap: No es posible Con Export + Parse: Exporta a XML/CSV, luego parsea con System.Xml.Linq (gratuito)

PathMap es solo para información básica del proyecto y del entorno.

8. Buenas prácticas

8.1 Siempre validar el resultado

string valor = PathMap.SubstitutePath("$(PROJECTNAME)");

// Validar ANTES de usar
if (string.IsNullOrEmpty(valor) || valor.StartsWith("$("))
{
    // Manejar el caso de variable no sustituida
    return;
}

// Ahora es seguro usar 'valor'

8.2 Solo usar variables verificadas

Bien:

// Variables verificadas en scripts oficiales
string nombre = PathMap.SubstitutePath("$(PROJECTNAME)");
string ruta = PathMap.SubstitutePath("$(PROJECTPATH)");

Mal:

// Variable NO verificada (puede no existir)
string usuario = PathMap.SubstitutePath("$(USERNAME)");

8.3 Comentar qué variable estás obteniendo

// Obtener nombre del proyecto actual (sin extensión)
string nombreProyecto = PathMap.SubstitutePath("$(PROJECTNAME)");

// Obtener ruta completa del proyecto
string rutaCompleta = PathMap.SubstitutePath("$(PROJECTPATH)");

9. Casos prácticos explicados

9.1 ¿Por qué PathMap en lugar de preguntar al usuario?

Problema: Si pides al usuario que escriba el nombre del proyecto:

• Es tedioso (el usuario ya lo abrió, ¿por qué escribirlo otra vez?)
• Propenso a errores (puede escribirlo mal)
• Mala experiencia de usuario

Solución con PathMap:

• Automático (cero interacción)
• Sin errores (EPLAN lo sabe con certeza)
• Mejor experiencia

9.2 ¿Por qué PathMap en lugar de hardcodear?

Problema: Si hardcodeas el nombre:

string nombreProyecto = "MiProyecto";  // ❌ Hardcodeado

• Solo funciona para ese proyecto específico
• No es reutilizable
• Difícil de mantener

Solución con PathMap:

string nombreProyecto = PathMap.SubstitutePath("$(PROJECTNAME)");  // ✅ Dinámico

• Funciona con cualquier proyecto
• Reutilizable
• Fácil de mantener

Resumen

PathMap es tu herramienta para obtener información básica del proyecto de forma gratuita y automática.

Conceptos clave:

• PathMap.SubstitutePath() sustituye variables del sistema por sus valores reales
• Las variables se escriben entre $( )
• Si la variable no existe, devuelve el string sin sustituir
• Solo usa variables verificadas en scripts oficiales
• Siempre valida el resultado antes de usarlo

Cuándo usar PathMap:

• Obtener nombre del proyecto
• Obtener ruta del proyecto
• Verificar si hay proyecto abierto
• Acceder a carpetas de EPLAN
• Leer campos personalizados del proyecto

PathMap es la alternativa gratuita a DataModel para información básica.

Preguntas frecuentes

P: ¿Por qué las variables llevan $() alrededor?

R: Es la sintaxis que EPLAN usa para identificar variables del sistema. Sin los $(), sería solo un string normal.

P: ¿Puedo usar PathMap sin que haya proyecto abierto?

R: Algunas variables (como las de carpetas de EPLAN) funcionan sin proyecto abierto. Las variables de proyecto requieren que haya uno abierto.

P: ¿Puedo modificar valores con PathMap?

R: No. PathMap es solo lectura. Para modificar, usa comandos CLI como XEsSetProjectPropertyAction.

P: ¿Todas las variables PathMap son gratuitas?

R: Sí. PathMap pertenece a Eplan.EplApi.Base, que es completamente gratuito.

Conexiones

Capítulo anterior

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

Próximo capítulo

Capítulo 21: BaseException - Mensajes del sistema

En el próximo capítulo aprenderás a mostrar mensajes en la ventana "Mensajes de sistema" de EPLAN usando BaseException.

Última actualización: Enero 2025 Tiempo de lectura estimado: 25 minutos Código de ejemplo: code/cap-20/Script de referencia: EPLAN-Scripting-4.0/03_Classes/02_StringPathVariable.cs