EasyScript.NET  100% .NET Scripting Toolkit for .NET applications    NET 4.0 .NET 3.5

Product Overview

EasyScript.NET enables Software Developers to integrate scripting capabilities directly into their .NET applications.  EasyScript is a .NET Assembly wrapper for S# (aka Script.NET) which is a powerful scripting tool for .NET.  EasyScript adds features to make it easier to use and much more powerful, especially when it comes to text generation such as XML documents. S# is a very easy to use but powerful scripting language, much like Javascript but easier and better.  You have access to the entire .NET Framework from your scripts - very powerful indeed.  The download includes some S# examples which demonstrate its features.  Use EasyScript when:

• You need your users to be able to write scripts which call methods on your .NET objects.

• You need to generate documents, such as XML or HTML.

Allow your users to Automate your Application with Scripting

Application Scripting has been around for a long time, but there hasn't been any good .NET scripting solutions available - until now.  EasyScript gives you the ability to script your application and includes a ready to use Script Editor (see screenshot below).  You can pass in any number of .NET objects as parameters to your script and all of their properties and methods are available to your script code which you can call directly (see below for example code).  You can even pass in Lists of anonymous objects generated by LINQ queries.  Please see our sample download to see this done with our FileDb product.

Generate XML Documents

Besides ready to use application scripting, EasyScript can generate text much the same way as PHP and Microsoft classic ASP (webserver) technology.  This is the ability to mix plain text and "in-line" script code.  For example,

This is <%="inline code"%>

The text inside the <% and %> delimiters is evaluated as S# script code.  This example just prints the "inline code" text as-is since its just a literal string.  You would normally output variable values, such as from a database or remote connection.

This ability to intermix code and text adds a powerful dimension to your .NET applications.  Its a powerful text generation ability, for example to generate XML.  Here's a simple example of generating XML documents.  As you can see, its structured just like a javascript program, with the entry point at the top of the file and any number of functions.  custOrderDetails is passed in as a parameter from the host application.  In this case, its a hierarchical list of anonymous objects from a LINQ query.  One XML document is created for each Order of each Customer.  Each time through the loop, the host App's Form.OnXmlDoc is called.  Form is another parameter which was passed in to the script - its the main Form of the host App.

foreach( cust in custOrderDetails ) {   foreach( order in cust.Orders )   {     GenXmlDoc( cust, order );     Form.OnXmlDoc( order.OrderID );   } } //----------------------------------------------- function GenXmlDoc( cust, order ) {   total = 0; %> <?xml version="1.0" encoding="utf-8"?> <ORDER>   <ORDER_ID><%=order.OrderID%></ORDER_ID>   <CUST_ID><%=cust.CustomerID%></CUST_ID>   <CUST_NAME><%=cust.CompanyName%></CUST_NAME>   <ORDER_ITEMS>   <% foreach( orderDetail in order.OrderDetails )   {     amt = orderDetail.UnitPrice * orderDetail.Quantity;     total+= amt;   %>     <ORDER_ITEM>     <PROD_ID><%= orderDetail.ProductID %></PROD_ID>     <PROD_NAME><%= orderDetail.ProductName %></PROD_NAME>     <PRICE><%= orderDetail.UnitPrice %></PRICE>     <QUANTITY><%= orderDetail.Quantity %></QUANTITY>     <AMOUNT><%= amt %></AMOUNT>     </ORDER_ITEM>   <% } %>   </ORDER_ITEMS>   <TOTAL><%=total%></TOTAL> </ORDER> <% } %>

After the script runs (upon return from Scripter.RunScript), the text output is available in the Output property of the Scripter.  Example:

scripter.RunScriptFile( "GenXmlDoc.script", custList ); string sXmlDoc = scripter.Output;

The great thing about this method of mixing script and text is that most HTML/XML tools allow for these delimiters so you can edit them in a WYSIWYG tool.  Furthermore, your script maintains the structure of what you are trying to create so its easier to work with.  Have you ever tried doing the same thing in C# code?  Its really hard to read and understand what is being done.  But notice how orderly the above code looks.  All of the script output goes to Scripter.Output for you to retrieve after the script is run.

Here are some important features of EasyScript:

