ProConcepts Arcade

Functionality that uses the ArcadeScriptEngine API. Arcade API functionality is found in ArcGIS.Core.dll in the namespace ArcGIS.Core.Arcade. The Arcade API is commonly used in conjunction with geodatabase and mapping components.

ArcGIS.Core.dll

Language:      C#
Subject:       Arcade
Contributor:   ArcGIS Pro SDK Team <arcgisprosdk@esri.com>
Organization:  Esri, http://www.esri.com
Date:          10/02/2023
ArcGIS Pro:    3.2
Visual Studio: 2022

In this topic

• Introduction
• The Arcade Script Engine
  • Arcade Profiles
  • Find the required version for an expression
• Creating the Arcade evaluator
  • Find required fields for expressions
  • Evaluating expressions
• Exception handling
• Additional References

Introduction

Arcade is a portable, lightweight, and secure expression language used to create custom content in ArcGIS applications. Like other expression languages, it can perform mathematical calculations, format text, and evaluate logical statements. It also supports multi-statement expressions, variables, and flow control statements. Arcade is unique when compared to other expression and scripting languages because of its inclusion of GIS data types such as features and geometry.

Arcade is used in many places in ArcGIS Pro such as label expressions, symbology expressions, calculate field expressions, and attribute rules. Custom logic can be set for these cases using the ArcGIS Pro application or via their respective APIs in the ArcGIS Pro SDK. See the map authoring snippets for examples of configuring mapping components to use Arcade. Outside of these built-in uses of Arcade, the ArcadeScriptEngine allows for use of Arcade in ArcGIS Pro add-ins or standalone CoreHost applications. This allows for applications to use Arcade expressions for custom workflows in new areas and expose expressions to users of the customization.

The Arcade Script Engine

The ArcadeScriptEngine is the entry point for integrating Arcade into your ArcGIS Pro customizations or standalone CoreHost applications. You'll primarily use this object to create the Arcade evaluator or find the required version for an expression. It is a singleton object and the engine instance can be accessed via its static ArcadeScriptEngine.Instance property. The engine instance has two additional methods: ArcadeScriptEngine.Instance.GetRequiredVersion(expression, profile) which returns the minimum required version of Arcade for the given expression and ArcadeScriptEngine.Instance.GetVersion() which returns the current (installed) version of the Arcade engine. This represents the highest version of Arcade functionality supported by the object. Consult the Arcade version matrix for the list of versions and functionality for each version.

Arcade Profiles

Arcade profiles define the environment and rules for how an Arcade expression is evaluated and interpreted. Specifically an Arcade profile specifies:

• the execution context - or the environment controlling the expression's execution.
• the profile variables that can be used as input data values to the expression,
• the function bundles available, and
• the valid data types that may be returned from an expression.

When evaluating expressions via the ArcadeScriptEngine you select a profile for execution. When using a profile, the input global variables must match the expected names of that profile. Two profiles are available for custom applications: Restricted which provides access to the Core and Geometry function bundles and Unrestricted which provides access to all Arcade functionality supported by ArcGIS Pro. Set Restricted as the default when starting your application if doing simple calculations. Use other profiles for additional functionality.

When passing profile variables to the expression the following data types are supported: System.Boolean, System.Int32, System.Int64, System.Single, System.Double, System.String, System.Collections.Generic.Dictionary{TKey, TValue}, ArcGIS.Core.Data.Row, ArcGIS.Core.Data.Feature, ArcGIS.Core.Data.Table, ArcGIS.Core.Data.FeatureClass, ArcGIS.Core.Data.Database, and ArcGIS.Desktop.Mapping.FeatureLayer. Dictionary objects can contain the other types including nested Dictionary objects.

Find the required version for an expression

There may be cases where you want to limit the functionality of Arcade expressions so that they work over a number of Arcade versions. For instance, if your application supports multiple versions of ArcGIS Pro, you may want to limit expression functionality to the lowest version to ensure compatibility. The Arcade language has its own version numbers, so consult the version matrix for Arcade and application versions to target. The Arcade version of an expression is dependent on the expression itself, primarily function usage, and the profile. Call the GetRequiredVersion() function to obtain the version as a string. Typically the required version is much lower than the current version of ArcadeScriptEngine unless the expression uses newer functions or profiles. For example:

var expressionInfo = new CIMExpressionInfo() {
    Expression = " ..... ",
    Title = "Custom"
};
var requiredVer = ArcadeScriptEngine.Instance.GetRequiredVersion(expressionInfo, ArcadeProfile.Visualization);

Creating the Arcade evaluator

The ArcadeEvaluator is created via the ArcadeScriptEngine. Two inputs are required for creation, the expression itself in a CIMExpressionInfo object and the selected ArcadeProfile.

var expressionInfo = new CIMExpressionInfo()
{
  Name = "Expression Result",
  Title = "Expression Result",
  Expression = "$feature.NAME + ' ' + $feature.STATENAME",
  ReturnType = ExpressionReturnType.String,
};
using (var arcadeEvaluator = ArcadeScriptEngine.Instance.CreateEvaluator(expressionInfo, ArcadeProfile.Labeling))
{
}

Find required fields for expressions

It's best practice to request only the fields necessary for the work being performed when creating a database cursor. The .GetFields(...) method on the ArcadeEvaluator is used to provide the fields needed for the specific profile variable in the expression. After acquiring the fields necessary for the expression they can be specified as the output fields of the query filter used to query the data. If your query filter already contains fields, append them to the existing fields list.

var fields = arcadeEvaluator.GetFields("$feature", table);

var queryFilter = new QueryFilter();
queryFilter.SubFields = string.Join(",", fields);

Evaluating expressions

// create necessary profile variables
var profileVariables = new List<KeyValuePair<string, object>>()
{
  new KeyValuePair<string, object>("$feature", feature),
};
try
{
  // evaluate expression
  var result = arcadeEvaluator.Evaluate(profileVariables);
  // do something with result
}
catch (Exception ex)
{
}

Expression evaluation returns an ArcadeEvaluationResult. Use the .GetResults() method to obtain the result as returned or use the .CastTo() method to cast to a type specified by the ExpressionReturnType using Arcade's casting rules.

Exception handling

ArcadeScriptEngine, ArcadeEvaluator, and ArcadeEvaluationResult may return Arcade specific exceptions:

A ParsingException can be returned from CreateEvaluator() when the expression is invalid. Invalid cases may include incorrect syntax or use of a non-existent function. The Message of the exception will contain information about the problem and may include the line number.

An EvaluationException is returned when there is a failure with execution of the script with ArcadeEvaluator.Evaluate(). The Message of the exception will contain information about the problem and may include the line number.

InvalidProfileVariableException is returned by ArcadeEvaluator.Evaluate() when an invalid type is passed as to the Evaluate() method. See Arcade Profiles for information about supported types.

InvalidResultTypeException is returned when an invalid type is returned from ArcadeEvaluator.Evaluate().

ArcadeOperationFailedException is returned when there has been an underlying exception in ArcadeEvaluationResult.GetResult(), ArcadeEvaluationResult.CastTo() and ArcadeEvaluationResult.IsEqual().

Additional References

The ArcGIS Arcade documentation on the ArcGIS Developers site provides an overview of the Arcade language, function reference documentation, and a playground for quick evaluation of expressions. ProSnippets-MapAuthoring contains numerous examples of ArcadeScriptEngine in use.