Monthly Archives: September 2014

Calculated properties

Calculated properties are readonly order properties that are evaluated using an Expression.

A calculated field includes a calculate button to process the expression. When clicked the expression evaluation routing is triggered. All form values are injected into the expression as a dictionary. The dictionary is the root object and can be accessed using the #root keyword.

Example expression that adds the Number to the Date


Calculated property expressions can be tested as a part of building up your order schema. Once a calculate property is selected you can enter your expression and use the test inputs to test and build your expression.

For further details on the syntax used in expressions please read Expression Evaluation.

Expression Evaluation

There are a number of extension points within labPortal that use configurable expressions to evaluate a condition. These expressions enable the  a single instance of labPortal to be configured for a customers particular needs and business rules without having to develop custom code. The expressions can be considered similar a similie to the inline expression used in Excel. Expressions are used when some data needs to be processed, mapped or a business rule needs to be evaluated.

All expressions are executed within a similar pattern:

  1. A context is created
  2. The expression is compiled and loaded into the context
  3. Input values are passed into the expression
  4. The expression is evaluated
  5. The output is loaded into the result

Each scenario where an expression is used can be different, however the general guidance below details all the information required for writing and understanding how the labPortal expression engine works.

Evaluating Expressions

The simplest, but not the most efficient way to perform expression evaluation is by using one of the static convenience methods of the ExpressionEvaluator class:

public static object GetValue(object root, string expression);

public static object GetValue(object root, string expression, IDictionary variables)

public static void SetValue(object root, string expression, object newValue)

public static void SetValue(object root, string expression, IDictionary variables, object newValue)

The first argument is the ‘root’ object that the expression string (2nd argument) will be evaluated against. The third argument is used to support variables in the expression and will be discussed later. Simple usage to get the value of an object property is shown below using the Inventor class. You can find the class listing in section Section 11.4, “Classes used in the examples”.

Inventor tesla = new Inventor("Nikola Tesla", new DateTime(1856, 7, 9), "Serbian");

tesla.PlaceOfBirth.City = "Smiljan";

string evaluatedName = (string) ExpressionEvaluator.GetValue(tesla, "Name");

string evaluatedCity = (string) ExpressionEvaluator.GetValue(tesla, "PlaceOfBirth.City"));

The value of ‘evaluatedName’ is ‘Nikola Tesla’ and that of ‘evaluatedCity’ is ‘Smiljan’. A period is used to navigate the nested properties of the object. Similarly to set the property of an object, say we want to rewrite history and change Tesla’s city of birth, we would simply add the following line

ExpressionEvaluator.SetValue(tesla, "PlaceOfBirth.City", "Novi Sad");

A much better way to evaluate expressions is to parse them once and then evaluate as many times as you want usingExpressionclass. Unlike ExpressionEvaluator, which parses expression every time you invoke one of its methods, Expression class will cache the parsed expression for increased performance. The methods of this class are listed below:

public static IExpression Parse(string expression)

public override object Get(object context, IDictionary variables)

public override void Set(object context, IDictionary variables, object newValue)

The retrieval of the Name property in the previous example using the Expression class is shown below

IExpression exp = Expression.Parse("Name");

string evaluatedName = (string) exp.GetValue(tesla, null);

The difference in performance between the two approaches, when evaluating the same expression many times, is several orders of magnitude, so you should only use convenience methods of the ExpressionEvaluator class when you are doing one-off expression evaluations. In all other cases you should parse the expression first and then evaluate it as many times as you need.

There are a few exception classes to be aware of when using the ExpressionEvaluator. These are InvalidPropertyException, when you refer to a property that doesn’t exist,NullValueInNestedPathException, when a null value is encountered when traversing through the nested property list, and ArgumentException and NotSupportedExceptionwhen you pass in values that are in error in some other manner.

The expression language is based on a grammar and uses ANTLR to construct the lexer and parser. Errors relating to bad syntax of the language will be caught at this level of the language implementation. For those interested in the digging deeper into the implementation, the grammar file is named Expression.g and is located in the src directory of the namespace. As a side note, the release version of the ANTLR DLL included with Spring.NET was signed with the Spring.NET key, which means that you should always use the included version of antlr.runtime.dll within your application. Upcoming releases of ANTLR will provide strongly signed assemblies, which will remove this requirement.

Language Reference

Literal expressions

The types of literal expressions supported are strings, dates, numeric values (int, real, and hex), boolean and null. String are delimited by single quotes. To put a single quote itself in a string use the backslash character. The following listing shows simple usage of literals. Typically they would not be used in isolation like this, but as part of a more complex expression, for example using a literal on one side of a logical comparison operator.

string helloWorld = (string) ExpressionEvaluator.GetValue(null, "'Hello World'"); // evals to "Hello World"

string tonyPizza  = (string) ExpressionEvaluator.GetValue(null, "'Tony\\'s Pizza'"); // evals to "Tony's Pizza"

double avogadrosNumber = (double) ExpressionEvaluator.GetValue(null, "6.0221415E+23");

int maxValue = (int)  ExpressionEvaluator.GetValue(null, "0x7FFFFFFF");  // evals to 2147483647

DateTime birthday = (DateTime) ExpressionEvaluator.GetValue(null, "date('1974/08/24')");

DateTime exactBirthday =
  (DateTime) ExpressionEvaluator.GetValue(null, " date('19740824T131030', 'yyyyMMddTHHmmss')");

bool trueValue = (bool) ExpressionEvaluator.GetValue(null, "true");

object nullValue = ExpressionEvaluator.GetValue(null, "null");

