Agenda – (Basics)

Ziele
• Calls – Scripts – API
• Was ist ein Script?
• Grundlagen C#
• Namespaces API / scripting
• Wie ist ein Script zu erstellen?
• „Ausführen“ – „Laden“ eines Scripts
• EPLAN-Settings beeinflussen
• Menü- und Symbolleiste
Call - Script - API

Call externe Aufrufe von P8-Aktions

(auch eigene Aktions)

Script einfache API - Funktionalität

kompiliert durch P8 während der Ladeprozedur
Aufruf von mehreren Aktionen möglich
Reaktionen auf Events

API komplexes Programmier-Interface;

bidirektionaler Zugriff auf EPLAN – Objekte
Was ist ein script?

Files
… Extension .VB or .CS
… enthält Program-Logic .NET VB or C#

in EPLAN
… Files werden geladen, kompiliert und
ausgeführt
(ohne zusätzliches Development-Tool)

Development
… kann mittels Text-Editor realsiert werden
… oder mittels Development-Tool:
Syntax .NET VB
.NET Visual Basic
• File-Extension .vb
• Ende einer Zeile: <CRLF>
• Kommentare starten mit '

VB Code - example:

Documentation:
http://openbook.galileocomputing.de/vb_net/

Download “Visual Studio Community”

https://visualstudio.microsoft.com/de/downloads/
Syntax .NET C#
.NET Visual C#
• File-Extension .cs
• Ende einer Zeile: Semikolon
• Kommentare starten mit //
• Zwischen Groß- und Kleinschreibung wird unterscheiden

C# Code - example:

Documentation:
http://openbook.rheinwerk-verlag.de/visual C# 2012/

Download “Visual Studio Community”

https://visualstudio.microsoft.com/de/downloads/
Syntax .NET C#
.NET Visual C#
• Strukturiert in Klassen („class“)
und Funktionen

C# Code - example:

Class: Funktion mit Return-Value; „void“

Beginn – Ende mittels {} Beginn – Ende mittels {}
Was passiert bei Syntax-Fehlern?

Was kann bei Laden in EPLAN

passieren…?

EPALN versucht das Script zu kompilieren.

Falls Syntax - Fehler bestehen, wird eine EPLAN - Systemmeldung erzeugt.
C# Fehlerbehandlung

Fehlerbehandlung
C# : Try - catch
try
{
// .. Do something;
}
catch (System.Exception ex)
{
// .. Handle the error - case

// .. Do something;
}
finally
{
// .. Do something
}
C# Deklarieren und Initialisieren einer Variable

Variable
C# : Deklarieren und Initialisieren einer Variable
int iZaehler;
iZaehler = 1000;

bool bEntscheidung;
bEntscheidung = true;

string sText = string.Empty;

sText = "HelloWorld";

// Objekte anlegen
CommandLineInterpreter oCLI = new CommandLineInterpreter();

Basic_Datentyp.cs
C# Kontrollstrukturen

Kontrollstrukturen
C# : if else
if (Bedingung)
{
//instruction1
}
else
{
//instruction 2
}

C# : switch
switch (oDialogResult)
{
case DialogResult.Yes:
// instruction Yes;
break;
case DialogResult.No :
// instruction No;
break;
default:
//instruction Cancel;
}

Basic_Kontrollstrukturen_If_Ausführen.cs; Basic_Kontrollstrukturen_Switch_Ausführen.cs
C# Schleifen

Schleifen
C# : for
for(int i=0; i<=10; i++)
{
// for führt eine Anweisung oder einen Anweisungsblock aus, solange ein angegebener boolescher Ausdruck true ergibt. Z.B. "i<=10"
// instruction;
}

C# : while
while (Bedingung)
{
// Eine while-Schleife wird ausgeführt, solange die Bedingung true ist.
// Die Schleife wird beendet, wenn die Bedingung false ist.
// instruction1;
}

Basic_Schleifen_For_Ausführen.cs; Basic_Schleifen_While_Ausführen.cs
Möglichkeiten im Scripting

Was ist im Scriptig möglich?

• Erstellen eigener Actions

• Manipulation von Setting
• Nutzen der Commandline-Funktionen
• Reagieren auf EPLAN-Events
• Erzeugen von Menüpunkten, Button
• Verwenden von System.IO
• Implementierung einfacher Dialoge
Wie starten Sie ein Script?

Wie können die Funktionen

gestartet werden?
Script aktivieren:
“Dienstprogramme” – “Scripte” – “Ausführen”
(kompiliert das Script und führt es unmittelbar aus)

“Dienstprogramme” – “Script” – “Laden”

(kompiliert das Script, regiestriert enthaltenen Actions)

