Capítulo 20: PathMap - Variables del sistema

Capítulo 20: PathMap - Variables del sistema

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

Variable	Descripción	Ejemplo
$(PROJECTNAME)	Nombre del proyecto sin extensión	”MiProyecto”
$(PROJECTPATH)	Ruta completa del proyecto	”C:\Proyectos\MiProyecto.elk”
$(P)	Directorio completo del proyecto	”C:\Proyectos\MiProyecto.elk”

4.2 Variables de carpetas EPLAN

Variable	Descripción
$(DOC)	Carpeta de documentos de EPLAN
$(MD_PROJECTS)	Carpeta de datos maestros - Proyectos
$(MD_PARTS)	Carpeta de datos maestros - Artículos
$(MD_MACROS)	Carpeta de datos maestros - Macros
$(MD_SYMBOLS)	Carpeta de datos maestros - Símbolos
$(BIN)	Carpeta de binarios de EPLAN
$(EPLAN)	Carpeta de instalación de EPLAN

4.3 Variables de propiedades de proyecto

Variable	Descripción
$(PROJECTPROPERTYFIELD1) a $(PROJECTPROPERTYFIELD30)	Campos personalizados del 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

Aspecto	PathMap	DataModel
Licencia	Gratuito	Premium
Complejidad	Simple	Complejo
Información	Básica	Completa
Uso típico	Nombre, ruta, campos personalizados	Páginas, componentes, conexiones

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