Note that the extra backslash character in Tony’s Pizza is to satisfy C# escape syntax. Numbers support the use of the negative sign, exponential notation, and decimal points. By default real numbers are parsed using Double.Parse unless the format character “M” or “F” is supplied, in which case Decimal.Parse and Single.Parse would be used respectfully. As shown above, if two arguments are given to the date literal then DateTime.ParseExact will be used. Note that all parse methods of classes that are used internally reference theCultureInfo.InvariantCulture.

Properties, Arrays, Lists, Dictionaries, Indexers

As shown in the previous example in Section 11.2, “Evaluating Expressions”, navigating through properties is easy, just use a period to indicate a nested property value. The instances ofInventor class, pupin and tesla, were populated with data listed in section Section 11.4, “Classes used in the examples”. To navigate “down” and get Tesla’s year of birth and Pupin’s city of birth the following expressions are used

int year = (int) ExpressionEvaluator.GetValue(tesla, "DOB.Year"));  // 1856

string city = (string) ExpressionEvaluator.GetValue(pupin, "PlaCeOfBirTh.CiTy");  // "Idvor"

For the sharp-eyed, that isn’t a typo in the property name for place of birth. The expression uses mixed cases to demonstrate that the evaluation is case insensitive.

The contents of arrays and lists are obtained using square bracket notation.

// Inventions Array
string invention = (string) ExpressionEvaluator.GetValue(tesla, "Inventions[3]"); // "Induction motor"

// Members List
string name = (string) ExpressionEvaluator.GetValue(ieee, "Members[0].Name"); // "Nikola Tesla"

// List and Array navigation
string invention = (string) ExpressionEvaluator.GetValue(ieee, "Members[0].Inventions[6]") // "Wireless communication"

The contents of dictionaries are obtained by specifying the literal key value within the brackets. In this case, because keys for the Officers dictionary are strings, we can specify string literal.

// Officer's Dictionary
Inventor pupin = (Inventor) ExpressionEvaluator.GetValue(ieee, "Officers['president']";

string city = (string) ExpressionEvaluator.GetValue(ieee, "Officers['president'].PlaceOfBirth.City"); // "Idvor"

ExpressionEvaluator.SetValue(ieee, "Officers['advisors'][0].PlaceOfBirth.Country", "Croatia");

You may also specify non literal values in place of the quoted literal values by using another expression inside the square brackets such as variable names or static properties/methods on other types. These features are discussed in other sections.

Indexers are similarly referenced using square brackets. The following is a small example that shows the use of indexers. Multidimensional indexers are also supported.

public class Bar
    private int[] numbers = new int[] {1, 2, 3};

    public int this[int index]
        get { return numbers[index];}
        set { numbers[index] = value; }

Bar b = new Bar();

int val = (int) ExpressionEvaluator.GetValue(bar, "[1]") // evaluated to 2

ExpressionEvaluator.SetValue(bar, "[1]", 3);  // set value to 3 Defining Arrays, Lists and Dictionaries Inline

In addition to accessing arrays, lists and dictionaries by navigating the graph for the context object, Spring.NET Expression Language allows you to define them inline, within the expression. Inline lists are defined by simply enclosing a comma separated list of items with curly brackets:

{1, 2, 3, 4, 5}
{'abc', 'xyz'}

If you want to ensure that a strongly typed array is initialized instead of a weakly typed list, you can use array initializer instead:

new int[] {1, 2, 3, 4, 5}
new string[] {'abc', 'xyz'}

Dictionary definition syntax is a bit different: you need to use a # prefix to tell expression parser to expect key/value pairs within the brackets and to specify a comma separated list of key/value pairs within the brackets:

#{'key1' : 'Value 1', 'today' : DateTime.Today}
#{1 : 'January', 2 : 'February', 3 : 'March', ...}

Arrays, lists and dictionaries created this way can be used anywhere where arrays, lists and dictionaries obtained from the object graph can be used, which we will see later in the examples.

Keep in mind that even though examples above use literals as array/list elements and dictionary keys and values, that’s only to simplify the examples — you can use any valid expression wherever literals are used.

11.3.3. Methods

Methods are invoked using typical C# programming syntax. You may also invoke methods on literals.

//string literal
char[] chars = (char[]) ExpressionEvaluator.GetValue(null, "'test'.ToCharArray(1, 2)"))  // 't','e'

//date literal
int year = (int) ExpressionEvaluator.GetValue(null, "date('1974/08/24').AddYears(31).Year") // 2005

// object usage, calculate age of tesla navigating from the IEEE society.

ExpressionEvaluator.GetValue(ieee, "Members[0].GetAge(date('2005-01-01')") // 149 (eww..a big anniversary is coming up ;)
Relational operators

The relational operators; equal, not equal, less than, less than or equal, greater than, and greater than or equal are supported using standard operator notation. These operators take into account if the object implements the IComparable interface. Enumerations are also supported but you will need to register the enumeration type, as described in SectionSection 11.3.8, “Type Registration”, in order to use an enumeration value in an expression if it is not contained in the mscorlib.

ExpressionEvaluator.GetValue(null, "2 == 2")  // true

ExpressionEvaluator.GetValue(null, "date('1974-08-24') != DateTime.Today")  // true

ExpressionEvaluator.GetValue(null, "2 < -5.0") // false

ExpressionEvaluator.GetValue(null, "DateTime.Today <= date('1974-08-24')") // false

ExpressionEvaluator.GetValue(null, "'Test' >= 'test'") // true

Enumerations can be evaluated as shown below

FooColor fColor = new FooColor();

ExpressionEvaluator.SetValue(fColor, "Color", KnownColor.Blue);

bool trueValue = (bool) ExpressionEvaluator.GetValue(fColor, "Color == KnownColor.Blue"); //true

Where FooColor is the following class.

public class FooColor
    private KnownColor knownColor;

    public KnownColor Color
        get { return knownColor;}
        set { knownColor = value; }

