Ribbon-XML in Dynamics 365 erklärt

Wer eine Schaltfläche in der Befehlsleiste anpasst erzeugt oder verändert die Ribbon-XML einer Lösung. Die Struktur stammt noch aus der Zeit als die Oberfläche tatsächlich ein Ribbon im Office-Stil war. Bis heute ist sie ein eher verwirrender Teil des Solution-Exports. Hier ein Überblick damit man beim ersten Kontakt nicht kapituliert.

Das Grundprinzip: Differenzen, keine Definitionen

Im Export steht pro Tabelle ein "RibbonDiffXml". Das Wort Diff ist wörtlich zu nehmen: Die Datei beschreibt nicht die ganze Befehlsleiste sondern nur die Abweichungen vom Standard. Eine neue Schaltfläche, eine ausgeblendete Standardschaltfläche, ein geändertes Label oder ein ausgetauschtes Symbol.

Deshalb lässt sich aus dem Export allein nie das vollständige Erscheinungsbild rekonstruieren. Man sieht lediglich was angepasst wurde, nicht aber was der Standard beisteuert.

Die drei Bausteine

CustomActions platzieren Elemente. Jede CustomAction hat eine "Location". Das ist eine lange, punktierte Adresse wie "Mscrm.Form.account.MainTab.Actions". Sie bestimmt wo in der Leiste etwas erscheint oder verschwindet. Diese Adressen sind der häufigste Fehlerort: Ein Tippfehler und die Schaltfläche taucht kommentarlos nicht auf.

So hängen die Teile zusammen, beispielsweise hier eine Schaltfläche auf dem Kontoformular:

<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 beschreiben was passiert. Ein so genannter Command bündelt die auszuführende Aktion mit Regeln wann er verfügbar ist. Die Aktion ist meist eine "JavaScriptFunction" mit Bibliothek und Funktionsname.

EnableRules und DisplayRules sind diese Regeln. DisplayRules steuern die Sichtbarkeit (wie etwa nur auf bestimmten Formularen anzeigen). EnableRules steuern die Aktivierung (wie z.B. etwa nur bei ausgewählten Datensätzen oder abhängig vom Ergebnis einer JavaScript-Funktion). In gewachsenen Systemen verweisen Commands gern auf Regeln deren Funktionen es nicht mehr gibt. Die Schaltfläche bleibt dann dauerhaft aktiv oder ausgegraut und niemand weiß mehr warum.

Der Blick auf die Zuordnung

Für eine Bestandsaufnahme ist die wichtigste Frage nicht wie viele Schaltflächen es gibt sondern welche JavaScript-Funktionen daran hängen. Das Ribbon ist neben den Formular-Ereignissen der zweite Ort an dem Web-Ressourcen tatsächlich benutzt werden. Wer prüft ob ein Skript noch gebraucht wird muss beide Orte absuchen. Ein Skript welches in keinem Formular gebunden ist kann immer noch an einer Schaltfläche hängen.

Für die Fehlersuche am lebenden Objekt gibt es ein eingebautes Werkzeug das erstaunlich unbekannt ist: den Command Checker, zuschaltbar über den URL-Parameter ribbondebug. Er zeigt pro Schaltfläche welche Regeln ausgewertet wurden und woran eine Anzeige scheiterte. Wer Ribbon-Probleme ohne ihn sucht, sucht mit verbundenen Augen.

Und das moderne Commanding?

Seit einigen Jahren gibt es den modernen Command-Designer mit Power-Fx-Formeln. Dessen Befehle landen nicht im RibbonDiffXml sondern als eigener Komponententyp im Export, als App Actions. In einer Lösung mit langer Geschichte findet man deshalb häufig beides nebeneinander: alte Ribbon-Anpassungen und neue App Actions die sich um dieselbe Befehlsleiste kümmern.

Für die Zukunft ist die Richtung klar; Microsoft baut auf dem neuen Modell auf. Bestehendes Ribbon-XML läuft weiter aber jede neue Anpassung dort vergrößert einen Bestand der irgendwann ohnehin wandern muss. Neue Schaltflächen gehören in den neuen Designer.