Rules Schema Description

Retired Content
This content and the technology described is outdated and is no longer being maintained. For more information, see Transient Fault Handling.

On this page:
The rules Element | The constraintRules Element | Attributes of the rule Element | Attributes of the range Element | Attributes and Children of the timetable Element | The reactiveRules Element | Attributes of the rule Element | The when Element | The actions Element | The operands Element

This topic lists the XML elements and attributes used to define the autoscaling rules in the Autoscaling Application Block. You can manually edit the XML data in a text or XML editor, or build your own tool to edit the configuration data. You can use the schema information contained in this topic when you edit the data manually, or when you design your own custom UI to edit this data.

If you installed the Autoscaling Application Block in your Visual Studio project by using NuGet, you can find the AutoscalingRules.xsd schema file in the root folder of the project.

The rules file has the following top-level structure.

<rules xmlns=
    https://schemas.microsoft.com/practices/2011/entlib/autoscaling/rules
  enabled="true">
  <constraintRules>
    ...
  </constraintRules>

  <reactiveRules>
    ...
  </reactiveRules>
  
  <operands>
    ...
  </operands>
</rules>

The rules Element

The top-level rules element has three optional child elements: the constraintRules element, the reactiveRules element, and the operands element (if there is a reactiveRules element, there must also be an operands element).

The enabled attribute of the rules element is a global flag that you can use to disable all rules evaluation in the Autoscaling Application Block. Its default value is true.

The constraintRules Element

The constraintRules element contains one or more rule elements that define constraint rules. Each rule element contains an optional actions element and an optional timetable element. The actions element contains one or more range elements.

The following snippet shows an example of a constraintRules element. For more examples, see the topic "Defining Constraint Rules."

<constraintRules>
  <rule name="Weekly Rule" description="Example weekly rule" rank="10" 
    enabled="true">
    <timetable startTime="06:00:00" duration="12:00:00" endDate="2011-12-15" 
      utcOffset="-08:00">
      <weekly days="Saturday Sunday" />
    </timetable>
  </rule>
  ...
</constraintRules>

Attributes of the rule Element

The following table describes the attributes of the rule element that defines a constraint rule. This rule element is a child of the constraintRules element.

Attribute	Description
name	A string name for the rule. This can be used to identify the rule in a rule editing UI. This is a required attribute.
description	A string description for the rule. This can be used to describe the rule in a rule editing UI. This is an optional attribute.
rank	A positive integer. The rank of the rule is a number greater than or equal to one. When rules conflict, the rule with the highest rank takes precedence. If two rules conflict and have the same rank, the block will use the first rule. This is an optional attribute. If this attribute is omitted, a rank of one is assumed.
enabled	A Boolean flag. If this is true, the rule is evaluated by the rule evaluator. If this is false, the rule is ignored. The default value is true. This is an optional attribute.

Attributes of the range Element

The following table describes the attributes of the range element that defines a constraint rule. This element is a child of the actions element that is a child of the rule element. Each range must identify a unique target.

Attribute	Description
target	A string. This identifies the target for the rule. It can be either the name of a role or a scale group as defined in the service information configuration data. This is a required attribute.
min	A positive integer that is less than or equal to the value of the max attribute. The minimum number of instances of the target that the block should allow. If the target is a scale group, the ratios of the scale group members will affect the actual number of instances of individual roles. This is a required attribute.
max	A positive integer that is greater than or equal to the value of the min attribute. The maximum number of instances of the target that the block should allow. If the target is a scale group, the ratios of the scale group members will affect the actual number of instances of individual roles. This is a required attribute.

Attributes and Children of the timetable Element

The following table describes the attributes of the timetable element. The timetable element is an optional child of the rule element. If there is no timetable, the rule is assumed to always be in effect.

Attribute	Description
startTime	The time that the rule becomes active. This is a required attribute.
duration	The period after the start time that the rule remains active. This is a required attribute.
startDate	The date that the rule first becomes active. This is an optional attribute.
endDate	The date when the rule ceases to be active. This is an optional attribute.
utcOffset	The number of hours, positive or negative, offset from UTC. This allows you to enter the start time in your local time. This is an optional attribute.

The timetable element contains one of the following child elements.