In addition to standard relational operators, Spring.NET Expression Language supports some additional, very useful operators that were “borrowed” from SQL, such as in, like andbetween, as well as is and matches operators, which allow you to test if object is of a specific type or if the value matches a regular expression.

ExpressionEvaluator.GetValue(null, "3 in {1, 2, 3, 4, 5}")  // true

ExpressionEvaluator.GetValue(null, "'Abc' like '[A-Z]b*'")  // true

ExpressionEvaluator.GetValue(null, "'Abc' like '?'")  // false

ExpressionEvaluator.GetValue(null, "1 between {1, 5}")  // true

ExpressionEvaluator.GetValue(null, "'efg' between {'abc', 'xyz'}")  // true

ExpressionEvaluator.GetValue(null, "'xyz' is int")  // false

ExpressionEvaluator.GetValue(null, "{1, 2, 3, 4, 5} is IList")  // true

ExpressionEvaluator.GetValue(null, "'5.0067' matches '^-?\\d+(\\.\\d{2})?$'"))  // false

ExpressionEvaluator.GetValue(null, @"'5.00' matches '^-?\d+(\.\d{2})?$'")  // true

Note that the Visual Basic and not SQL syntax is used for the like operator pattern string. Logical operators

The logical operators that are supported are and, or, and not. Their use is demonstrated below

// AND
bool falseValue = (bool) ExpressionEvaluator.GetValue(null, "true and false"); //false

string expression = @"IsMember('Nikola Tesla') and IsMember('Mihajlo Pupin')";
bool trueValue = (bool) ExpressionEvaluator.GetValue(ieee, expression);  //true

// OR
bool trueValue = (bool) ExpressionEvaluator.GetValue(null, "true or false");  //true

string expression = @"IsMember('Nikola Tesla') or IsMember('Albert Einstien')";
bool trueValue = (bool) ExpressionEvaluator.GetValue(ieee, expression); // true

// NOT
bool falseValue = (bool) ExpressionEvaluator.GetValue(null, "!true");

// AND and NOT
string expression = @"IsMember('Nikola Tesla') and !IsMember('Mihajlo Pupin')";
bool falseValue = (bool) ExpressionEvaluator.GetValue(ieee, expression);
Bitwise operators

The bitwise operators that are supported are and, or, xor and not. Their use is demonstrated below. Note, that the logical and bitwise operators are the same and their interpretation depends if you pass in integral values or boolean values.

// AND
int result = (int) ExpressionEvaluator.GetValue(null, "1 and 3"); // 1 & 3

// OR
int result = (int) ExpressionEvaluator.GetValue(null, "1 or 3");  // 1 | 3

// XOR
int result = (int) ExpressionEvaluator.GetValue(null, "1 xor 3");  // 1 ^ 3

// NOT
int result = (int) ExpressionEvaluator.GetValue(null, "!1"); // ~1
Mathematical operators

The addition operator can be used on numbers, strings and dates. Subtraction can be used on numbers and dates. Multiplication and division can be used only on numbers. Other mathematical operators supported are modulus (%) and exponential power (^). Standard operator precedence is enforced. These operators are demonstrated below

// Addition
int two = (int)ExpressionEvaluator.GetValue(null, "1 + 1"); // 2

String testString = (String)ExpressionEvaluator.GetValue(null, "'test' + ' ' + 'string'"); //'test string'

DateTime dt = (DateTime)ExpressionEvaluator.GetValue(null, "date('1974-08-24') + 5"); // 8/29/1974

// Subtraction

int four = (int) ExpressionEvaluator.GetValue(null, "1 - -3"); //4

Decimal dec = (Decimal) ExpressionEvaluator.GetValue(null, "1000.00m - 1e4"); // 9000.00

TimeSpan ts = (TimeSpan) ExpressionEvaluator.GetValue(null, "date('2004-08-14') - date('1974-08-24')"); //10948.00:00:00

// Multiplication

int six = (int) ExpressionEvaluator.GetValue(null, "-2 * -3"); // 6

int twentyFour = (int) ExpressionEvaluator.GetValue(null, "2.0 * 3e0 * 4"); // 24

// Division

int minusTwo = (int) ExpressionEvaluator.GetValue(null, "6 / -3"); // -2

int one = (int) ExpressionEvaluator.GetValue(null, "8.0 / 4e0 / 2"); // 1

// Modulus

int three = (int) ExpressionEvaluator.GetValue(null, "7 % 4"); // 3

int one = (int) ExpressionEvaluator.GetValue(null, "8.0 % 5e0 % 2"); // 1

// Exponent

int sixteen = (int) ExpressionEvaluator.GetValue(null, "-2 ^ 4"); // 16

// Operator precedence

int minusFortyFive = (int) ExpressionEvaluator.GetValue(null, "1+2-3*8^2/2/2"); // -45

Setting of a property is done by using the assignment operator. This would typically be done within a call to GetValue since in the simple case SetValue offers the same functionality. Assignment in this manner is useful when combining multiple operators in an expression list, discussed in the next section. Some examples of assignment are shown below

Inventor inventor = new Inventor();
String aleks = (String) ExpressionEvaluator.GetValue(inventor, "Name = 'Aleksandar Seovic'");
DateTime dt = (DateTime) ExpressionEvaluator.GetValue(inventor, "DOB = date('1974-08-24')");

//Set the vice president of the society
Inventor tesla = (Inventor) ExpressionEvaluator.GetValue(ieee, "Officers['vp'] = Members[0]");
Expression lists

Multiple expressions can be evaluated against the same context object by separating them with a semicolon and enclosing the entire expression within parentheses. The value returned is the value of the last expression in the list. Examples of this are shown below

//Perform property assignments and then return Name property.

