Report expressions
RDL reports are mostly expressions: =Fields!Sales.Value, =Sum(Fields!Sales.Value, "Region"), =Globals!PageNumber & " of " & Globals!TotalPages. DocWright.Reporting evaluates them with an interpreter: no compiler, no reflection and no code generation, with identical results on every runtime.
Report processing evaluates expressions for you. Use the engine directly to evaluate an expression in a designer, a preview or a test.
Parse and evaluate
using System.Globalization;
using DocWright.Reporting.Expressions;
// Parse once (syntax, names and constants are checked here), evaluate many times.
ReportExpression expression = ReportExpression.Parse(
"=Format(Parameters!Amount.Value * 1.1, \"C\") & \" for \" & Parameters!Region.Label");
var context = new ReportExpressionContext();
context.Parameters["Amount"] = new ReportParameterValue(1250);
context.Parameters["Region"] = new ReportParameterValue("W", "West");
Console.WriteLine(ReportExpressionEvaluator.Evaluate(expression, context));
// The culture is never the machine's: en-US unless you say otherwise.
context.Culture = CultureInfo.GetCultureInfo("de-DE");
Console.WriteLine(ReportExpressionEvaluator.Evaluate(expression, context));
// What the expression reads, with positions for a designer's rename.
foreach (ReportExpressionReference reference in expression.References)
{
Console.WriteLine($" {reference.Kind} {reference.Name} at {reference.Position}");
}
Output
$1,375.00 for West
1.375,00 € for West
Parameter Amount at 8
Parameter Region at 56
DXP9106: The expression reads the execution time, and none was supplied: set ReportExpressionContext.ExecutionTime. The clock is never read.
2026-10-01 09:00
- Parse once, evaluate many times.
Parsechecks syntax, names, argument counts and constants. A parsed expression is immutable and safe to share across threads. - Text not starting with
=is a literal and evaluates to itself. - Results are the .NET values Visual Basic produces:
Integerisint,DateisDateTime,Nothingisnull. - Names are case-sensitive, as in Reporting Services.
References,UsesAggregates,UsesPageGlobals,UsesCustomCodeandUsesExecutionTimedescribe what an expression depends on.
Nothing comes from the machine
The culture defaults to en-US, which is what Reporting Services uses for a report with no <Language>, measured. Now(), Today() and Globals!ExecutionTime return the ExecutionTime you supply. Without one, they are refused rather than given the clock:
using DocWright.Reporting.Expressions;
// Now() is never the machine's clock: it is the ExecutionTime you supply.
try
{
ReportExpressionEvaluator.Evaluate(ReportExpression.Parse("=Year(Now())"), new ReportExpressionContext());
}
catch (ReportExpressionException error)
{
Console.WriteLine($"{error.DiagnosticCode}: {error.Message}");
}
var timed = new ReportExpressionContext { ExecutionTime = new DateTime(2026, 10, 1, 9, 0, 0) };
Console.WriteLine(ReportExpressionEvaluator.Evaluate(ReportExpression.Parse("=Format(Now(), \"yyyy-MM-dd HH:mm\")"), timed));
This differs from Reporting Services on purpose: binding every date function to one instant makes a report reproducible.
Functions
ReportFunctionCatalog lists every function an expression can call by name — the Visual Basic functions, Math and Convert, the aggregates and lookups, If and CType — 280 in all, with a category, a signature, a description and an example, and for the 76 DocWright refuses, the reason. It's what an expression editor needs for completion and to explain a refusal before anything runs:
using DocWright.Reporting.Expressions;
// Completion: every function whose name starts with what was typed.
foreach (ReportFunction function in ReportFunctionCatalog.StartingWith("Format"))
{
Console.WriteLine(function.Signature);
}
// What to show for one function, and why a refused one is refused.
ReportFunction mid = ReportFunctionCatalog.Find("Mid")!;
Console.WriteLine($"{mid.Name}: {mid.Category}, returns {mid.ReturnType}. {mid.Description} {mid.Example}");
ReportFunction rnd = ReportFunctionCatalog.Find("Rnd")!;
Console.WriteLine($"{rnd.Name}: {rnd.RefusalCode} {rnd.RefusalReason}");
Format(value, [style])
FormatCurrency(value, [digits], [leadingDigit], [parentheses], [groupDigits])
FormatDateTime(date, [format])
FormatNumber(value, [digits], [leadingDigit], [parentheses], [groupDigits])
FormatPercent(value, [digits], [leadingDigit], [parentheses], [groupDigits])
Mid: Text, returns String. The characters from a 1-based position. =Mid("report", 2, 3)
Rnd: DXP9102 Random numbers would make a report differ each time it runs, so they are not evaluated.
Find accepts any name an expression may use, in any case: Math.Abs, Abs, Strings.Len, Integer.Parse. The argument counts, return types and refusals come from the interpreter itself, and every example of a function DocWright evaluates gives the same value in Microsoft's report engine.
Custom code
A report's <Code> block is Visual Basic from the file, and running it in a server would mean running whatever an uploaded file contains. DocWright never executes it. Implement ReportCodeHost to provide the functions you trust. The SSRS tutorial shows one.
Limits
An expression is a program written by someone else, so evaluation is bounded, and these limits are on by default:
| Limit | Default |
|---|---|
MaxReportExpressionDepth |
256 levels |
MaxReportExpressionSteps |
10,000,000 per evaluation |
MaxReportExpressionAllocation |
16,000,000 characters and array elements per evaluation |
=Space(2000000000) is refused rather than allocating four gigabytes.