Perform advanced tasks on rulesets with the Microsoft Rules Composer (Preview)

Applies to: Azure Logic Apps (Standard)

This guide describes more advanced operations that you can perform on rulesets in the Microsoft Rules Composer.

Prerequisites

• Download and install the Microsoft Rules Composer.

• The XML file that contains the ruleset that you want to work on.

Copy a ruleset version

You can create a copy of an existing ruleset version but with a different version number.

1. Open the Microsoft Rules Composer. In the RuleSet Explorer window, open the ruleset version's shortcut menu, and select Copy.

2. Open the ruleset's shortcut menu, and select Paste RuleSet Version.

   The Microsoft Rules Composer creates a new ruleset version with the same elements as the copied version but with a different number.

   Note

   If you update the .NET assembly used to provide facts to your ruleset, make sure to update your ruleset version's references to that assembly. For more information, see Update .NET assembly references.

Create an empty ruleset version

After you add rules to a ruleset version, you can create a new empty ruleset version with a different number, and save that version for you to work on later.

1. Open the Microsoft Rules Composer. From the ruleset's shortcut menu, select Add New Version.

   The Microsoft Rules Composer creates a new empty ruleset version with a different number.

2. Open the new ruleset version's shortcut menu, and select Save.

You can now copy rules from other ruleset versions, and paste them into the new version.

Pass fact types to a ruleset

Although you can't directly specify a return type for a ruleset, you can pass one of the following types of facts to the ruleset, have the ruleset change the value of the fact to true or false, and then check the value of the property or element/column after the ruleset executes:

• A .NET object that has a property with Boolean type
• An XML document that has an element with Boolean type

Set up a fact retriever for a ruleset

When you use a fact retriever with your ruleset, you can store facts that don't often change so that before your host application's first execution cycle. That way, you can retrieve these facts from storage, present them once to the rules engine for caching, and reuse them over multiple execution cycles. For more information, see Build fact creators and retrievers.

You have two ways to associate a fact retriever with a ruleset:

• Manually select a fact retriever for a ruleset version in the Microsoft Rules Composer.

• Programmatically by using the RuleSetExecutionConfiguration object.

Manually select a fact retriever for a ruleset

1. Open the Microsoft Rules Composer. In the RuleSet Explorer, select the ruleset version that you want to associate with the fact retriever.

2. In the Properties window, select the FactRetriever property row, and then select the ellipsis button (…) to find and select an existing fact retriever object.

   Note

   The ellipsis button (…) doesn't appear until you select the FactRetriever row in the Properties window.

Call a child ruleset from a parent ruleset

For this task, use one of the following methods:

• Call the Ruleset.Execute method directly from the parent ruleset.

• From the parent ruleset, call a method of a helper .NET component that wraps the Ruleset.Execute method.

  With the second method, you can add preprocessing and postprocessing code to the Ruleset.Execute method. For example, you can create any facts required from the child ruleset within this wrapper method. The following sections provide an example for each method.

Call the Ruleset.Execute method directly from the parent ruleset

This section provides high-level steps to call the child ruleset directly from the parent Ruleset by using the Ruleset.Execute method. The following procedure shows the steps to add the Ruleset.Execute method as an action to the parent ruleset that passes an XML document as a fact to the child ruleset.

1. Open the Microsoft Rules Composer. In the Facts Explorer window, select the .NET Classes tab.

2. Open the shortcut menu for .NET Assemblies, and select Browse.

3. From the .NET Assemblies list, select Microsoft.RuleEngine, and then select OK.

4. Expand Ruleset, and drag either Execute(Object facts) or Execute(Object facts, IRuleSetTrackingInterceptor trackingInterceptor) to the THEN pane.

5. Select the XML Schemas node, open the shortcut menu for Schemas, and select Browse.

6. Select the schema for the XML document you want to pass as a fact, and then select Open.

7. To pass the XML document that is passed to the parent ruleset as a fact to the child ruleset, drag <schema-name>.xsd to the first argument in the Ruleset.Execute method.

8. If you use the Execute method that doesn't take IRuleSetTrackingInterceptor as the second argument, skip the following steps.

9. Select the .NET Classes tab, and drag DebugTrackingInterceptor in Microsoft.RuleEngine to the second argument of the Ruleset.Execute method.

   Note

   If you perform this action, the client must pass an instance of the DebugTrackingInterceptor class as a fact to the parent ruleset, which then passes the instance as a fact to the child ruleset. Instead, you can drag the constructor of the DebugTrackingInterceptor class so that the instance is automatically created for you.