String pupin = (String) ExpressionEvaluator.GetValue(ieee.Members,
  "( [1].PlaceOfBirth.City = 'Beograd'; [1].PlaceOfBirth.Country = 'Serbia'; [1].Name )"));

// pupin = "Mihajlo Pupin"

In many cases, you can reference types by simply specifying type name:

ExpressionEvaluator.GetValue(null, "1 is int")

ExpressionEvaluator.GetValue(null, "DateTime.Today")

ExpressionEvaluator.GetValue(null, "new string[] {'abc', 'efg'}")

This is possible for all standard types from mscorlib, as well as for any other type that is registered with the TypeRegistry as described in the next section.

For all other types, you need to use special T(typeName) expression:

Type dateType = (Type) ExpressionEvaluator.GetValue(null, "T(System.DateTime)")

Type evalType = (Type) ExpressionEvaluator.GetValue(null, "T(Spring.Expressions.ExpressionEvaluator, Spring.Core)")

bool trueValue = (bool) ExpressionEvaluator.GetValue(tesla, "T(System.DateTime) == DOB.GetType()")

The implementation delegates to Spring’s ObjectUtils.ResolveType method for the actual type resolution, which means that the types used within expressions are resolved in the exactly the same way as the types specified in Spring configuration files.

Type Registration

To refer to a type within an expression that is not in the mscorlib you need to register it with the TypeRegistry. This will allow you to refer to a shorthand name of the type within your expressions. This is commonly used in expression that use the new operator or refer to a static properties of an object. Example usage is shown below.

TypeRegistry.RegisterType("Society", typeof(Society));

Inventor pupin = (Inventor) ExpressionEvaluator.GetValue(ieee, "Officers[Society.President]");

Alternatively, you can register types using typeAliases configuration section.


Constructors can be invoked using the new operator. For classes outside mscorlib you will need to register your types so they can be resolved. Examples of using constructors are shown below:

// simple ctor
DateTime dt = (DateTime) ExpressionEvaluator.GetValue(null, "new DateTime(1974, 8, 24)");

// Register Inventor type then create new inventor instance within Add method inside an expression list.
// Then return the new count of the Members collection.

int three = (int) ExpressionEvaluator.GetValue(ieee.Members, "{ Add(new Inventor('Aleksandar Seovic', date('1974-08-24'), 'Serbian')); Count}"));

As a convenience, Spring.NET also allows you to define named constructor arguments, which are used to set object’s properties after instantiation, similar to the way standard .NET attributes work. For example, you could create an instance of the Inventor class and set its Inventions property in a single statement:

Inventor aleks = (Inventor) ExpressionEvaluator.GetValue(null, "new Inventor('Aleksandar Seovic', date('1974-08-24'), 'Serbian', Inventions = {'SPELL'})");

The only rule you have to follow is that named arguments should be specified after standard constructor arguments, just like in the .NET attributes.

While we are on the subject, Spring.NET Expression Language also provides a convenient syntax for .NET attribute instance creation. Instead of using standard constructor syntax, you can use a somewhat shorter and more familiar syntax to create an instance of a .NET attribute class:

WebMethodAttribute webMethod = (WebMethodAttribute) ExpressionEvaluator.GetValue(null, "@[WebMethod(true, CacheDuration = 60, Description = 'My Web Method')]");

As you can see, with the exception of the @ prefix, syntax is exactly the same as in C#.

Slightly different syntax is not the only thing that differentiates an attribute expression from a standard constructor invocation expression. In addition to that, attribute expression uses slightly different type resolution mechanism and will attempt to load both the specified type name and the specified type name with an Attribute suffix, just like the C# compiler.


Variables can referenced in the expression using the syntax #variableName. The variables are passed in and out of the expression using the dictionary parameter inExpressionEvaluator‘s GetValue or SetValue methods.

public static object GetValue(object root, string expression, IDictionary variables)

public static void SetValue(object root, string expression, IDictionary variables, object newValue)

The variable name is the key value of the dictionary. Example usage is shown below;

IDictionary vars = new Hashtable();
vars["newName"] = "Mike Tesla";
ExpressionEvaluator.GetValue(tesla, "Name = #newName", vars));

You can also use the dictionary as a place to store values of the object as they are evaluated inside the expression. For example to change Tesla’s first name back again and keep the old value;

ExpressionEvaluator.GetValue(tesla, "{ #oldName = Name; Name = 'Nikola Tesla' }", vars);
String oldName = (String)vars["oldName"]; // Mike Tesla

Variable names can also be used inside indexers or maps instead of literal values. For example;

vars["prez"] = "president";
Inventor pupin = (Inventor) ExpressionEvaluator.GetValue(ieee, "Officers[#prez]", vars);
The ‘#this’ and ‘#root’ variables

There are two special variables that are always defined and can be references within the expression: #this and #root.

The #this variable can be used to explicitly refer to the context for the node that is currently being evaluated:

// sets the name of the president and returns its instance
ExpressionEvaluator.GetValue(ieee, "Officers['president'].( #this.Name = 'Nikola Tesla'; #this )")

Similarly, the #root variable allows you to refer to the root context for the expression:

// removes president from the Officers dictionary and returns removed instance
ExpressionEvaluator.GetValue(ieee, "Officers['president'].( #root.Officers.Remove('president'); #this )")
Ternary Operator (If-Then-Else)

You can use the ternary operator for performing if-then-else conditional logic inside the expression. A minimal example is;

String aTrueString  = (String) ExpressionEvaluator.GetValue(null, "false ? 'trueExp' : 'falseExp'") // trueExp

In this case, the boolean false results in returning the string value ‘trueExp’. A less artificial example is shown below

ExpressionEvaluator.SetValue(ieee, "Name", "IEEE");
IDictionary vars = new Hashtable();
vars["queryName"] = "Nikola Tesla";

