Skip to content

extending_rules.md

Latest commit

 

History

History
50 lines (39 loc) · 2.25 KB

extending_rules.md

File metadata and controls

50 lines (39 loc) · 2.25 KB

Extending XAML Rules

In CPS, you can extend a XAML rule of the same name by setting OverrideMode="Extend". Alternatively, you can use OverrideMode="Replace" if you desire to completely override any existing rule of the same name.

This is useful if you are building ontop of an existing project system and want to add or change properties to the existing rules.

Example:

<Rule
  Name="RuleToExend"
  DisplayName="File Properties"
  PageTemplate="generic"
  Description="File Properties"
  OverrideMode="Extend"
  xmlns="http://schemas.microsoft.com/build/2009/properties">
  <!-- Add new properties, data source, categories, etc -->

</Rule>

Extending Behavior

  • Can only extend/replace rules of the same name.
  • (17.0 and earlier) Can only be performed on rules imported via MSBuild, and not by extension points.
  • (17.1 and later) Rules imported via MSBuild and extension points can be extended (but see Source Order, below).
  • Can be performed multiple times. Including multiple replaces.
  • Performed in the order they are returned from MSBuild evaluation.
  • When extending a rule, a 3rd rule is created that is a combination of the original rule and extending rule.
  • When replacing a rule, the old rule is discarded and the new rule used.
  • All values are taken from the extending rule if they exist, and defaulting to the original rule if they do not.
  • Properties, Categories, and Metadata of a rule are merged together between the base and extending rule. In the case of collisions, the value of the extending rule is taken.

Source Order

The source of a rule affects which rules it can override/extend, and which rules can override/extend it. Here are the sources in decreasing priority order (i.e. rules from sources earlier in the list can override/extend those later in the list):

  1. MSBuild PropertyPageSchema items
  2. Rule files added via IAdditionalRuleDefinitionsService
  3. Rule objects added via IAdditionalRuleDefinitionsService
  4. Embedded XAML rules
  5. IRuleObjectProvider implementations

Also, each source has its own means of ordering its rules for the purposes of overriding/extending (e.g., MSBuild items follow the item declaration order in the project; MEF-exported sources use [Order(...)] attributes, etc.).