Add your application .NET objects to the scripting environment and call methods and properties on them directly in your scripts Use the function results directly in your code, without redirecting standard error and standard output Generate HTML/XML documents using the advanced features of EasyScript Built-in script editor and tester for super-easy drop-in integration in your application Easy to use, well documented interface Call functions directly instead of writing 'stub' code - the results of the functions are available for direct use after the function completes Pass function parameters dynamically - pass the function parameters 'on the fly', directly from your own application or script Pass unlimited parameters and use them directly in your code by name, just as if it were a locally declared variable. Use in any .NET application, including Windows Services. Thread safe - the Toolkit can be used in any multi-threading (and multi-processing) environment Logging facility Your users don't need to learn .NET programming to write scripts - but - the entire .NET Framework is available.

Advanced features

EasyScript also has these advanced features::

Built-in Script Editor and Tester Text generation - ability to add "inline text".  It works much the same way as classic ASP and PHP (see example below) Ability to include other scripts using #include directive Ability for hosting application to manage script saving and loading via Events (to a database, for example).

One of the most powerful features of EasyScript is the ability of the application developer to inject .NET objects into the script runtime, including all their properties and methods.  You can even expose entire object models into the script runtime, and these objects can later be referenced in the scripts at runtime and manipulated just as if they were declared in the script itself, e.g. myObj.DoSomething().  This allows amazing features for many applications. The client could literally program against an API exposed by the application runtime, an API that could be just as powerful as the application that was hosting it, but with the benefit of the simplicity of S#.  This is how you write scriptable programs, so your users can script your application.

Using EasyScript

Adding EasyScript to your application is one of the easiest things you will ever do.  Here are the steps:

1. Copy the EasyScript.NET DLLs to your application folder and add a reference to EasyScript.dll.
2. Declare and create a Scripter variable.
3. Create a Parameter List with any .NET objects you want to have available in the script code.
4. Call Scripter.RunScript or RunScriptFile to run an existing script.

Example:  Run the Script Editor to create a new script with the application Form available as a scripting object.

EasyScript.Scripter scripter = new EasyScript.Scripter(); var parameters = new List<Parameter>(); parameters.Add( new Parameter( "Form", this ) ); ScriptEditor editor = new ScriptEditor( scripter, null, null, parameters ); editor.ShowDialog( this );

Notice we use a List of Parameter objects.   Parameter is an EasyScript class which you use to pass parameters to your scripts.  This code will cause the Script Editor to open, ready to start typing script code.   Here is a screenshot:

You use the Script Editor to create, edit and test your scripts (or users of your program use it for their scripts).  The great thing is that you can test your script as you write it without exiting the Script Editor.  Additionally, you can pass the same parameters to the RunScriptEditor method as you would do to the RunScript method.  Thus you can write and test your scripts with the same parameters and conditions under which it will run normally in your program.  Here is an example how you might do it:

int nCustId = GetCustomerId(); // a parameter for illustration var parameters = new List<Parameter>(); parameters.Add( new Parameter( "CustId", nCustId ) ); if( editing ) {   ScriptEditor editor = new ScriptEditor( scripter, "Script1.script", parameters );   editor.ShowDialog( this ); } else {   scripter.RunScriptFile( "Script1.script", parameters ); }

With this code, nCustId will be passed to the Script Editor and then passed to the script engine each time the "Run Script" button is clicked.  When not in "editing" mode, the script will be run without the Script Editor.  This is an excellent solution for creating, editing and running scripts.  It makes life easy for you, allowing you to integrate scripting into your application.

In summary, the Script Editor is to be used by you or your application users to create and test scripts which can be saved and run whenever.

Text Generation with EasyScript.NET

Your scripts can generate text output in one of two ways.  The first way is with Host.Write or Host.WriteLn, like this:

Host.WriteLn( "Hello World" )

Notice we made use of the Host object.  This is the only "intrinsic" object available to your script at runtime.

The second way is with "inline text".  This is a very powerful feature we have implemented.  Its the same principle as Classic ASP and PHP webserver languages.  For those unfamiliar with how Classic ASP works, we will explain it here.  The idea is that you can output any amount of text (several lines of XML for example) by delimiting it with special characters.  To enter an inline text sequence, use %> and to end a sequence use <%.  Here is an example that uses both methods to list all input parameter values and their names.  To demonstrate, add create and add two parameters in your .NET code:

var parameters = new List<Parameter>(); parameters.Add( new Parameter( "param1", "a string" ) ); parameters.Add( new Parameter( "param2", 123 ) ); scripter.RunScriptFile( "InParams.script", parameters );