string expression = @"IsMember(#queryName)
                      ? #queryName + ' is a member of the ' + Name + ' Society'
                      : #queryName + ' is not a member of the ' + Name + ' Society'";

String queryResultString = (String) ExpressionEvaluator.GetValue(ieee, expression, vars));

// queryResultString = "Nikola Tesla is a member of the IEEE Society"
List Projection and Selection

List projection and selection are very powerful expression language features that allow you to transform the source list into another list by either projecting across its “columns”, orselecting from its “rows”. In other words, projection can be thought of as a column selector in a SQL SELECT statement, while selection would be comparable to the WHERE clause.

For example, let’s say that we need a list of the cities where our inventors were born. This could be easily obtained by projecting on the PlaceOfBirth.City property:

IList placesOfBirth = (IList) ExpressionEvaluator.GetValue(ieee, "Members.!{PlaceOfBirth.City}")  // { 'Smiljan', 'Idvor' }

Or we can get the list of officers’ names:

IList officersNames = (IList) ExpressionEvaluator.GetValue(ieee, "Officers.Values.!{Name}")  // { 'Nikola Tesla', 'Mihajlo Pupin' }

As you can see from the examples, projection uses !{projectionExpression} syntax and will return a new list of the same length as the original list but typically with the elements of a different type.

On the other hand, selection, which uses ?{projectionExpression} syntax, will filter the list and return a new list containing a subset of the original element list. For example, selection would allow us to easily get a list of Serbian inventors:

IList serbianInventors = (IList) ExpressionEvaluator.GetValue(ieee, "Members.?{Nationality == 'Serbian'}")  // { tesla, pupin }

Or to get a list of inventors that invented sonar:

IList sonarInventors = (IList) ExpressionEvaluator.GetValue(ieee, "Members.?{'Sonar' in Inventions}")  // { pupin }

Or we can combine selection and projection to get a list of sonar inventors’ names:

IList sonarInventorsNames = (IList) ExpressionEvaluator.GetValue(ieee, "Members.?{'Sonar' in Inventions}.!{Name}")  // { 'Mihajlo Pupin' }

