Custom Functions

Oct 28, 2022
4 minutes to read

Overview

Expressions in reports support multiple predefined functions, described in the following help topic: Functions in Expressions. If you need more flexibility in the expressions used in your application, implement and register custom functions. The scope of custom functions depends on the interface implemented in the function and registration method.

For information on custom aggregate functions, review the following help topic: Custom Aggregate Functions.

Custom Function Interfaces

A custom function implements one of the following interfaces:

ICustomFunctionOperator: Declares the base functionality for custom functions.
ICustomFunctionOperatorBrowsable: Contains descriptive information about a custom function for use in the Expression editor (category, description, number of parameters).
ICustomFunctionOperatorFormattable: Allows you to use the Query Builder or filter editor to insert a string into SQL queries generated for SELECT operations.
ICustomFunctionDisplayAttributes: Allows you to create a custom function displayed as a comparison operator and specify the operator’s display settings.

Registration Scope

You should register custom functions in your Reporting application. When you register a function, you can choose between two scopes in which the function is available:

Data Access Scope

Query Builder
- Expression Editor
- FilterString Editor
Data Wizard
- Parameters (Expression Editor)

Reporting Scope

Expression Editor
Calculated Field editor
Parameter editor
Expression Collection Editor (to modify binding expressions for controls and parameters)
FilterString Editor

Registration Methods

You can use one of the following registration methods:

CriteriaOperator.RegisterCustomFunction: Registers the function so that it can be accessed anywhere in the application. The available scopes are Data Access and Reporting.
CustomFunctions.Register: Registers a function so that it is only available in the Reporting scope.

Implement a Function

To add a custom function, create a ReportCustomFunctionOperatorBase class descendant.

The following code defines a custom function in the String category:

CustomFormatFunction.cs
CustomFormatFunction.vb

using DevExpress.XtraReports.Expressions;
using System;
// ...
    public class CustomFormatFunction : ReportCustomFunctionOperatorBase
    {
        public override string FunctionCategory 
            => "String";
        public override string Description 
            => "CustomFormatFunction(string format, object arg0)" +
            "\r\nConverts an arg0 value to a string based on a specified format";
        public override bool IsValidOperandCount(int count) 
            => count == 2;
        public override bool IsValidOperandType(int operandIndex, int operandCount, Type type) 
            => true;
        public override int MaxOperandCount
            => 2;
        public override int MinOperandCount
            => 2;
        public override object Evaluate(params object[] operands)
        {
            string res = String.Format(operands[0].ToString(), operands[1]);
            return res;
        }
        public override string Name 
            => "CustomFormatFunction";
        public override Type ResultType(params Type[] operands)
        {
            return typeof(string);
        }
    }

Imports DevExpress.XtraReports.Expressions
Imports System
' ...
    Public Class CustomFormatFunction
        Inherits ReportCustomFunctionOperatorBase

        Public Overrides ReadOnly Property FunctionCategory() As String
            Get
                Return "String"
            End Get
        End Property
        Public Overrides ReadOnly Property Description() As String
            Get
                Return "CustomFormatFunction(string format, object arg0)" _
                & ControlChars.CrLf & "Converts an arg0 value to a string based on a specified format"
            End Get
        End Property
        Public Overrides Function IsValidOperandCount(ByVal count As Integer) As Boolean
            Return count = 2
        End Function
        Public Overrides Function IsValidOperandType(ByVal operandIndex As Integer,
            ByVal operandCount As Integer, ByVal type As Type) As Boolean
            Return True
        End Function
        Public Overrides ReadOnly Property MaxOperandCount() As Integer
            Get
                Return 2
            End Get
        End Property
        Public Overrides ReadOnly Property MinOperandCount() As Integer
            Get
                Return 2
            End Get
        End Property
        Public Overrides Function Evaluate(ParamArray ByVal operands() As Object) As Object
            Dim res As String = String.Format(operands(0).ToString(), operands(1))
            Return res
        End Function
        Public Overrides ReadOnly Property Name() As String
            Get
                Return "CustomFormatFunction"
            End Get
        End Property
        Public Overrides Function ResultType(ParamArray ByVal operands() As Type) As Type
            Return GetType(String)
        End Function
    End Class

Register a Function

Register at Runtime

Call the CustomFunctions.Register static method at application startup:

DevExpress.XtraReports.Expressions.CustomFunctions.Register(new CustomFormatFunction());

DevExpress.XtraReports.Expressions.CustomFunctions.Register(New CustomFormatFunction())

After registration, the function is available in the Expression Editor and expression bindings at runtime.

Register in the Visual Studio Report Designer

To enable a custom function in Visual Studio Report Designer, do the following:

Create a custom component in Visual Studio. For this, press Ctrl+Shift+A, and select a new Component Class item.
Call the CustomFunctions.Register method in the component’s constructor.
Rebuild the project.
Open the Report Designer and drop the newly created custom component from the Toolbox to the report design area.
Invoke the Expression Editor. The previously registered function is available.

Note

In Visual Studio, you can register custom functions only in projects that target .NET Framework. In .NET/.NET Core projects, custom functions are not available.

Unregister a Function

To unregister a previously registered function, call the CustomFunctions.Unregister static method.

Unregistered functions are not available in the Expression Editor. An expression that has unregistered functions is evaluated as an empty value.

Invoke the Expression Editor

The Expression Editor displays the CustomFormatFunction in the String category:

Custom Function in Expression Editor for WinForms