• Aufruf registrierter Actions mittels

Menüpunkt, Button, externem Call
“Laden” oder “Ausführen” - Startattribute

Ausführen …
Dienstprogramme> Scripte > Ausführen... ; nur temporär verfügbar.

Laden…
Dienstprogramme> Scripte > Laden... ; Script ist permanent verfügbar.

Attributs - see help: Eplan.EplApi.Scripting Namespace

@ VB C# Description
Attribute for a scripts to
<Start()> [Start]
„Run“

Attribute used to register

<DeclareAction(„Actionname“)> [DeclareAction("Actionname")]
an action in EPLAN.

Attribute used to react to

EPLAN-events
<DeclareEventHandler(„Eventname“)> [DeclareEventHandler("Eventname")]
(Start / End of EPLAN,
Open projects, …)

Attribute used to
<DeclareMenu()> [DeclareMenu]
implement menu-points.
Verweise auf EPLAN.EplApi.*dll

• API based on .NET Framework

(COM not supported)
• Assembly - files stored in the BIN-folder of EPLAN
Namespaces scripting
Folgende Namespaces stehen im Scripting zur Verfügung:
Eplan.EplApi.AFu.dll enthält:
Eplan.EplApi.ApplicationFramework,
Eplan.EplApi.Scripting

Eplan.EplApi.Baseu.dll enthält:
Eplan.EplApi.Base

Eplan.EplApi.Guiu.dll enthält:
Eplan.EplApi.GUI

Eplan.EplApi.CommandLineActions;
call via CommandLineInterpreter
using System;

.NET:
using System.Collections.Generic;
using System.Text;
using System.IO;
System; // ====
using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Base; http://www.eplan.help/help/platformapi/2.7/en-us/help/index.html
System.XML using Eplan.EplApi.Gui;
using Eplan.EplApi.Scripting;
System.Drawing using System.Windows.Forms;
// ====
System.Windows.Forms
Einstellungen im “Script”- Projekt

EPLAN 2.7
uses .Net Framework 4.5.2
C#: example – HalloWelt “Start” - Script

C# : example

SEM_HalloWelt.cs
C#: example – HalloWelt “Start” - Script

C# : example

SEM_HalloWelt.cs
C#: example – HalloWelt “Start” - Script

C# : example

SEM_HalloWelt.cs
C#: example – Wichtige Benutzereinstellungen Setzen

C# : SEM_ScriptEinstellungen_Ausführen.cs

SEM_ScriptEinstellungen_Ausführen.cs
EPLAN – Settings (Benutzer, Station, Firma)

Read string - setting

Eplan.EplApi.Base.Settings oSettings = new Eplan.EplApi.Base.Settings();
string sWert = oSettings.GetStringSetting(sSettingName,0);

Set bool - setting

Eplan.EplApi.Base.Settings oSettings = new Eplan.EplApi.Base.Settings();
oSettings.SetBoolSetting(sSettingName,value,0);
SEM_NurEineZwischenablageNutzen_Ausführen.cs
EPLAN – Settings (Benutzer, Station, Firma)

Name und Typ eines Settings sind zu

ermitteln:

“Einstellungspfad in die
Zwischenablage kopieren”

- oder “Einstellungen exportieren”.

Export des Settings-Bereiches
in eine Datei.

Name of the setting:

USER.MacrosGui.OneClipBoard
SEM_NurEineZwischenablageNutzen_Ausführen.cs
C#: Example – Actions mit Parameter

C# : example

Parameter - value Description

MyAction Name of the EPLAN-action
/sName:Test /Parameter:Value

 Erstellen eines Button, um die Action zu starten.

SEM_SetBoolSetting4Toggle_Laden.cs
C#: Example – "Laden" - Action mit Menüeintrag

C# : example
class example
{
[DeclareAction("MyAction")]
public bool MyAction(string sName)
{
// Action with parameter
MessageBox.Show("Hallo Welt, schöne Grüße von ", "Begrüßung");
return true;
}

[DeclareMenu]
public void MenuFunction()
{
Eplan.EplApi.Gui.Menu oMenu = new Eplan.EplApi.Gui.Menu();
oMenu.AddMenuItem("MyAction_Call", "MyAction");
}
}

 Please design the script and load it!

Define the action: [DeclareAction("MyAction")]
public bool MyAction(string sName)

Define the menu: Fügt einen Menüpunkt unter

oMenu.AddMenuItem “Dienstprogramme” ein.
EPLAN – Informationen über Actions
Actions = EPLAN - Aktionen

Wie kann der Name einer Action ermittelt werden?

…siehe EPLAN-Hilfe: „EPLAN-Aktionen: Übersicht“