Element	Description
daily	Indicates that the rule applies every day. This element has no attributes.
weekly	Indicates that the rule is active on specific days of the week.
monthly	Indicates that the rule is active on specific days in the month. For example, the 15th or the 22nd.
relativeMonthly	Indicates that the rule is active on relative days in the month. For example on the second day, or the last day.
yearly	Indicates that the rule is active on specific days in the year.
relativeYearly	Indicates that the rule is active on relative days in the year. For example on the second day, or the last day.

The following table lists the attributes of the weekly element.

Attribute	Description
days	A string containing one or more of Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday. This is a required attribute.

The following table lists the attributes of the monthly element.

Attribute	Description
dayOfMonth	A positive integer up to 31. This is a required attribute.

The following table lists the attributes of the relativeMonthly element.

Attribute	Description
dayOfWeek	A string containing one of Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday. This is a required attribute.
position	A string containing one of First, Second, Third, Fourth, Last. This is a required attribute.

The following table lists the attributes of the yearly element.

Attribute	Description
dayOfMonth	A positive integer up to 31. This is a required attribute.
month	A positive integer up to 12. This is a required attribute.

The following table lists the attributes of the relativeYearly element.

Attribute	Description
dayOfWeek	A string containing one of Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday. This is a required attribute.
position	A string containing one of First, Second, Third, Fourth, Last. This is a required attribute.
month	A positive integer up to 12. This is a required attribute.

The reactiveRules Element

The reactiveRules element is a child of the top-level rules element. It contains one or more rule elements that define relative rules. Each rule element contains a when element and an optional actions element.

The actions element contains one or more scale elements that each has a unique target. The actions element can also contain custom elements that describe your own custom actions. See the topic "Extending and Modifying the Autoscaling Application Block" for more information.

The following snippet shows an example of a reactiveRules element. For more examples, see the topic "Defining Reactive Rules."

<reactiveRules>
  <rule name="Example Scaling Rule" rank="100">
    <when>
      <greater operand="CPU_RoleA" than="80"/>
    </when>
    <actions>
      <scale target="WorkerRoleA" by="2"/>
    </actions>
  </rule>
  ...
</reactiveRules>

Attributes of the rule Element

The following table describes the attributes of the rule element that defines a reactive rule. This rule element is a child of the reactiveRules element.

Attribute	Description
name	A string name for the rule. This can be used to identify the rule in a rule editing UI. This is a required attribute.
description	A string description for the rule. This can be used to describe the rule in a rule editing UI. This is an optional attribute.
rank	A positive integer. The rank of the rule is a number greater than or equal to one. When rules conflict, the rule with the highest rank takes precedence. This is an optional attribute. If this attribute is omitted, a rank of one is assumed.
enabled	A Boolean flag. If this is true, the rule is evaluated by the rule evaluator. If this is false, the rule is ignored. The default value is true. This is a required attribute.

The when Element

The when element is a child of the rule element in a reactive rule. This element defines the Boolean expression that is evaluated to determine whether the rule's action should be executed. The when element contains one of the child elements in the following table.

Element	Description
all	Contains one or more of the elements listed in this table as children. This element indicates that the expression is true if all its child expressions are true. This element enables nested conditions.
any	Contains one or more of the elements listed in this table as children. This element indicates that the expression is true if one or more of its child expressions are true. This element enables nested conditions.
not	Contains one of the elements listed in this table as a child element. This element negates the value of the child expression. This element enables nested conditions.
greater	Indicates that the expression is true if the operand is greater than the supplied value.
greaterOrEqual	Indicates that the expression is true if the operand is greater than or equal to the supplied value.
less	Indicates that the expression is true if the operand is less than the supplied value.
lessOrEqual	Indicates that the expression is true if the operand is less than or equal to the supplied value.
equals	Indicates that the expression is true if the operand is equal to the supplied value.

The following table describes the attributes of the comparison****elements (greater, greaterOrEqual, less, lessOrEqual, equals) that make up the Boolean expression in the reactive rule. These elements are children of the when element or children of the and, any, or not elements.

Attribute	Description
operand	Applies to the following elements: greater, greaterOrEqual, less, lessOrEqual, equals. A string that identifies the operand. This is a required attribute.
than	Applies to the following elements: greater, greaterOrEqual, less, lessOrEqual. The value that the operand value is compared to. This is a required attribute.
to	Applies to the following elements: equals. The value that the operand value is compared to. This is a required attribute.

The string value of each operand, than, and to attribute can be one of the following:

