Ribbon XML in Dynamics 365 Explained

Whoever customizes a button in the command bar creates or changes the ribbon XML of a solution. The structure dates from the time when the interface really was an Office-style ribbon. To this day it is a rather confusing part of the solution export. Here is an overview, so that you do not give up at first contact.

The basic principle: differences, not definitions

The export contains one "RibbonDiffXml" per table. Take the word Diff literally: the file does not describe the whole command bar, only the deviations from the standard. A new button, a hidden standard button, a changed label or a replaced icon.

That is why the export alone never lets you reconstruct the full appearance. You only see what was customized, not what the standard contributes.

The three building blocks

CustomActions place elements. Every CustomAction has a "Location". That is a long, dotted address like "Mscrm.Form.account.MainTab.Actions". It determines where in the bar something appears or disappears. These addresses are the most common source of errors: one typo and the button silently does not show up.

Here is how the parts fit together, for example a button on the account form:

<RibbonDiffXml>
  <CustomActions>
    <CustomAction Id="old.account.Freigabe.CustomAction"
                  Location="Mscrm.Form.account.MainTab.Actions.Controls._children">
      <CommandUIDefinition>
        <Button Id="old.account.Freigabe" Command="old.account.FreigabeCommand"
                LabelText="Freigeben" TemplateAlias="o1" />
      </CommandUIDefinition>
    </CustomAction>
  </CustomActions>
  <CommandDefinitions>
    <CommandDefinition Id="old.account.FreigabeCommand">
      <EnableRules><EnableRule Id="Mscrm.SelectionCountExactlyOne" /></EnableRules>
      <Actions>
        <JavaScriptFunction FunctionName="old.Account.freigeben"
                            Library="$webresource:fab_/js/account.js" />
      </Actions>
    </CommandDefinition>
  </CommandDefinitions>
</RibbonDiffXml>

CommandDefinitions describe what happens. A so-called command bundles the action to run with rules for when it is available. The action is usually a "JavaScriptFunction" with a library and a function name.

EnableRules and DisplayRules are those rules. DisplayRules control visibility, for example showing a button only on certain forms. EnableRules control activation, for example only for selected records or depending on the result of a JavaScript function. In grown systems, commands like to point to rules whose functions no longer exist. The button then stays permanently active or grayed out, and nobody knows why anymore.

Looking at the mapping

For an inventory, the most important question is not how many buttons there are but which JavaScript functions hang on them. Besides form events, the ribbon is the second place where web resources are actually used. Whoever checks whether a script is still needed has to search both places. A script that is not bound in any form can still hang on a button.

For troubleshooting on a live system there is a built-in tool that is surprisingly unknown: the Command Checker, enabled through the URL parameter ribbondebug. It shows per button which rules were evaluated and where a display failed. Looking for ribbon problems without it means searching blindfolded.

And modern commanding?

For some years now there has been the modern command designer with Power Fx formulas. Its commands do not land in the RibbonDiffXml but as a component type of their own in the export, as app actions. In a solution with a long history you therefore often find both side by side: old ribbon customizations and new app actions that deal with the same command bar.

The direction for the future is clear: Microsoft builds on the new model. Existing ribbon XML keeps running, but every new customization there enlarges a stock that will have to move at some point anyway. New buttons belong in the new designer.