Actions ausführen

Einzelne Action

In Kapitel „Menüband", haben wir die Befehlszeile kennengelernt. Über diese Eigenschaft wird EPLAN gesagt, was getan werden soll. Im Script steht deswegen die Klasse CommandLineInterpreter bereit. Sie ist identisch mit unserer grafischen Befehlszeile im Ribbon, wird allerdings vom Programmcode aufgerufen.

Wir erstellen eine neue Datei 01_SingleAction im Ordner 02_RunActions. Das geht am schnellsten, indem man eine bestehende Datei kopiert. Wir können aber auch eine neue leere Datei über das Kontextmenü im Projektmappen-Explorer erzeugen.

Im ersten Beispiel führen wir die Action reports aus, um die Auswertungen zu erzeugen. Dieser Schritt entspricht dem Menüpunkt Werkzeuge > Auswertungen > Projekt auswerten.

Um den CommandLineInterpreter verwenden zu können, müssen wir diesen zuerst initialisieren. Der frei wählbare Name für unser Objekt ist cli.

CommandLineInterpreter cli = new CommandLineInterpreter();

Will man ein Objekt erzeugen, ist der Aufbau gleich oder ähnlich:

Klasse objektName = new Klasse();

Danach müssen wir dem Programm über die Befehlszeile Folgendes mitteilen: Führe Auswertungen erzeugen aus.

cli.Execute("reports");

Der Befehl ist wie folgt aufgebaut:

cli.Execute("ACTIONNAME");

Execute() ist dabei die Methode, um eine Action auszuführen.

Das fertige Script sollte wie folgt aussehen:

using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Scripting;

public class _02_RunActions_01_SingleAction
{
  [Start]
  public void Function()
  {
    CommandLineInterpreter cli = new CommandLineInterpreter();
    cli.Execute("reports");
  }
}

Wir führen nun das Script aus. Im EPLAN-Projekt sollten Auswertungsvorlagen und Betriebsmittel vorhanden sein, um den Programmcode erfolgreich zu testen.

Mehrere Actions

Wir erstellen uns nun die Datei 02_MultipleActions.cs. Da das Script im ersten Beispiel nur eine Action verwendet, ist es nicht sinnvoll, dies über den Programmcode zu realisieren. Ein besserer Weg wäre, mehrere Actions nacheinander auszuführen.

Wir haben bereits einen CommandLineInterpreter initialisiert. Diesen können wir nun auch für alle anderen Actions verwenden. Pro Funktion in einem Script ist somit ein CommandLineInterpreter-Objekt ausreichend.

Vor dem Auswerten der Formulare (Action: reports) werden wir noch einen Prüflauf starten. Hierfür gehen wir ähnlich wie im Beispiel DeclareEventHandler vor und ermitteln die Action mithilfe von Ctrl+^. Wir wählen dazu den Menüpunkt Werkzeuge > Überprüfung > Prüfen an. Danach rufen wir sofort den Diagnose-Dialog auf, allerdings ohne den Prüflauf wirklich auszuführen.

Zusätzlich kann man auch eigene Actions ausführen. Mit DeclareAction haben wir schon eine Action in EPLAN geladen (ActionName). Diese führen wir am Ende des Scripts aus. Wir müssen sicherstellen, dass das Script auch geladen ist (02_DeclareAction.cs).

CommandLineInterpreter cli = new CommandLineInterpreter();     
cli.Execute("XMsgActionStartVerification");
cli.Execute("reports");
cli.Execute("ActionName");

Wir testen nun das Script in EPLAN. Im erscheinenden Dialog für den Prüflauf kann das Schema ausgewählt werden. Die Auswertungen werden ohne visuelle Rückmeldung erzeugt. Dies kann etwas dauern, wenn es sich um ein größeres Projekt handelt.

Wurde vergessen, das Script 02_DeclareAction.cs zu laden, erzeugt EPLAN einen Fehler in den Systemmeldungen. Um diese einzublenden, wählen wir das Symbol am unteren rechten Rand oder gehen über Datei > Extras > Systemmeldungen > Systemmeldungen.

using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Scripting;

public class _02_RunActions_02_MultipleActions
{
  [Start]
  public void Function()
  {
    CommandLineInterpreter cli = new CommandLineInterpreter();

    cli.Execute("XMsgActionStartVerification");
    cli.Execute("reports");
    cli.Execute("ActionName");
  }
}

Action mit Parameter

Wie im Menüband ist es auch in Scripten möglich, Actions mit Parameter auszuführen. In folgendem Beispiel werden wir das Format eines Textes (normaler Text oder Pfadfunktionstext) auf Schriftgröße 20 ändern.

Dazu erstellen wir uns eine Scriptdatei mit dem Namen 03_Action_mit_Parameter.cs. Man kann auch testweise einen Befehl in der Registerkarte über einen Rechtsklick auf Menüband > Menüband anpassen ... > Aktionen > Textformat setzen erstellen.