Then in your script file, you could output the entire contents of the input parameters collection, like this:

<% Host.WriteLn( string.Format( "param1: {0}", param1.ToString() ) ); Host.WriteLn( string.Format( "param2: {0}", param2.ToString() ) ); %>

Or you can use inline code in a more natural way.  The <% characters effectively switches off text mode and begins an inline code sequence.  The %> characters switch back to text mode.  We can use a shorthand method of writing inline code by using the = character if is only a single expression which is the middle of an inline text sequence, like this:

param1: <%=param1.ToString() %>
param2: <%=param2.ToString() %>

Or, if you don't know the names of the input parameters you could output the entire contents of the input parameters collection, like this:

<% foreach( param in Host.Parameters ) {   Host.WriteLn( string.Format( "{0}: {1}", param.Name, param.Value.ToString() ) ); } %>

As you can see, this is a powerful feature indeed.  The example above shows how to generate an XML document in a very visual way, with much of the document actually in the script in the way it will appear when generated.  This is exactly how PHP and classic ASP works.  In fact, the Microsoft FrontPage editor recognizes the text delimiter tags and renders the page correctly in design mode.  Notice the while loop in the code.  It loops until the last row of the Dataset is reached.  The whole section is repeated until dsOrderItems.eof is true.  Now you can see why ASP and PHP are so popular, and you can use the same code in your scripts today to generate XML/HTML as you may need.

Using the #include Directive to include other script files

Script writers often create libraries of functions that can be used in other scripts.  We have designed EasyScript.NET to be able to include other scripts with the #include directive.  Its very simple to use.

#include mylib1.script

You can form 3 types of include paths:  Relative, Based or Absolute.  Please see the BasePath property of the Scripter object for complete details.

The ability to include other scripts in a script is a powerful feature, allowing you to build up script libraries and easily use them when needed.

Controlling Script Loading and Saving

There are two schemes for loading and saving scripts.  EasyScript.NET will quite happily use file-based scripts, with no intervention needed by your application.  RunScriptFile and RunScriptFileEditor are all you need to use to have an instant, up-and-running scripting solution for your application.  But you may need to have more control over scripts.  For example, for security reasons you may want to limit access to certain scripts by user.  You may even want to encrypt scripts, and store them in a database on another machine, or even across the world via the Internet.  You can control how scripts are loaded and saved by EasyScript.NET by connecting to certain events.  These are the Save and Open events on the Scripter class.   When you have connected to these events, whenever the script parser encounters a #include statement, the Open event is fired, and likewise when the Script Editor Save and Open buttons are clicked.  This gives your application the chance to provide the script text for the given named script.  You are passed the name of the script with which you can retrieve the script from wherever your application has it stored.  The sample program in this download demonstrates how to do this.  Its very easy to do.  Here are the steps.

1.  Connect the event to your event handlers for both Save and Open.

scripter.SaveScript += new EasyScript.Scripter.SaveEventHandler( OnSaveScript ); scripter.OpenScript += new EasyScript.Scripter.OpenEventHandler( OnOpenScript );

2.  In your OnSave event handler, save the script text to your storage medium.

private void OnSaveScript( ref string scriptName, string scriptText ) {   // save the script text with the script name here   // if scriptName is null or empty, ask the user for a name }

3.  In your OnOpen event handler, retrieve the script text from your storage medium.

private void OnOpenScript( ref string scriptName, string scriptText ) {     // retrieve the script text with the script name here     // if scriptName is null or empty, provide a UI for the user to     // select a script from a list }

In this way, you have complete control over saving and loading of scripts.  If you never connect to the events, EasyScript.NET will provide the Windows FileOpen and FileSave dialogs.

Licensing

The EasyScript.NET DLL uses the .NET Component Licensing system.  It will display a License (nag) window until you purchase a development license.  A license allows you to distribute your application with no restrictions.

File Redistribution

The following two DLLs must be distributed with your application which uses EasyScript.NET:

EasyScript.dll	Main EasyScript.NET assembly
Scripting.SSharp.dll	S# Script Engine assembly

If your application will use the EasyScript ScriptEditor you must also include these two DLLs:

EasyScript.Editor.dll	Script Editor assembly
Puzzle.SyntaxBox.NET4.dll	This DLL is the editor component of the Script Editor.

Sample Applications

There is a C# sample project included in the download which demonstrates everything in this overview.