-
Notifications
You must be signed in to change notification settings - Fork 119
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/06/2024
ArcGIS Pro: 3.4
Visual Studio: 2022
- Introduction
- The Arcade Script Engine
- Creating the Arcade evaluator
- Exception handling
- Additional References
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 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 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.
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);
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))
{
}
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);
// 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.
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()
.
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.
Home | API Reference | Requirements | Download | Samples
- Overview of the ArcGIS Pro SDK
- What's New for Developers at 3.4
- Installing ArcGIS Pro SDK for .NET
- Release notes
- Resources
- Pro SDK Videos
- ProSnippets
- ArcGIS Pro API
- ProGuide: ArcGIS Pro Extensions NuGet
Migration
- ProSnippets: Framework
- ProSnippets: DAML
- ProConcepts: Framework
- ProConcepts: Asynchronous Programming in ArcGIS Pro
- ProConcepts: Advanced topics
- ProGuide: Custom settings
- ProGuide: Command line switches for ArcGISPro.exe
- ProGuide: Reusing ArcGIS Pro Commands
- ProGuide: Licensing
- ProGuide: Digital signatures
- ProGuide: Command Search
- ProGuide: Keyboard shortcuts
Add-ins
- ProGuide: Installation and Upgrade
- ProGuide: Your first add-in
- ProGuide: ArcGIS AllSource Project Template
- ProConcepts: Localization
- ProGuide: Content and Image Resources
- ProGuide: Embedding Toolboxes
- ProGuide: Diagnosing ArcGIS Pro Add-ins
- ProGuide: Regression Testing
Configurations
Customization
- ProGuide: The Ribbon, Tabs and Groups
- ProGuide: Buttons
- ProGuide: Label Controls
- ProGuide: Checkboxes
- ProGuide: Edit Boxes
- ProGuide: Combo Boxes
- ProGuide: Context Menus
- ProGuide: Palettes and Split Buttons
- ProGuide: Galleries
- ProGuide: Dockpanes
- ProGuide: Code Your Own States and Conditions
Styling
- ProSnippets: Content
- ProSnippets: Browse Dialog Filters
- ProConcepts: Project Content and Items
- ProConcepts: Custom Items
- ProGuide: Custom Items
- ProGuide: Custom browse dialog filters
- ArcGIS Pro TypeID Reference
- ProSnippets: Editing
- ProConcepts: Editing
- ProConcepts: COGO
- ProConcepts: Annotation Editing
- ProConcepts: Dimension Editing
- ProGuide: Editing Tool
- ProGuide: Sketch Tool With Halo
- ProGuide: Construction Tools with Options
- ProGuide: Annotation Construction Tools
- ProGuide: Annotation Editing Tools
- ProGuide: Knowledge Graph Construction Tools
- ProGuide: Templates
3D Analyst Data
Plugin Datasources
Topology
Linear Referencing
Object Model Diagram
- ProSnippets: Geometry
- ProSnippets: Geometry Engine
- ProConcepts: Geometry
- ProConcepts: Multipatches
- ProGuide: Building Multipatches
Relational Operations
- ProSnippets: Knowledge Graph
- ProConcepts: Knowledge Graph
- ProGuide: Knowledge Graph Construction Tools
Reports
- ProSnippets: Map Authoring
- ProSnippets: Annotation
- ProSnippets: Charts
- ProSnippets: Labeling
- ProSnippets: Renderers
- ProSnippets: Symbology
- ProSnippets: Text Symbols
- ProConcepts: Map Authoring
- ProConcepts: Annotation
- ProConcepts: Dimensions
- ProGuide: Tray buttons
- ProGuide: Custom Dictionary Style
- ProGuide: Geocoding
3D Analyst
CIM
Graphics
Scene
Stream
Voxel
- ProSnippets: Map Exploration
- ProSnippets: Custom Pane with Contents
- ProConcepts: Map Exploration
- ProGuide: Map Pane Impersonation
- ProGuide: TableControl
Map Tools
- ProGuide: Feature Selection
- ProGuide: Identify
- ProGuide: MapView Interaction
- ProGuide: Embeddable Controls
- ProGuide: Custom Pop-ups
- ProGuide: Dynamic Pop-up Menu
Network Diagrams
- ArcGIS Pro API Reference Guide
- ArcGIS Pro SDK (pro.arcgis.com)
- arcgis-pro-sdk-community-samples
- ArcGISPro Registry Keys
- ArcGIS Pro DAML ID Reference
- ArcGIS Pro Icon Reference
- ArcGIS Pro TypeID Reference
- ProConcepts: Distributing Add-Ins Online
- ProConcepts: Migrating to ArcGIS Pro
- FAQ
- Archived ArcGIS Pro API Reference Guides
- Dev Summit Tech Sessions