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

Product Overview

EasyScript.NET enables Software Developers to integrate scripting capabilities directly into their .NET applications.  EasyScript.NET is a .NET Assembly wrapper for Script.NET (aka S#) 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 even easier.  You have access to the entire .NET Framework from your scripts - very powerful indeed.  The download includes some S# examples which demonstrate its features.

Dynamic User Interfaces in WPF

We are very excited about our newly discovered use for EasyScript - dynamic WPF user interface code generation.  But to understand how this works, you must first read this page to see how EasyScript works.

EasyScript works 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.  However, you're script code can be as complex as you need.

Generate XML Documents

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 or XAML documents as we will demonstrate below.

Another important feature is a built-in Script Editor for creating and testing scripts.

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.NET 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.NET 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.NET 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. myVar.ToString().  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#.

Using EasyScript.NET

Adding EasyScript.NET 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.NET.dll.
2. Declare and create a Scripter variable.  This is the EasyScript.NET object you use for all operations.
3. Create a Parameter List with any .NET objects you want to have available in the script code.
4. Call Scripter.RunScript to run an existing script or call Scripter.RunScriptEditor to create a new script (or RunScriptFile / RunScriptFileEditor).

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 ) );
scripter.RunScriptEditor( this, null, null, parameters );

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.  Since the Form object has been added to the script environment, you can call any method or set any property on the form.  Let's change the Title of the Form and run the Script.  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 parameter 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 )
{
    scripter.RunScriptFileEditor( this, "Script1.script", parameters );
}
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() ) );
}

Consider this entire script function that creates a complete XML document using the tools described above:

<%
dsInvoices = db.Exec( "SELECT o.OrderID, c.CustomerID, c.CompanyName FROM Orders o " +
"JOIN Customers c ON o.CustomerID=c.CustomerID JOIN Shippers s on o.ShipVia=s.ShipperID LIMIT 10",
null, null, null );

while( !dsInvoices.eof )
{
    sOrderId = dsInvoices.Columns.GetColumn_("OrderId").Value;

    dsProducts = db.Execute( "SELECT p.ProductName, d.* FROM Products p JOIN OrderDetails d ON p.ProductID = d.ProductID WHERE     OrderID=" + sOrderId, null, null, null );

    GenXmlDoc( dsInvoices, dsProducts );
    Form.OnXmlDoc( sOrderId );
    dsInvoices.MoveNext();
}

function GenXmlDoc( dsOrders, dsOrderItems )
{
    cols = dsOrders.Columns;
    orderId = cols.GetColumn_("OrderID").Value;
    custId = cols.GetColumn_("CustomerID").Value;
    custName = cols.GetColumn_("CompanyName").Value;
    total = 0;
%>
<?xml version="1.0" encoding="utf-8"?>
<ORDER>
<ORDER_ID><%=orderId%></ORDER_ID>
<CUST_ID><%=custId%></CUST_ID>
<CUST_NAME><%=custName%></CUST_NAME>
<ORDER_ITEMS>
<% while( !dsOrderItems.eof )
{
    cols = dsOrderItems.Columns;
    price = cols.GetColumn_("UnitPrice").Value;
    qty = cols.GetColumn_("Quantity").Value;
    amt = price * qty;
    total+= amt;
    %>
    <ORDER_ITEM>
    <PROD_ID><%=cols.GetColumn_("ProductID").Value%></PROD_ID>
    <PROD_NAME><%=cols.GetColumn_("ProductName").Value%></PROD_NAME>
    <PRICE><%=price%></PRICE>
    <QUANTITY><%=qty%></QUANTITY>
    <AMOUNT><%=amt%></AMOUNT>
    </ORDER_ITEM>
<% dsOrderItems.MoveNext(); } %>
</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", _dbConn );
string sXmlDoc = scripter.Output;

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.Save += new EasyScript.Scripter.SaveEventHandler( OnSave );
scripter.Open += new EasyScript.Scripter.OpenEventHandler( OnOpen );

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

private void OnSave( ref string sScriptName, string sScriptText )
{
    // save the script text with the script name here
    // if sScriptName 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 OnOpen( ref string sScriptName, string sScriptText )
{
    // retrieve the script text with the script name here
    // if sScriptName 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 files must be distributed with your application which uses EasyScript.NET:

EasyScript.dll	Main EasyScript.NET assembly
ScriptDotNet.dll	Script Engine assembly
*Puzzle.SyntaxBox.NET3.5.dll	Script editor component DLL.  You only need to ship this DLL if you will need to show the Script Editor window when running your application (RunScriptEditor).  Otherwise its not needed.

Sample Applications

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

There is also a sample project demonstrating how to use EasyScript for dynamic XAML generation.

Please click here to read about WPF dynamic user interface generation.