ESAPI allows you to write single-file plug-ins, binary plug-ins, and stand-alone apps. The ESAPI Reference Guide explains how to create each of these types. Here I discuss their advantages and disadvantages, and when to use each.
In general, plug-ins are launched from Eclipse and use the currently opened patient. Stand-alone apps are launched as a standard program and can use any patient (as long as only one is opened at a time).
As the name suggests, this type of plug-in consists of a single source file. When you run it in Eclipse (Tools → Scripts), Eclipse will compile the code and execute the Execute method in the Script class.
However, this type of plug-in has many limitations. For one, you’re forced to create all your classes in the same file. This breaks the physical modularity of your code, making classes hard to find and maintain.
Another limitation is that you can’t use external class libraries (like your own or third-party libraries through NuGet). This is because a single source file can’t contain enough information to properly reference external assemblies. You can, however, use those already loaded by Eclipse or in the GAC.
Using a single file, creating complex UIs is difficult. You won’t be able to use tools like WPF. Simple UIs are manageable in a single file, though, like message boxes or a text box with output data.
An advantage with single-file plug-ins is that you don’t need to quit Eclipse each time you run an updated version of your script. This is a problem with binary plug-in scripts.
Personally, I don’t write single-file plug-ins because of their limitations, but they’re not a bad idea for small scripts that write output to a simple display or file.
This type of plug-in is a .NET class library. When you run it in Eclipse, Eclipse loads it (and any dependent libraries) into memory and executes the Execute method in the Script class.
Binary plug-ins don’t have many of the limitations that single-file plug-ins have: you can create a separate file for each of your classes, reference third-party libraries, and create complex UIs using multiple files (for example, using WPF).
One disadvantage, though, is that once you run an binary plug-in in Eclipse, it will lock up your script DLL and you won’t be able to re-compile your script until you restart Eclipse. A solution is to use a plug-in tester (see my post Run and Test Plug-In Scripts from Visual Studio).
Another disadvantage is that, once you run a plug-in in Eclipse, you won’t be able to run any other binary plug-ins with the same name until you restart Eclipse. This situation happens when you’d like to test two versions of your script. A solution is to attach the version of your script to the name of the script DLL (see my post Version Conflicts in ESAPI Scripts).
If you start writing scripts that perform long-running operations with ESAPI, you may want to run these operations on a separate thread to avoid freezing the UI. However, Eclipse calls your plug-in from the main UI thread, the same thread that also holds the patient context. This means that you can’t use a separate thread to run ESAPI operations. One solution is to create another thread for the UI and use the main thread for ESAPI operations (see my post Create ESAPI Scripts That Don’t Freeze the UI).
You should write binary plug-ins when you need to display a non-trivial UI. You should also prefer binary plug-ins if your code will contain multiple classes or use external libraries. The disadvantages I described above are a bit annoying, but they have acceptable work-arounds.
Stand-alone apps are normal Windows applications that happen to use ESAPI as a third-party library. They’re not tied to the Eclipse application in any way.
Stand-alone apps don’t suffer from the limitations of single-file plug-ins or the disadvantages of binary plug-ins. The cost is that you can’t launch them easily from Eclipse (for a work-around, see my post Launch Stand-Alone Apps from Eclipse), and therefore you won’t have access to the Eclipse context (opened patient, plans, images, etc.)
However, you’re free to open any patient you want, as long as only one patient is open at a time. This makes stand-alone apps perfect for batch processing of patients (for example, exporting dose metrics for a list of patients).
Stand-alone apps may or may not have a UI. For example, you can create a console application for a batch run. If you’re creating a UI, you may want to let the user choose a patient to open (and close).
Use single-file plug-ins for very simple scripts that require the Eclipse context, binary plug-ins for most scripts that also require the Eclipse context, and stand-alone apps if you need access to any patient.