As a convenience, Spring.NET Expression Language also supports a special syntax for selecting the first or last match. Unlike regular selection, which will return an empty list if no matches are found, first or last match selection expression will either return an instance of the matched element, or null if no matching elements were found. In order to return a first match you should prefix your selection expression with ^{ instead of ?{, and to return last match you should use ${ prefix:

ExpressionEvaluator.GetValue(ieee, "Members.^{Nationality == 'Serbian'}.Name")  // 'Nikola Tesla'
ExpressionEvaluator.GetValue(ieee, "Members.${Nationality == 'Serbian'}.Name")  // 'Mihajlo Pupin'

Notice that we access the Name property directly on the selection result, because an actual matched instance is returned by the first and last match expression instead of a filtered list.

Collection Processors and Aggregators

In addition to list projection and selection, Spring.NET Expression Language also supports several collection processors, such as distinct, nonNull and sort, as well as a number of commonly used aggregators, such as max, min, count, sum and average.

The difference between processors and aggregators is that processors return a new or transformed collection, while aggregators return a single value. Other than that, they are very similar — both processors and aggregators are invoked on a collection node using standard method invocation expression syntax, which makes them very simple to use and allows easy chaining of multiple processors.

Count Aggregator

The count aggregator is a safe way to obtain a number of items in a collection. It can be applied to a collection of any type, including arrays, which helps eliminate the decision on whether to use Count or Length property depending on the context. Unlike its standard .NET counterparts, count aggregator can also be invoked on the null context without throwing a NullReferenceException. It will simply return zero in this case, which makes it much safer than standard .NET properties within larger expression.

ExpressionEvaluator.GetValue(null, "{1, 5, -3}.count()")  // 3
ExpressionEvaluator.GetValue(null, "count()")  // 0
Sum Aggregator

The sum aggregator can be used to calculate a total for the list of numeric values. If numbers within the list are not of the same type or precision, it will automatically perform necessary conversion and the result will be the highest precision type. If any of the collection elements is not a number, this aggregator will throw an InvalidArgumentException.

ExpressionEvaluator.GetValue(null, "{1, 5, -3, 10}.sum()")  // 13 (int)
ExpressionEvaluator.GetValue(null, "{5, 5.8, 12.2, 1}.sum()")  // 24.0 (double)
Average Aggregator

The average aggregator will return the average for the collection of numbers. It will use the same type coercion rules, as the sum aggregator in order to be as precise as possible. Just like the sum aggregator, if any of the collection elements is not a number, it will throw an InvalidArgumentException.

ExpressionEvaluator.GetValue(null, "{1, 5, -4, 10}.average()")  // 3
ExpressionEvaluator.GetValue(null, "{1, 5, -2, 10}.average()")  // 3.5
Minimum Aggregator

The minimum aggregator will return the smallest item in the list. In order to determine what “the smallest” actually means, this aggregator relies on the assumption that the collection items are of the uniform type and that they implement the IComparable interface. If that is not the case, this aggregator will throw an InvalidArgumentException.

ExpressionEvaluator.GetValue(null, "{1, 5, -3, 10}.min()")  // -3
ExpressionEvaluator.GetValue(null, "{'abc', 'efg', 'xyz'}.min()")  // 'abc'
Maximum Aggregator

The maximum aggregator will return the largest item in the list. In order to determine what “the largest” actually means, this aggregator relies on the assumption that the collection items are of the uniform type and that they implement IComparable interface. If that is not the case, this aggregator will throw an InvalidArgumentException.

ExpressionEvaluator.GetValue(null, "{1, 5, -3, 10}.max()")  // 10
ExpressionEvaluator.GetValue(null, "{'abc', 'efg', 'xyz'}.max()")  // 'xyz'
Non-null Processor

A non-null processor is a very simple collection processor that eliminates all null values from the collection.

ExpressionEvaluator.GetValue(null, "{ 'abc', 'xyz', null, 'abc', 'def', null}.nonNull()")  // { 'abc', 'xyz', 'abc', 'def' }
ExpressionEvaluator.GetValue(null, "{ 'abc', 'xyz', null, 'abc', 'def', null}.nonNull().distinct().sort()")  // { 'abc', 'def', 'xyz' }
Distinct Processor

A distinct processor is very useful when you want to ensure that you don’t have duplicate items in the collection. It can also accept an optional Boolean argument that will determine whether null values should be included in the results. The default is false, which means that they will not be included.

ExpressionEvaluator.GetValue(null, "{ 'abc', 'xyz', 'abc', 'def', null, 'def' }.distinct(true).sort()")  // { null, 'abc', 'def', 'xyz' }
ExpressionEvaluator.GetValue(null, "{ 'abc', 'xyz', 'abc', 'def', null, 'def' }.distinct(false).sort()")  // { 'abc', 'def', 'xyz' }
Sort Processor

The sort processor can be used to sort uniform collections of elements that implement IComparable.

ExpressionEvaluator.GetValue(null, "{1.2, 5.5, -3.3}.sort()")  // { -3.3, 1.2, 5.5 }
ExpressionEvaluator.GetValue(null, "{ 'abc', 'xyz', 'abc', 'def', null, 'def' }.sort()")  // { null, 'abc', 'abc', 'def', 'def', 'xyz' }

The sort processor also accepts a boolean value as an argument to determine sort order, sort(false) will sort the collection in decending order.

Type Conversion Processor

The convert processor can be used to convert a collection of elements to a given Type.

object[] arr = new object[] { "0", 1, 1.1m, "1.1", 1.1f };
decimal[] result = (decimal[]) ExpressionEvaluator.GetValue(arr, "convert(decimal)");
Reverse Processor

The reverse processor returns the reverse order of elements in the list

object[] arr = new object[] { "0", 1, 2.1m, "3", 4.1f };
object[] result = new ArrayList( (ICollection) ExpressionEvaluator.GetValue(arr, "reverse()") ).ToArray(); // { 4.1f, "3", 2.1m, 1, "0" }            
OrderBy Processor

Collections can be ordered in three ways, an expression, a SpEL lamda expreression, or a delegate.

// orderBy expression
IExpression exp = Expression.Parse("orderBy('ToString()')");
object[] input = new object[] { 'b', 1, 2.0, "a" };
object[] ordered = exp.GetValue(input);  // { 1, 2.0, "a", 'b' }

// SpEL lambda expressions
IExpression exp = Expression.Parse("orderBy({|a,b| $a.ToString().CompareTo($b.ToString())})");
object[] input = new object[] { 'b', 1, 2.0, "a" };
object[] ordered = exp.GetValue(input);  // { 1, 2.0, "a", 'b' }

Hashtable vars = new Hashtable();
Expression.RegisterFunction( "compare", "{|a,b| $a.ToString().CompareTo($b.ToString())}", vars);
exp = Expression.Parse("orderBy(#compare)");
ordered = exp.GetValue(input, vars);  // { 1, 2.0, "a", 'b' }

// .NET delegate
private delegate int CompareCallback(object x, object y);
private int CompareObjects(object x, object y)
  if (x == y) return 0;
  return x.ToString().CompareTo(""+y);

Hashtable vars = new Hashtable();
vars["compare"] = new CompareCallback(CompareObjects);

IExpression exp = Expression.Parse("orderBy(#compare)");
object[] input = new object[] { 'b', 1, 2.0, "a" };
object[] ordered = exp.GetValue(input);  // { 1, 2.0, "a", 'b' }
User Defined Collection Processor

You can register your own collection processor for use in evaluation a collection. Here is an example of a ICollectionProcessor implementation that sums only the even numbers of an integer list

        public class IntEvenSumCollectionProcessor : ICollectionProcessor
            public object Process(ICollection source, object[] args)
                object total = 0d;
                foreach (object item in source)
                    if (item != null)
                        if (NumberUtils.IsInteger(item))
                            if ((int)item % 2 == 0)
                                total = NumberUtils.Add(total, item);
                            throw new ArgumentException("Sum can only be calculated for a collection of numeric values.");

                return total;

        public void DoWork()
            Hashtable vars = new Hashtable();
            vars["EvenSum"] = new IntEvenSumCollectionProcessor();
            int result = (int)ExpressionEvaluator.GetValue(null, "{1, 2, 3, 4}.EvenSum()", vars));  // 6
Spring Object References

Expressions can refer to objects that are declared in Spring’s application context using the syntax @(contextName:objectName). If no contextName is specified the default root context name (Spring.RootContext) is used. Using the application context defined in the MovieFinder example from Chapter 37, IoC Quickstarts, the following expression returns the number of movies directed by Roberto Benigni.

public static void Main()
  . . .

// Retrieve context defined in the spring/context section of
// the standard .NET configuration file.
IApplicationContext ctx = ContextRegistry.GetContext();

int numMovies = (int) ExpressionEvaluator.GetValue(null,
                      "@(MyMovieLister).MoviesDirectedBy('Roberto Benigni').Length");

  . . .

The variable numMovies is evaluated to 2 in this example.

Lambda Expressions

A somewhat advanced, but a very powerful feature of Spring.NET Expression Language are lambda expressions. Lambda expressions allow you to define inline functions, which can then be used within your expressions just like any other function or method. You may also use .NET delegates as described in the next section.

The syntax for defining lambda expressions is:

#functionName = {|argList| functionBody }

For example, you could define a max function and call it like this:

ExpressionEvaluator.GetValue(null, "(#max = {|x,y| $x > $y ? $x : $y }; #max(5,25))", new Hashtable())  // 25

As you can see, any arguments defined for the expression can be referenced within the function body using a local variable syntax, $varName. Invocation of the function defined using lambda expression is as simple as specifying the comma-separated list of function arguments in parentheses, after the function name.

Lambda expressions can be recursive, which means that you can invoke the function within its own body:

ExpressionEvaluator.GetValue(null, "(#fact = {|n| $n <= 1 ? 1 : $n * #fact($n-1) }; #fact(5))", new Hashtable())  // 120

Notice that in both examples above we had to specify a variables parameter for the GetValue method. This is because lambda expressions are actually nothing more than parameterized variables and we need variables dictionary in order to store them. If you don’t specify a valid IDictionary instance for the variables parameter, you will get a runtime exception.

Also, in both examples above we used an expression list in order to define and invoke a function in a single expression. However, more likely than not, you will want to define your functions once and then use them within as many expressions as you need. Spring.NET provides an easy way to pre-register your lambda expressions by exposing a staticExpression.RegisterFunction method, which takes function name, lambda expression and variables dictionary to register function in as parameters:

IDictionary vars = new Hashtable();
Expression.RegisterFunction("sqrt", "{|n| Math.Sqrt($n)}", vars);
Expression.RegisterFunction("fact", "{|n| $n <= 1 ? 1 : $n * #fact($n-1)}", vars);

Once the function registration is done, you can simply evaluate an expression that uses these functions, making sure that the vars dictionary is passed as a parameter to expression evaluation engine:

ExpressionEvaluator.GetValue(null, "#fact(5)", vars)  // 120
ExpressionEvaluator.GetValue(null, "#sqrt(9)", vars)  // 3

Finally, because lambda expressions are treated as variables, they can be assigned to other variables or passed as parameters to other lambda expressions. In the following example we are defining a delegate function that accepts function f as the first argument and parameter n that will be passed to function f as the second. Then we invoke the functions registered in the previous example, as well as the lambda expression defined inline, through our delegate:

Expression.RegisterFunction("delegate", "{|f, n| $f($n) }", vars);
ExpressionEvaluator.GetValue(null, "#delegate(#sqrt, 4)", vars)  // 2
ExpressionEvaluator.GetValue(null, "#delegate(#fact, 5)", vars)  // 120
ExpressionEvaluator.GetValue(null, "#delegate({|n| $n ^ 2 }, 5)", vars)  // 25

While this particular example is not particularly useful, it does demonstrate that lambda expressions are indeed treated as nothing more than parameterized variables, which is important to remember.

Delegate Expressions

Delegate expressions allow you to refer to .NET delegates which can then be used within your expressions just like any other function or method.

For example, you can define a max delegate and call it like this

private delegate double DoubleFunctionTwoArgs(double arg1, double arg2);

private double Max(double arg1, double arg2)
  return Math.Max(arg1, arg2);

public void DoWork()
  Hashtable vars = new Hashtable();
  vars["max"] = new DoubleFunctionTwoArgs(Max);
  double result = (double) ExpressionEvaluator.GetValue(null, "#max(5,25)", vars);  // 25
Null Context

If you do not specify a root object, i.e. pass in null, then the expressions evaluated either have to be literal values, i.e. ExpressionEvaluator.GetValue(null, “2 + 3.14”), refer to classes that have static methods or properties, i.e. ExpressionEvaluator.GetValue(null, “DateTime.Today”), create new instances of objects, i.e. ExpressionEvaluator.GetValue(null, “new DateTime(2004, 8, 14)”) or refer to other objects such as those in the variable dictionary or in the IoC container. The latter two usages will be discussed later.

Classes used in the examples

The following simple classes are used to demonstrate the functionality of the expression language.

public class Inventor
    public string Name;
    public string Nationality;
    public string[] Inventions;
    private DateTime dob;
    private Place pob;

    public Inventor() : this(null, DateTime.MinValue, null)

    public Inventor(string name, DateTime dateOfBirth, string nationality)
        this.Name = name;
        this.dob = dateOfBirth;
        this.Nationality = nationality;
        this.pob = new Place();

    public DateTime DOB
        get { return dob; }
        set { dob = value; }

    public Place PlaceOfBirth
        get { return pob; }

    public int GetAge(DateTime on)
        // not very accurate, but it will do the job ;-)
        return on.Year - dob.Year;

public class Place
    public string City;
    public string Country;

public class Society
    public string Name;
    public static string Advisors = "advisors";
    public static string President = "president";

    private IList members = new ArrayList();
    private IDictionary officers = new Hashtable();

    public IList Members
        get { return members; }

    public IDictionary Officers
        get { return officers; }

    public bool IsMember(string name)
        bool found = false;
        foreach (Inventor inventor in members)
            if (inventor.Name == name)
                found = true;
        return found;

The code listings in this chapter use instances of the data populated with the following information.

Inventor tesla = new Inventor("Nikola Tesla", new DateTime(1856, 7, 9), "Serbian");
tesla.Inventions = new string[]
        "Telephone repeater", "Rotating magnetic field principle",
        "Polyphase alternating-current system", "Induction motor",
        "Alternating-current power transmission", "Tesla coil transformer",
        "Wireless communication", "Radio", "Fluorescent lights"
tesla.PlaceOfBirth.City = "Smiljan";

Inventor pupin = new Inventor("Mihajlo Pupin", new DateTime(1854, 10, 9), "Serbian");
pupin.Inventions = new string[] {"Long distance telephony & telegraphy", "Secondary X-Ray radiation", "Sonar"};
pupin.PlaceOfBirth.City = "Idvor";
pupin.PlaceOfBirth.Country = "Serbia";

Society ieee = new Society();
ieee.Officers["president"] = pupin;
ieee.Officers["advisors"] = new Inventor[] {tesla, pupin};

Basic Configuration

When labPortal is configured there are some basic settings available for configuration.
These settings are stored in the Contract table.
There is no UI for managing these settings as they are intended to be set when labPortal is first provisioned and then not changed.
The system is designed to fail to false, therefore if there is no entry for a particular setting labPortal will assume the record is false.

Setting Description Value
PlugInMask Path to plug in dlls
DefaultArea Used to configure the default page for a user when they login results
DefaultController Used to configure the default page for a user when they login samples
DefaultAction Used to configure the default page for a user when they login index
ShowLimits Display mapped limits on the single sample page true/false
DisableFlags Disable the flag column on samples grid and single sample view true/false
ShowAllDets Enable the AllDets setting so that you can display all determinations in the grid on a single page, this has a massive performance impact and is not recommended true/false
ExcelExportDetcodeHeader Changes Excel Export to use the detcodes instead of the detshort codes true/false
EmailRoot The Root Email Address used for the Admin Account
EmailToFeedback The email address that feedback is sent to
EmailBccFeedback The email address that feedback is sent to bcc The laboratory’s email
ResultsEnableJobs Enables the Jobs Module true/false
EnableOrders Enables the Orders Module true/false

If changes are made to the contracts table the website needs to be restarted to enable the settings to be reloaded

Reference Data

The detname and units in the Sample Grid come from the reference data spreadsheet.
The system looks for a worksheet called ‘dets’.
Once it has loaded the ‘dets’ worksheet it will be looking for a set of columns

DET The DET has to match the codes that are found in your LIMS system as the system will use this as the key column
DETNAME Is the long description that is shown in the tooltip when you hover your mouse over the column header
SHORTNAME If provided the SHORTNAME replaces the Detcode in the column header. It is often used when the user f the labPortal would not know what the DETCODE was.
UNITS The Units of the DET to be displayed in the tooltip when you hover over the column header
VIEW The VIEW tag is picked up and displayed in a dropdown above the grid. If the users selects the view then the grid will only display those determinations that are associated with the view.
ORDER Needs to be an integer and is used to order the columns as they are rendered from left to right using an ascending sort order

Although duplicate DETs will not break the system, it may result in unexpected behaviour for the user.

A template spreadsheet has been attached to this article.

When you need to update the Spreadsheet please email a copy to and we will update your system accordingly.

Refine your Job Search

By using special characters, operators and quotation marks around a phrase, you can fine-tune your search query and increase the accuracy of its results.

Phrase Searches
To search for a phrase, a proper name, or a set of words in a specific order, put them in double quotes.

“Old Dean”
Wildcard Searches
You can perform single and multiple character wildcard searches within a single term (not within phrase queries).

To perform a single character wildcard search use the “?” symbol.

To perform a multiple character wildcard search use the “*” symbol.

The single character wildcard search looks for terms that match that with the single character replaced. For example, to search for “text” or “test” you can use the search:

Multiple character wildcard searches looks for 0 or more characters. For example, to search for test, tests or tester, you can use the search:

You can also use the wildcard searches in the middle of a term.

Note: You cannot use a * or ? symbol as the first character of a search.

Fuzzy Search
To do a fuzzy search use the tilde, “~”, symbol at the end of a Single word Term. For example to search for a term similar in spelling to “roam” use the fuzzy search:

This search will find terms like foam and roams.

Boolean Operators
Boolean operators allow terms to be combined through logic operators. labPortal supports AND, “+”, OR, NOT and “-” as Boolean operators(Note: Boolean operators must be ALL CAPS).

The OR operator is the default conjunction operator. This means that if there is no Boolean operator between two terms, the OR operator is used. The OR operator links two terms and finds a matching record if either of the terms exist in a record. The symbol || can be used in place of the word OR.

To search for documents that contain either “old dean” or just “dean” use the query:

“jakarta apache” jakarta

“jakarta apache” OR jakarta
The AND operator matches documents where both terms exist anywhere in the text of a single document. This is equivalent to an intersection using sets. The symbol && can be used in place of the word AND.

To search for documents that contain “jakarta apache” and “Apache Lucene” use the query:

“jakarta apache” AND “Apache Lucene”
The NOT operator excludes documents that contain the term after NOT. This is equivalent to a difference using sets. The symbol ! can be used in place of the word NOT.

To search for documents that contain “jakarta apache” but not “Apache Lucene” use the query:

“jakarta apache” NOT “Apache Lucene”
Note: The NOT operator cannot be used with just one term. For example, the following search will return no results:

NOT “jakarta apache”

Sample Views

A Sample View is a predetermined configuration of columns that renders a Samples Down, Determinations across view of the data. When a View is selected the Sample Grid is redrawn to include all Sample Properties and only those column included in the View

There are 3 types of Views available

  1. Suite
  2. All Dets
  3. Free Form


The suite view includes only those determinations that are included within the select suite. The suite view is automatically configured by the suites that are uploaded by the publishing process.

All Dets

The “All Dets” view includes all determination that have been uploaded for a given client. Some systems and clients can have a huge number of Dets. As a result we suggest that this view is used with caution as it can be very slow to render.

Free Form

The Free Form views are views that are constructed from the metadata provided in the reference data spreadsheet.


How can I see the most recently uploaded samples and their results?

The Results > Samples view, by default, will show the latest samples that have been uploaded to labPortal.

How to view a samples results as a list?

You can easily view a samples details by clicking on the row. This will display the Single Sample view of the sample where you can review all of the sample properties, results and comments in a single screen.