Modify the client application that calls the parent ruleset

The client that invokes the parent ruleset creates an instance of the Ruleset class with the child ruleset name as a parameter and passes that instance as a fact to the parent ruleset along with other facts. The following sample code illustrates this action:

DebugTrackingInterceptor dti = new DebugTrackingInterceptor("RulesetTracking.txt");
Ruleset Ruleset = new Ruleset("ParentRuleset");
object[] facts = new object[3];
facts[0] = txd;
facts[1] = new Ruleset("ChildRuleset");
facts[2] = new DebugTrackingInterceptor("RulesetTracking2.txt");
Ruleset.Execute(facts, dti);
Ruleset.Dispose();

If the client is a BizTalk orchestration, you might need to put the code in an Expression shape to create facts, and then pass the facts as parameters to the Call Rules shape.

Call a .NET wrapper method from the parent ruleset

This section presents the high-level steps to invoke a .NET method that wraps the call to the Ruleset.Execute method from the parent ruleset.

Create the utility .NET class

1. Create a .NET class library project. Add a class to the project.

2. Add a static method that calls the Ruleset.Execute method to invoke the ruleset whose name is passed as a parameter, for example, as the following sample code shows:

   public static void Execute(string RulesetName, TypedXmlDocument txd)
   {
       DebugTrackingInterceptor dti = new   DebugTrackingInterceptor("RulesetTracking.txt");
       Ruleset Ruleset = new Ruleset("ParentRuleset");
       object[] facts = new object[3];
       facts[0] = txd;
       facts[1] = new Ruleset("ChildRuleset");
       facts[2] = new DebugTrackingInterceptor("RulesetTracking2.txt");
       Ruleset.Execute(facts, dti);
       Ruleset.Dispose();
   }
   

   The client invokes the parent ruleset, and the parent ruleset calls the helper method that invokes the child ruleset, for example, as the following sample code for the client shows:

   facts[0] = txd;
   facts[1] = new RulesetExecutor(txd);
   
   // Call the first or parent ruleset.
   Ruleset Ruleset = new Ruleset(RulesetName);
   DebugTrackingInterceptor dti = new DebugTrackingInterceptor("RulesetTracking.txt");
   Ruleset.Execute(facts, dti);
   Ruleset.Dispose();
   

   Note

   If the method is an instance method, the client must create an instance of the helper .NET class, and pass that instance as a fact to the parent ruleset.

Analyze multiple objects with the same type in a rule

In many scenarios, you write a business rule against a type and expect the engine to separately analyze and act on each instance of the type that is asserted into the engine. However, in some scenarios, you want the engine to simultaneously analyze multiple instances that have the same type. For example, the following sample rule uses multiple instances of the FamilyMember class:

IF FamilyMember.Role == Father
AND FamilyMember.Role == Son
AND FamilyMember.Surname == FamilyMember.Surname
THEN FamilyMember.AddChild(FamilyMember)

The rule identifies multiple FamilyMember instances where one is a Father and another is a Son. If the instances are related by surname, the rule adds the Son instance to a collection of children on the Father instance. If the engine separately analyzes each FamilyMember instance, the rule never triggers because in this scenario, the FamilyMember only has one role, either Father or Son.

So, in this scenario, you must indicate that the engine analyzes multiple instances together in the rule, and you need a way to differentiate the identity of each instance in the rule. You can use the Instance ID field to provide this functionality. This field is available in the Properties window when you select a fact in the Facts Explorer.

When you use the Instance ID field, the rule is rebuilt. For those rule arguments that use the Son instance of the FamilyMember class, change the Instance ID value from the default of 0 to 1. When you change the Instance ID value from 0, and you drag the fact or member into the Rule Editor, the Instance ID value appears in the rule following the class, for example:

IF FamilyMember.Role == Father
AND FamilyMember(1).Role== Son
AND FamilyMember.Surname == FamilyMember(1).Surname
THEN FamilyMember.AddChild(FamilyMember(1))

Now, assume that a Father instance and a Son instance are asserted into the engine. The engine evaluates the rule against the various combinations of these instances. Assuming that the Father and Son instance have the same surname, the Son instance is added to the Father instance as expected.

Related content

• Create rules with the Microsoft Rules Composer
• Create an Azure Logic Apps Rules Engine project