• The name of an operand defined in the operands element.
• An integer or decimal number.
• A simple expression that multiples a number and an operand.
• A simple expression that divides an operand by a number.

For complete examples of when elements, see the topic "Defining Reactive Rules."

The actions Element

The actions element is a child of the rule element in a reactive rule. This element defines the scaling actions that are performed when the expression in the when element evaluates to true. The actions element contains one or more scale elements or changeSetting attributes. It can also include custom elements that define custom scaling actions. See the topic "Extending and Modifying the Autoscaling Application Block" for more information.

The following table lists the attributes of the scale element.

Attribute	Description
target	A string. This identifies the target for the rule. It can be either the name of a role or a scale group, as defined in the service information configuration data. This is a required attribute.
by	An integer or an integer with a trailing % (percent symbol). Negative values are permitted. If the attribute value is an integer, this is the number by which the current number of role instances should be incremented or decremented. If the attribute value is a percentage, this is the proportion by which the current number of role instances should be adjusted. This is a required attribute. Examples include: 2 -3 +25%

The following table lists the attributes of the changeSetting element.

Attribute	Description
target	A string. This identifies the target for the rule. It can be either the name of a role or a scale group, as defined in the service information configuration data. This is a required attribute.
settingName	The name of a setting in the .cscfg file.
value	The value for the setting in the .cscfg file.

The block uses the changeSetting element to notify the Microsoft Azure application that it should perform a throttling action. See the topic "Implementing Throttling Behavior."

The operands Element

The operands element is a child of the top-level rules element. It contains zero or more child elements that define the operands to which the expressions in the reactive rules refer. The children of the operands element are some combination of either the performanceCounter element, the queueLength element, the roleInstanceCount element, or a custom element. See the topic "Extending and Modifying the Autoscaling Application Block" for more information about defining custom operands.

The following snippet shows an example of an operands element. For more examples, see the topic "Defining Reactive Rules."

<operands>
  <performanceCounter alias="CPU_45_RoleA" source="WorkerRoleA" 
    performanceCounterName="\Processor(_Total)\% Processor Time" 
    timespan="00:45:00" aggregate="Average"/>
  <performanceCounter alias="CPU_45_RoleBC" source="ScaleGroupB" 
    performanceCounterName="\Processor(_Total)\% Processor Time" 
    timespan="00:45:00" aggregate="Max"/>
  <queueLength alias="Length_10_QueueC" queue="QueueC"
    timespan="00:10:00" aggregate="Growth"/>
</operands>

The following table lists the attributes of the performanceCounter element.

Attribute	Description
alias	A string. This is the name of the operand that is used in the rule expression elements. This is a required attribute.
performanceCounterName	A string. This is the name of the performance counter. For example: \Processor(_Total)\% Processor Time In this example, Processor(_Total) identifies the performance counter object, and % Processor Time identifies the counter. This is a required attribute.
source	A string. This identifies the Azure role that the performance counter data is collected from. This name must be defined in the role element in the service information configuration file. This is a required attribute.
timespan	The time over which the aggregate value is calculated. This is a required attribute.
aggregate	One of Average, Max, Min, Last, and Growth. This specifies the aggregate calculation that is performed on the performance counter data over the timespan. The Growth aggregate uses simple linear regression to measure the growth of a counter value over time.

The following table lists the attributes of the queueLength element.

Attribute	Description
alias	A string. This is the name of the operand that is used in the rule expression elements. This is a required attribute.
queue	A string. This is the name of the Azure queue. This is a required attribute.
timespan	The time over which the aggregate value is calculated. This is a required attribute.
aggregate	One of Average, Max, Min, Last, and Growth. This specifies the aggregate calculation that is performed on the performance counter data over the timespan. The Growth aggregate uses simple linear regression to measure the growth of a counter value over time.

The following table lists the attributes of the roleInstanceCount element.

Attribute	Description
alias	A string. This is the name of the operand that is used in the rule expression elements. This is a required attribute.
role	A string. This is the name of the Azure role. This is a required attribute.
timespan	The time over which the aggregate value is calculated. This is a required attribute.
aggregate	One of Average, Max, Min, Last, and Growth. This specifies the aggregate calculation that is performed on the performance counter data over the timespan. The Growth aggregate uses simple linear regression to measure the growth of a counter value over time.

Next Topic | Previous Topic | Home

Last built: June 7, 2012