…siehe API-Hilfe: „Eplan.EplApi.CommandLineActions“
EPLAN - Actions (internal use!)

EPLAN Diagnostics?

Execute action
Name and Menu-ID

DumpInfo-Dialog
=>[Strg]+[^] Germany

=>[CTRL]+[\] UK

=>[CTRL]+[§]

=>[CTRL]+[|] US

=>[CTRL]+<]>
EPLAN - Actions

EPLAN –Aktionen ausführen

ActionCallingContext und CommandLineInterpreter()
//-----------------------------
ActionCallingContext oContext1 = new ActionCallingContext();
oContext1.AddParameter("configscheme", "Device tag list");
oContext1.AddParameter("language", "de_DE");
oContext1.AddParameter("destinationfile", @"$(MD_DOCUMENTS)\$(PROJECTNAME)_BM-LISTE.txt");
oContext1.AddParameter("recrepeat", "1");
oContext1.AddParameter("taskrepeat", "1");
new CommandLineInterpreter().Execute("label", oContext1);
//-----------------------------

oder
new CommandLineInterpreter().Execute("label /configscheme:\"Device tag list\" /language:de_DE
/destinationfile:\"$(MD_DOCUMENTS)\\$(PROJECTNAME)_BM-LISTE2.txt\" /recrepeat:1 /taskrepeat:1
/showoutput:1");

SEM_CommandLineInterpreterBeschriftungsAusgabe_Ausführen.cs
EPLAN – Aktionen protokollieren
Aktionen protokollieren

Meldungen in die Systemmeldungen schreiben.

BaseException oBexMessage = new BaseException("Aktion erfolgreich ausgeführt", MessageLevel.Message);

oBexMessage.FixMessage();

BaseException oBexError = new BaseException("Aktion wurde nicht erfolgreich ausgeführt.", MessageLevel.Error);

oBexError.FixMessage();

EPLAN_ExampleSystemmeldungen_Ausführen.cs
C#: Progress - Fortschrittsanzeige

C# : example

EPLAN_ProgressBarSimple_Ausführen.cs
C#: Menü und Kontextmenü

C# : Beispiel für Menü und Kontextmenü

Siehe Hilfe: Eplan.EplApi.Gui Namespace – class "Menu"

AddMainMenu Add‘s a new main- and a new menu-item;
Retun value: ID of the own menu-item
AddMenuItem Add‘s a menu – item at a defined position
AddPopupMenuItem Add‘s a popup - menu – item

Siehe Hilfe : Eplan.EplApi.Gui Namespace – class "ContextMenu"

Eplan.EplApi.Gui.ContextMenu oCon = new Eplan.EplApi.Gui.ContextMenu();
Eplan.EplApi.Gui.ContextMenuLocation oConLoc = new
Eplan.EplApi.Gui.ContextMenuLocation("PmPageObjectTreeDialog", "1007");
oCon.AddMenuItem(oConLoc,"Test", "MyAction", true, false);

Anzeige des Names des Kontextmenü‘s nach Aktivieren

des Settings:
USER.EnfMVC.ContextMenuSetting.ShowIdentifier", true, 0);

EA_MenuVerzeichnisse_Laden.cs; SEM_Kontextmenüerweiterung_Laden.cs
C#: Menü und Kontextmenü

C# : Beispiel für Menü und Kontextmenü

class SEM_KontextmenüErweiterung_Laden
{
[DeclareMenu]
public void oConFunction()
{
// SPS Navigator: XPlcPrjDataTreeTab, 1012
// Last called action from (context)menu : XPlcReAddressDlgShow, Menu text : Projektdaten: SPS: Adressieren
Eplan.EplApi.Gui.ContextMenu oConPLC = new Eplan.EplApi.Gui.ContextMenu();
Eplan.EplApi.Gui.ContextMenuLocation oConLoc = new Eplan.EplApi.Gui.ContextMenuLocation("XPlcPrjDataTreeTab", "1012");
oConPLC.AddMenuItem(oConLoc, "Adressieren", "XPlcReAddressDlgShow", true, false);
}
}

EA_MenuVerzeichnisse_Laden.cs; SEM_Kontextmenüerweiterung_Laden.cs
C#: Example

C# : example: „Project_Closing_Functions.cs“

see help: „Eplan.EplApi.CommandLineActions Namespace”

“Eplan.EplApi.Base Namespace” – class Progress”

 toDo: Erzeugen einer Action für „Finale“ Arbeiten:

1. Ermittlen des aktuellen EPLAN-Projektes

2. „Finale“ Arbeiten zusammen ausführen, z.B.

PDF,
Backup,
…

3. Anzeige Progress
EPLAN – Automatisiert bearbeiten

Nutzen der EPLAN-Funktion

„Automatisiert bearbeiten“
um erste Sourcen zu erhalten
(Commandline-Actions,
Progress)

Im Script-Verzeichnis
befindet sich das erstellte
Script „workshop.cs“
EPLAN – Einstellungen

Benutzereinstellung:

EA_SetBoolSetting3Toggle_Ausführen.cs
EPLAN – Properties - Eigenschaften

EPLAN -Eigenschaften
• Jedes Objekt (project, page, functions) hat Eigenschaften
• Eigenschaften werden über eine eindeutige Nummer identifiziert
// PropertyIdentName
PropertyId
PropertyValue
PropertyIndex
• Eigenschaften sind typisiert (bool, integer, string ...)

CommandLineInterpreter oCLI = new CommandLineInterpreter();

ActionCallingContext oACC = new ActionCallingContext();

// Projekteigenschaft: Kommission <10014>

oACC.AddParameter("PropertyId", "10014");
oACC.AddParameter("PropertyIndex", "0");
oACC.AddParameter("PropertyValue", "EPLAN");

oCLI.Execute("XEsSetProjectPropertyAction", oACC); {

EA_Projekteigenschaft1Setzen_Ausführen.cs
EPLAN – Projektname ermitteln

….
string sProjectName1 = PathMap.SubstitutePath("$(PROJECTNAME)");
string sProjectName2 = projectName();
…..}
public string projectName()
{
// Ermittelt das aktuelle Projekt und gibt den vollständigen Projektnamen zurück
ActionCallingContext oContext = new ActionCallingContext();
oContext.AddParameter("type", "PROJECT");
bool ret = new CommandLineInterpreter().Execute("selectionset", oContext);

if (ret != false)
{
string sBack = string.Empty;
oContext.GetParameter("PROJECT", ref sBack);
return sBack;
}
return string.Empty;
}
}

