Working with Source XML

The source object classes topic demonstrates how easy it is to use any existing or newly declared public .NET class as a source object for your business rules, but sometimes you need finer control over your source objects. This is where Source XML plays a major role.

As soon as Code Effects component receives the type of the source object, it reflects and validates it. The result is an XML document known as Source XML. Code Effects component uses that document to hold information about your source object.

You can create such a document manually and pass it to Code Effects component as its source object. There are several reasons why you would want to do this:

  • If you want to skip the processing of the same source object on every load of the page.
  • If you'd like to display fields, in-rule methods, and actions of your rules in multiple languages.
  • If you need almost complete control over the nature of the data Code Effects component sends to the client.

You can create Source XML in one of two ways:

  • If you already have a .NET class that you'd like to use as a template for your Source XML, then simply register Code Effects component on a test web page, set the SourceAssembly and SourceType properties of the RuleEditor class to the type of your template class as shown here, run that page in the debugger, and extract the Source XML into a string variable by calling RuleEditor's GetSourceXml() method. Edit that XML document as needed, validate the result against its schema, and save it in your file system or database. Then reuse it with Code Effects component (see below.)

    // Extract the XML string from the sourceXml variable and edit it...
    string sourceXml = ruleEditor.GetSourceXml();
    
    // ... then store the resulting XML as a file...
    YourStorage.SaveSourceXmlAs("C:\MySourceXml.config", sourceXml);
    
    // ... or as XML type in database
    YourStorage.SaveSourceXmlInDatabase(sourceXml);
  • Another way to generate Source XML is to create it manually against its schema (this link opens the Source XML schema for Code Effects version 4.x)

    IMPORTANT! As of version 3.0, Code Effects component employs schema versioning for rules and source objects by specifying different namespace URLs for different versions.

You can load an existing Source XML document into Code Effects component as its source object by setting the value of either the RuleEditor.SourceXmlFile or RuleEditor.SourceXml property. (See topics on the RuleEditor class for ASP.NET and MVC for details) Below are some short examples of how to do it.

In ASP.NET, if the Source XML is saved as a file, you can register Code Effects component like this:

<%@ Register assembly="CodeEffects.Rule"
namespace="CodeEffects.Rule.Asp" tagprefix="rule" %>

<rule:RuleEditor ID="RuleEditor1" runat="server"
SourceXmlFile="C:\MySourceXml.config" />

... or from the code-behind file:

this.RuleEditor1.SourceXmlFile = Server.MapPath("/MySourceXml.config");

If stored in a database, load the Source XML as shown below:

string sourceXml = YourStorage.GetSourceXmlFromDatabase();
XmlDocument source = new XmlDocument();
source.Load(sourceXml);
this.RuleEditor1.SourceXml = source;

In MVC, use the path to the file while creating the RuleModel object:

[HttpGet]
public ActionResult Index()
{
	ViewBag.Rule = RuleModel.Create(Server.MapPath("/MySourceXML.config"));
	return View();
}

Of course, different source objects use different Source XML documents. In multilingual applications, the use of Source XML is the only way to set different display names for rule fields, in-rule methods and actions based on the user's culture or preference.

In ASP.NET, you can speed up the loading of RuleEditor even more by using built-in caching (turned off by default). This reloads the Source XML from the server's memory:

<rule:RuleEditor ID="RuleEditor1" runat="server"
SourceXmlFile="C:\MySourceXml.config"
CacheSource="true" />

Remember to clear the cache when loading different source object by using the ClearCache() method of the Asp.RuleEditor class.

The RuleEditor in MVC doesn't have this feature. If needed, you can write your own code that caches all Source XML docs if your application uses a large number of source objects.

Post your support requests on Stackoverflow.com. You can also post your comments and product feedback using the form at the bottom of this page.
Comments: 0
Name (optional):
Comment (URLs are allowed and must start with http:// or https://; all tags will be encoded):
Remaining character count: