{"type":"doc","content":[{"type":"paragraph","content":[{"text":"A product can integrate expressions that call C# code using ","type":"text"},{"text":"IExpressionFactory.CreateDelegate()","type":"text","marks":[{"type":"code"}]},{"text":" (or one of its several extension methods).","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Advantages and Drawbacks","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pure expressions","type":"text"}]},{"type":"paragraph","content":[{"text":"Standard expressions and functions have the following advantages:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"They can be mapped to the database, improving ORM speed.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"They can be serialized in remoting drivers","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"They can be analyzed and used by Quino to optimize other operations","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"They have the following drawbacks:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The logic is limited to a single-statement (with some conditional logic, like that provided by the ","type":"text"},{"text":"If","type":"text","marks":[{"type":"code"}]},{"text":" function)","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Evaluation is not easily debugged (there's no source-level debugger for Quino expressions)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Delegate expressions","type":"text"}]},{"type":"paragraph","content":[{"text":"Delegate expressions (and ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://encodo.atlassian.net/wiki/spaces/EB/pages/155877401"}},{"text":") have the following advantages:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"They can contain more complex logic","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"They can be easily debugged","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"They have the following drawbacks:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"They cannot be mapped to the database (there is a mechanism for mapping custom functions to databases. See ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://encodo.atlassian.net/wiki/spaces/EB/pages/155877401"}},{"text":")","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"They cannot be serialized in remoting drivers","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"They cannot be analyzed by Quino","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"With those pros and cons in mind, the following document explains how to add C# delegates to expressions.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Context","type":"text"}]},{"type":"paragraph","content":[{"text":"The context passed to a delegate expression when evaluated contains the following objects by default:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"IDataSession","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"IDataObject","type":"text","marks":[{"type":"code"}]},{"text":" to which the property belongs","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"A product can either use the session to get other dependencies or it can retrieve them from the ","type":"text"},{"text":"IExpressionContext","type":"text","marks":[{"type":"code"}]},{"text":" directly with ","type":"text"},{"text":"GetInstance()","type":"text","marks":[{"type":"code"}]},{"text":". A product can also register its own ","type":"text"},{"text":"IExpressionContextFactory","type":"text","marks":[{"type":"code"}]},{"text":" to control which objects are added.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Examples","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Simple expression","type":"text"}]},{"type":"paragraph","content":[{"text":"Let's start with a calculated property that doesn't use a delegate. Instead, it just returns the value of another property:","type":"text"}]},{"type":"codeBlock","content":[{"text":"personBuilder\n .Add\n .CalculatedProperty(\"Seniority\", MetaType.Integer)\n .Value(\"YearsActive\");\n","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Accessing the object in the context","type":"text"}]},{"type":"paragraph","content":[{"text":"The next example shows how to get this property with a delegate, but without any dependency on ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://encodo.atlassian.net/wiki/spaces/EB/pages/155287658"}},{"text":".","type":"text"}]},{"type":"codeBlock","content":[{"text":"personBuilder\n .Add\n .CalculatedProperty(\"Seniority\", MetaType.Integer)\n .ValueExpression(c => c.YearsActive + 1);\n","type":"text"}]},{"type":"paragraph","content":[{"text":"This example has two problems that we need to address:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It accesses the property by name rather than statically","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"It ","type":"text"},{"text":"requires","type":"text","marks":[{"type":"em"}]},{"text":" that the context contains an object of type ","type":"text"},{"text":"IDataObject","type":"text","marks":[{"type":"code"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Indicating computability","type":"text"}]},{"type":"paragraph","content":[{"text":"In many cases the product will want to indicate that the expression cannot be evaluated with some contexts.","type":"text"}]},{"type":"paragraph","content":[{"text":"In these cases, the product should use a different overload that returns a ","type":"text"},{"text":"bool","type":"text","marks":[{"type":"code"}]},{"text":" and sets an ","type":"text"},{"text":"out","type":"text","marks":[{"type":"code"}]},{"text":" parameter for the value instead.","type":"text"}]},{"type":"codeBlock","content":[{"text":"person\n .Add\n .CalculatedProperty(\"Bonus\", MetaType.Integer)\n .ValueExpression(TryGetBonus);\n\n// ...\n\nprivate bool TryGetBonus(IExpressionContext context, out object value)\n{\n if (context.TryGetInstance(out var person))\n {\n if (person.Company != null)\n {\n if (context.TryGetSingle(out ISystemClock clock))\n {\n if (person.HireDate < clock.UtcNow)\n {\n value = person.Company.GetBonus(person.HireDate.Year);\n\n return true;\n }\n }\n }\n }\n\n value = null;\n\n return return false;\n}\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Comparing parsed and delegate expressions","type":"text"}]},{"type":"paragraph","content":[{"text":"At the same time, you can see how powerful and useful the ","type":"text"},{"type":"inlineCard","attrs":{"url":"https://encodo.atlassian.net/wiki/spaces/EB/pages/155320360"}},{"text":" is: the ","type":"text"},{"text":"GetSalutation()","type":"text","marks":[{"type":"code"}]},{"text":" method has a lot of hand-coding just to get the same behavior as the much shorter text-formatting expression.","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Note: The example below assumes that the field ","type":"text"},{"text":"_expressionParser","type":"text","marks":[{"type":"code"}]},{"text":" is an injected ","type":"text"},{"text":"IExpressionParser","type":"text","marks":[{"type":"code"}]},{"text":".","type":"text"}]}]},{"type":"codeBlock","content":[{"text":"const string conditionText = \"Salutation.IsFormal\";\nconst string familiarText = \"'<{Salutation.Text} {FirstName}>'\";\nconst string formalText = \"'<<{Salutation.Text} {Title}> {LastName}>'\";\n\nvar condition = _expressionParser.CreateExpression(\n conditionText, true, metaClass\n);\nvar familiar = _expressionParser.CreateExpression(\n familiarText, true, metaClass\n);\nvar formal = _expressionParser.CreateExpression(\n formatText, true, metaClass\n);\n\n// Use a pure, parsed expression text\nmetaClass\n .Add\n .CalculatedProperty(\"SalutationText\", MetaType.Text)\n .ValueExpression(\n $\"If({conditionText}, {formatText}, {familiarText})\"\n );\n\n// Use a delegate with a strongly typed parameter\nmetaClass\n .Add\n .CalculatedProperty(\"SalutationTextPureDelegate\", MetaType.Text)\n .ValueExpression

(\n GetSalutation\n );\n\nprivate static object GetSalutation(Address address)\n{\n var salutation = address.Salutation;\n\n if (salutation != null)\n {\n var result = salutation.Text;\n\n if (salutation.IsFormal)\n {\n if (!string.IsNullOrEmpty(address.Title))\n {\n if (string.IsNullOrEmpty(result))\n {\n result = address.Title;\n }\n else\n {\n result += $\" {address.Title}\";\n }\n }\n\n if (string.IsNullOrEmpty(address.Name))\n {\n return result;\n }\n\n return result + $\" {address.Name}\";\n }\n \n if (!string.IsNullOrEmpty(address.FirstName))\n {\n if (string.IsNullOrEmpty(result))\n {\n return address.FirstName;\n }\n\n result += $\" {address.FirstName}\";\n }\n\n return result;\n }\n\n return string.Empty;\n}\n","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Mapping to SQL","type":"text"}]},{"type":"paragraph","content":[{"text":"Until the issue ","type":"text"},{"text":"QNO-6478","type":"text","marks":[{"type":"link","attrs":{"href":"https://secure.encodo.ch/jira/browse/QNO-6478"}}]},{"text":" provides more well-integrated support for mapping ","type":"text"},{"text":"DelegateExpressions","type":"text","marks":[{"type":"code"}]},{"text":" to SQL, a product can build custom mapping with the following pattern.","type":"text"}]},{"type":"paragraph","content":[{"text":"The example below extends the standard ","type":"text"},{"text":"DelegateExpression","type":"text","marks":[{"type":"code"}]},{"text":" to implement ","type":"text"},{"text":"IMappableExpression","type":"text","marks":[{"type":"code"}]},{"text":" and map the simple expression ","type":"text"},{"text":"not Active","type":"text","marks":[{"type":"code"}]},{"text":" for people.","type":"text"}]},{"type":"codeBlock","content":[{"text":"private class IsPersonActiveExpression : DelegateExpression, IMappableExpression\n{\n /// \n public IsPersonActiveExpression()\n : base(ExecuteLocally)\n {\n }\n\n /// \n public bool TryMapExpressionToSql(IExpressionContext context, IExpressionMapper mapper, out string sql)\n {\n switch (mapper.Dialect)\n {\n case SqlDialect.PostgreSql:\n sql = \"not \\\"Person\\\".\\\"active\\\"\";\n\n return true;\n case SqlDialect.SqlServer:\n sql = \"\\\"Person\\\".\\\"active\\\" = 0\";\n\n return true;\n default:\n throw new UnexpectedEnumValueException(mapper.Dialect);\n }\n }\n\n private static bool ExecuteLocally([NotNull] IExpressionContext context, out object value)\n {\n if (context.TryGetInstance(out var person))\n {\n value = person.Active;\n\n return true;\n }\n\n value = null;\n\n return false;\n }\n}\n","type":"text"}]},{"type":"paragraph","content":[{"text":"Note the following in the example above:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"ExecuteLocally","type":"text","marks":[{"type":"code"}]},{"text":" only returns ","type":"text"},{"text":"true","type":"text","marks":[{"type":"code"}]},{"text":" if the context contains a ","type":"text"},{"text":"Person","type":"text","marks":[{"type":"code"}]}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"When mapping SQL, the context is either empty or contains only a session (but no person), so ","type":"text"},{"text":"ExecuteLocally","type":"text","marks":[{"type":"code"}]},{"text":" returns false","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"The method ","type":"text"},{"text":"TryMapExpressionToSql","type":"text","marks":[{"type":"code"}]},{"text":" handles the SQL-mapping case for PostgreSql and SQl Server.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"You can use the expression in a query as follows:","type":"text"}]},{"type":"codeBlock","content":[{"text":"var people = Session.GetList(q => q.Where(new IsPersonActiveExpression()));\n","type":"text"}]},{"type":"paragraph","content":[{"text":"You can use the expression in metadata as follows:","type":"text"}]},{"type":"codeBlock","content":[{"text":"Elements.PersonBuilder\n .Add\n .Property(\"LastActivityTime\", MetaType.Date)\n .IsVisible(new IsPersonActiveExpression());","type":"text"}]},{"type":"paragraph"}],"version":1}

Browser not supported