[DeclareEventHandler("Eplan.EplApi.OnUserPreCloseProject")]
public void MyEventHandlerFunction1(IEventParameter iEventParameter)
{
EventParameterString oEventParameterString = new EventParameterString(iEventParameter);
string sProjectName3 = oEventParameterString.String;
… }

EPLAN_ProjektnameErmitteln_Laden.cs
EventHandler

Mechanismus um auf Benachichtigungen von EPLAN

zu reagieren

Events werden über den Namen identifiziert.

Siehe API-Hilfe:
Eplan.EplApi.ApplicationFramework.Events Namespace
Event Description

Eplan.EplApi.OnMainStart Send when the Main Start is done; when a mainframe is available

Eplan.EplApi.OnMainEnd Send when the Main End of EPLAN starts.

Eplan.EplApi.OnUserPreCloseProject Before closing a project

Eplan.EplApi.OnPostOpenProject After opening a project

EPLAN_DeclareEventHandler_Laden.cs
Script debuggen

 Set: (Erzeugt eine lokale Kopie, wenn gesetzt)

Settings oSetting = new Settings();
oSetting.SetBoolSetting("USER.EplanEplApiScriptLog.DebugScripts", true, 0);

 Start EPLAN
 Entwicklungsumgebung mit Projekt öffnen.
 Das Script erneut in EPLAN laden.
(Dienstprogramme; Scripte entladen – laden)

 EPLAN an den Prozess anhängen.

(„Debuggen – An den Prozess anhängen“)

 DebugScript laden.
Name: „Debug_<scriptname>
(Name: „Debug_<scriptname>
(Das DebugScript liegt im „tmp“ Ordner. „$(TMP)“ kontrollieren!)
(Das DebugScript darf beim öffnen nicht verändert werden.)

 Im DebugScript Haltepunkte setzen.

(Der Haltepunkt ist ein ausgefüllter roter Kreis.)

 Start der Action.

([F11] Einzelschritt im Debugmodus.)
Übersicht - Scripting / API

Scripting API

Acting on Events  

Creating Actions  
Start Functionality  
without loading
Design Menu  
Toolbar, (Contextmenu)
Read/Set Setting () 
Read/Set Properties () 

Export EPLAN-Data  
(Labeling, …)
Übersicht - API

API
Create / Modify EPLAN-Objects directly 
(project, pages, function, articles, …….)
Change layer-information in the project 
Change parts directly; 
additional influence on the functionality in the
parts-management-dialogs
Create own check functionality 
(“Prüfläufe” – “Verifications“)
Access project message database 
handle events connected with interactive work in GED ()
(not internal dialogs)
 Perspektiven im Engineering

„Wir freuen uns, mit Ihnen

gemeinsam Zukunft gestalten zu dürfen!“

EPLAN Software & Service GmbH & Co. KG 42