HybridScripting - Helmut-Ortmann/EnterpriseArchitect_hoTools GitHub Wiki

Hybrid Scripting

Purpose

Make a Console Application (*.exe) in C# or Java to do something with your EA Model. You may call it from EA script or the command line. When calling from EA Script you have full EA Integration.

Principle

Make a Console Application (*.exe):

  • Start the Console Application either
    • without a process-id: The Console Application does something with the open EA Model
    • with a process-id: The Console Application does something with the EA Model according to the process-id
      • use an EA Script to synchronously start the Console Application
  • The Console Aplication takes the prameters and does its job

The Console Application you may generate from EA or on basic of the here shown example with your beloved IDE.

Example Call by Script from Context menu

Use C#, Java from your EA Context Menu:

Call C#, Java from Context

Description

You want to integrate C#, Java, or so into EA. With VBScript, JScript or JavaScript EA Integration is easy and well known. Use the Script in a Context Menu of Browser, Diagram, Search-Results. But how to do it with C# or Java? Use the power of Script Integration together with state of the art languages - or simply languages you like most.

It's simple: Just call your C# or Java from within your favorite EA Scripting language. Make the EA integration as you are familiar with and then call C# or Java to make the heavy work. In essence, the sripting language is a small wrapper for Integration.

This works for all EA Versions, without Administration rights to install

With Version 13 EA adds C# and Java support into their developing environment. You can use it, you can look at it how it works, or you make your work with your beloved environment. Sparx names it Hybrid Scripting. hoTools provides the VB Script 'RunCommand' to easily run your C# or Java Console Program from the powerful EA Script Environment.

The things you have to learn are:

  • How do I call C# or Java from VBScript, JScript or JavaScript
  • How do I connect C# or Java to the right EA Repository
  • How do I pass parameters and get the result

You are not confined to C# or Java. If your language support Microsoft COM you can use the here described principles.

EA Environment

SPARX delivers two files:

C#:

  • Interop.EA.dll
  • SparxSystems.Repository.dll

Java:

  • eaapi.jar
  • SSJavaCOM.dll

to use the EA API efficiently. With these files, you can use the EA Hybrid development environment as well as any other IDE you like most. In other words: You can use the power of state of the art languages to perform your scripting. Integrating Scripting in EA is as easy as you know it from the well known Scripting Languages

  • VB Script
  • JavaScript
  • JScript.

This without installing anything or needing Admin rights.

How to use it

RunCommand.vbs contains two wrapper

  • RunCommand() for Java
  • RunCommandJava() for C#

to call your script written in a language supported by SPARX (C#, Java,..). Just one or two lines of code in VB Script.

C#

' Run ping.exe, pass the parameters ProcessID, par1, par2 and return Standard Output
result = RunCommand("ping", "par1 ", "par2")

Java

' Run in folder SparxSystems the class RepositoryInterface and pass the parameters
' ProcessID, par1, par2 and 
' return Standard Output
result = RunCommandJava("c:\temp\java", "SparxSystems.RepositoryInterface", "par1", "par2")

Remarks:

  • SparxSystems is the folder in which the *.java file is located
  • RepositoryInterface is the class to use, the main function is called

Under the hood

Have a look on the two SPARX Resources:

Name Description
RunCommand.vbs VB Script Wrapper to call your *.exe written in an EA supported language (e.g. C#, Java)
RunCommandTest.vbs VB Script Test to show how it works

Configure

Critical for success is to easyly find the files to execute. Some possible solutions are:

C# configuration

  • Use the Windows Environment variable %PATH% to find the *.exe files you want to use for Hybrid Scripting.
  • EA Local path ID

Java configuration

  • Make sure the 'java' is find. E.g. use the Windows Environment variable %PATH% to find java.
  • Make sure that EA finds javac (compiler) during the build.

Examples

Short Technology Description pro cons
Connect EA C# Class Example how to connect to EA Instance by the passed EA process id using the windows ROT (Running Object Table). See 'HybridScriptingConnectEA' in hoTools. Understand, customize to your needs Use the off the shelf EA 'SparxSystems.Repository.dll'
C# Sparx *.exe SPARX Environment, no installation required easy, out of the box, no installation only basic types
Java Sparx *.jar SPARX Environment, no installation required easy, out of the box, no installation only basic types
C# VS2017 *.dll VS2017, register dll, see HybridScriptingDll IDE, full Script integration, all types registration
C# VS2017 *.exe VS2017, no installation, see HybridScriptingExe IDE, no rights only basic types
C# VS2017 *.exe VS2017, no installation, see HybridScriptingAdvanced IDE, no installation only basic types

Best integration offers implementing C# Scripting as an EA Addin. But it's more effort. If you know how you don't need Administration rights for installation.

Of course, there are other possible good solutions!

LINQPad

An easy way to develop and test is to use LINQPad. The following code shows an example:

void Main(string[] args)
{
    // process id
    int pid = 0;
    //
    // Use CMD symbol to check whether you're running in the GUI or from the command line, you can do this as follow
    // see: https://www.linqpad.net/lprun.aspx
#if CMD
        // run from command line via lprun
        if (args != null && args.Length > 0)
        {
            pid = Int32.Parse(args[0]);
            "_".Dump($"Run by Batch for process '{pid}'");
        }
#else
    // run in LINQPad GUI
    "_".Dump("Run by Dialog");
    // Get PID of EA
    Process processEa = Process.GetProcessesByName("EA").FirstOrDefault();
    if (processEa == null)
    {
        MessageBox.Show("","Can't determine running ea.exe instance!");
        return;
    }
    pid = processEa.Id.Dump("ProcessID");

#endif
    // run for found EA instance
    if (pid > 0)
    {
        Program p = new Program(pid);
        EA.Repository rep = p.Repository;
        rep.ConnectionString.Dump();
    }
 
//---------------------------------------------------------
// Get the Repository from the program ID
//---------------------------------------------------------
// This method is used to call this script from EA and access the Repository the call comes from
//
class Program
{
    private EA.Repository _repository = null;
    private int m_ProcessID = 0;
    // get the EA repository from the progid
    public Program(int pid)
    {
        m_ProcessID = pid;
        _repository = SparxSystems.Services.GetRepository(m_ProcessID);
        Trace("Running C# Console Application AppPattern .NET 4.0");
    }
    public EA.Repository Repository
    {
        get { return _repository;}
    }
    public void Trace(string msg)
    {
        if (_repository != null)
        {
            // Displays the message in the 'Script' tab of Enterprise Architect System Output Window
            _repository.WriteOutput("Script", msg, 0);
        }
        Console.WriteLine(msg);

}

References

Books