Beim Hinzufügen des Befehls muss unsere Befehlszeile den in dargestellten Inhalt haben.

Um dies im Code abzubilden, hat der CommandLineInterpreter die Eigenschaft ActionCallingContext. Dies ist eine eigene Klasse.

Der Aufbau ist, wie im Menüband in schon ersichtlich, folgender:

• Action-Name: XGedStartInteractionAction
• Parameter 1: Name
• Wert 1: XGedIaFormatText
• Parameter 2: height
• Wert 2: 20

Um die Parameter mit der Action zu übergeben, initialisieren wir unseren ActionCallingContext ähnlich wie den CommandLineInterpreter:

ActionCallingContext acc = new ActionCallingContext();

Es ist ratsam, für jedes Objekt einen sprechenden Namen zu wählen, z. B. die Abkürzung acc. Der ActionCallingContext hat die Methode AddParameter(). Wie der Name schon sagt, können wir so den Parameter und den dazugehörigen Wert hinzufügen:

acc.AddParameter("Name", "XGedIaFormatText");
acc.AddParameter("height", "20");

Der Befehl ist folgendermaßen aufgebaut:

acc.AddParameter("PARAMETERNAME", "WERT");

Dies kann für alle möglichen Parameter wiederholt werden. Die nun gesammelten Parameter und die dazugehörigen Werte übergeben wir dem CommandLineInterpreter mit der Action.

cli.Execute("XGedStartInteractionAction", acc);

Der Befehl ist wie folgt aufgebaut:

cli.Execute("ACTIONNAME", ACTIONCALLINGCONTEXT);

Wir erstellen nun einen beliebigen Text in EPLAN, markieren ihn und führen anschließend das Script aus.

using Eplan.EplApi.ApplicationFramework;
using Eplan.EplApi.Scripting;

public class _02_RunActions_03_ActionsWithParameter
{
  [Start]
  public void Function()
  {
    CommandLineInterpreter cli = new CommandLineInterpreter();
    ActionCallingContext acc = new ActionCallingContext();

    acc.AddParameter("Name", "XGedIaFormatText");
    acc.AddParameter("height", "20");

    cli.Execute("XGedStartInteractionAction", acc);
  }
}

Action überladen

In diesem Abschnitt muss ich vorab auf etwas hinweisen. Generell wird empfohlen, Actions nicht zu überladen bzw. zu überschreiben. Dies kann sehr gefährlich sein und zu einem Fehlverhalten von EPLAN führen. Dennoch gibt es Anwendungsfälle für das Überschreiben einer Action. Das heißt, es wird nicht die ursprüngliche Action ausgeführt, sondern z. B. eine selbst programmierte Action.

Es gibt Aktionen in EPLAN, bei denen genau aufgepasst werden muss, da es z. B. keine Möglichkeit gibt, diese rückgängig zu machen. Wir wollen für die Aktion Systemstammdaten abgleichen eine Hinweismeldung, zusätzlich zur Warnung von EPLAN, ausgeben, wenn User:innen diese ausführen.

Wir erstellen dazu die Datei 04_ActionOverloading.cs. Dazu benötigen wir den Namen der Ursprungsaction, welchen man über den Diagnose-Dialog herausfindet (XSDShowMatchingMasterDialogAction).

Wir deklarieren unsere Methode mit dem Attribut [DeclareAction("XSDShowMatchingMasterDialogAction", 50)]. Wie man vielleicht erkennen kann, unterscheidet sich das Attribut vom bereits bekannten DeclareAction. Es wird eine Ordnungszahl angegeben, die man wie die Priorität der Action verstehen kann. Mit 50 stellen wir sicher, dass die Action die von EPLAN verwendete überschreibt.

Wir zeigen eine MessageBox mit „Vorsicht" an.

MessageBox.Show("Warning!");

Jede Action benötigt einen ActionCallingContext. Diesen erstellen wir und suchen uns die Ursprungsaction, welche wir dann ausführen. Das funktioniert wie folgt:

ActionCallingContext acc = new ActionCallingContext();
Eplan.EplApi.ApplicationFramework.Action action = 
  new ActionManager().FindBaseActionFromFunctionAction(false);    
action.Execute(acc);

Wir laden das Script und testen die Funktionalität. Nun sollte uns eine Warnung angezeigt werden. Das fertige Script sieht wie folgt aus:

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

public class _02_RunActions_04_ActionOverloading
{
  [DeclareAction("XSDShowMatchingMasterDialogAction", 50)]
  public void Function()
  {
    MessageBox.Show("Warning!");

    ActionCallingContext acc = new ActionCallingContext();
    Eplan.EplApi.ApplicationFramework.Action action =
      new ActionManager().FindBaseActionFromFunctionAction(false);    
    action.Execute(acc);
  }
}