Zum Inhalt

Code Analyzers

AL Compiler Diagnostic

Fehler, Warnungen oder Infos, welche als AL* gekennzeichnet werden, kommen vom AL Compiler und sind standardmäßig in der AL Language Extension vorhanden.1 Diese sind automatisch aktiv und gelten immer.

CodeCop

Der CodeCop ist der standard Code Analyzer von Microsoft, welcher die offiziellen AL Coding Richtlinien von AL vorgibt.2 Die Richtlinien werden mit dem Präfix AA gekennzeichnet. Beispiel: AA0001.

UICop

Der UICop ist ein Code Analyzer von Microsoft, welcher Richtlinien für Anpassungen im Web Client vorgibt.3 Die Richtlinien werden mit dem Präfix AW gekennzeichnet. Beispiel: AW0001.

PerTenantExtensionCop

Der PerTenantExtensionCop ist ein Code Analyzer von Microsoft, welcher Richtlinien für Extensions vorgibt, welche auf einzelnen Mandanten installiert werden.4 Die Richtlinien werden mit dem Präfix PTE gekennzeichnet. Beispiel: PTE0001.

AppSourceCop

Der AppSourceCop ist ein Code Analyzer von Microsoft, welcher Richtlinien für Extensions vorgibt, welche im AppSource veröffentlicht werden.5 Die Richtlinien werden mit dem Präfix AS gekennzeichnet. Beispiel: AS0001.

LinterCop (Abgekündigt)

Der LinterCop wird nicht mehr weiterentwickelt und wird im Oktober 2026 eingestellt. Weitere Entwicklungen wurden in die ALCops übernommen. Die Migration muss von einer Person, welche Zuständig für das Projekt-Repository ist, einmal durchgeführt werden. Für eine Migration auf die ALCops gibt es eine Anleitung und ein PowerShell Skript, welche von ALCops zur Verfügung gestellt wird, zudem muss die ALCops VS Code Extension installiert werden:

Folgende Schritte müssen für die Migration erledigt werden:

  1. ruleset.json in den .vscode Ordner im Projekt hinterlegen. Mehr Information zur ruleset.json gibt es auf dieser Seite: RuleSet

  2. Die .gitignore Datei muss wie folgt angepasst werden, damit die ruleset.json auch im Repository verfolgt wird:

    .gitignore Anpassungen

  3. alcops.json im Projektordner hinterlegen und falls vorhanden die LinterCop.json entfernen. Mehr Informationen zur alcops.json gibt es auf dieser Seite: ALCops

  4. In der app.json die "suppressWarnings" entfernen.

  5. In der Workspace Datei folgende Änderungen durchführen:

    2.1. Den LinterCop aus den al.codeAnalyzers entfernen und die neuen ALCops hinterlegen

    Neue Code Analyzers

    2.2. Die Eigenschaft "al.ruleSetPath": "./.vscode/ruleset.json" hinzufügen. Sie verweist auf die RuleSet Datei

  6. Das PowerShell Skript einmal für das Repository laufen lassen. Dadurch werden Pragmas auf die neuen Richtlinien-Codes migriert. Falls das Ausführen des Skripts nicht möglich ist, müsste die manuell durchgeführt werden

  7. Sollten nach der Migration Fehler auftreten, die vorher nicht da waren, dann müssen diese geprüft und behoben werden. Einige Richtlinien die im LinterCop nur als Warnung deklariert waren sind in den ALCops harte Fehlermeldungen. Die Projektleiter/-entwickler entscheiden, wie mit diesen Fällen umgegangen werden sollen.

ALCops

Die ALCops sind eine Sammlung an Code Analyzern, die durch die Gemeinschaft von AL-Entwicklern vorangetrieben wird.6 Stefan Maron, der Entwickler ds LinterCops, hat seine Zukünftige Entwicklung in die ALCops mit aufgenommen. Die ALCops-Extension bringt folgende Analyzer mit sich:

  • ApplicationCop AC
    • Richtlinien für die Anwendungskonventionen von Tabellen, Seiten, Enums, Labels und Berechtigungen
  • DocumentationCop DC
    • Richtlinien zur Prüfung von Kommentaren und XML-Dokumentationen
  • FormattingCop FC
    • Richtlinien für die Formatierung und Code-Struktur des AL Codes
  • LinterCop LC
    • Richtlinien für Qualitäts- und Komplexitätsprüfungen und Vorschläge für moderne AL Pattern
  • PlatformCop PC
    • Richtlinien zur Prüfung von Code der auf Plattform-Ebene technisch fehlerhaft, gefährlich oder leise ignoriert wird,
  • TestAutomationCop TA
    • Richtlinien für AL Test Code

Unterdrückte Richtlinien

Im folgenden werden Richtlinien aufgelistet welche in unseren Extensions standardmäßig unterdrückt werden. Einige Richtlinien zwangsweise zu Erfüllen würde keinen großen Mehrwert verursachen und stören eher bei der Entwicklung. Diese unterdrückten Richtlinien werden in einer ruleset.json festgehalten, die sich im Repository befinden sollte.

  • AA0205
    • Variables must be initialized before usage.
    • Variablen in AL haben immer einen Initial-Wert. Demnach ist eine Initialisierung nicht notwendig.
  • AA0210
    • Avoid non-indexed fields into filtering.
    • Auch Felder, welche keinen Key haben können gefiltert werden. Diese Regel ist nur eine Info.
  • AA0215
    • Follow the style guide about the best practices for naming.
    • Dateinamen ohne Affixe sind zulässig und sollten diese Regel nicht auslösen. Solange diese Bedingung erfüllt ist, bleibt die Regel deaktiviert.
  • AA0247
    • Use namespaces.
    • Da der Mehrwert von Namespaces noch nicht ausreichend geklärt und es noch einige offene Fragen dazu gibt, wird diese Richtlinie unterdrückt.
      • Wie sieht eine Migration von Suffix zu Namespace aus? Der Wechsel verursacht jede menge Breaking Changes
      • Wie sieht es mit Funktionen aus?
      • Wo ist der eigentliche Use-Case für Namespaces?
      • Das alle abhängigen Apps auch Namespaces verwenden müssen gibt die Dokumentation nicht her, das ist ein Mythos.
  • AS0092
    • The app.json file must specify an Azure Application Insights resource.
    • Telemetrie wird nicht für jede AppSource App verwendet.
  • AC0013
    • DropDown and Brick fieldgroups must be defined
    • Für die meisten Objekte sind Feldgruppen nicht erforderlich. Bei Einrichtungs-Tabellen sind Feldgruppen nicht sinnvoll, da diese in der Regel nicht im Zusammenhang mit einer Dropdown-Liste verwendet werden.
  • AC0015
    • ToolTip should start with Specifies
    • Tooltips können auch mit anderen Begriffen beginnen. Diese Regel stammt aus den Richtlinien von Microsoft für das Benutzerunterstützungsmodell.
  • AC0026
    • Explicitly set AllowInCustomizations for excluded fields
    • Der Standardwert ist in den meisten Fällen ausreichend und muss nicht explizit festgelegt werden.
  • AC0030
    • Use return value for better error handling
    • Der Aufruf von .Get() ohne Überprüfung des Rückgabewerts ist bei Einrichtungs-Tabellen gängige Praxis. Wenn diese Tabellen nicht vorhanden sind, sollte ein Fehler ausgelöst werden.

  • AC0031

    • Table data access requires explicit object permissions
    • Diese Regel gilt auch für Tabellen- und Seitenerweiterungen, die keine „Permissions“-Eigenschaft besitzen, sodass die Regel dort nicht erfüllt werden kann. Intern wurde beschlossen, diese Regel vollständig zu unterdrücken.

    Info

    Wenn indirekte Berechtigungen erteilt werden, die sich nicht im Code widerspiegeln, kann dies dennoch zu einem Berechtigungsfehler führen.

  • DC0007

    • Public objects must include XML documentation comments
    • Eine XML-Dokumentation zu öffentlichen Objekten und Mitgliedern ist nicht zwingend erforderlich.
  • PC0030
    • Use partial records on read operation
    • Diese Regel wird bei Schreibvorgängen in der Datenbank nicht korrekt angewendet, was zu unerwünschten JIT-Ladevorgängen führt.
  • PC0037
    • Use Validate() instead of direct field assignment
    • Validierungsprüfungen sind nicht immer erforderlich und können in bestimmten Fällen bedenkenlos weggelassen werden.
  • PC0038
    • Not all code paths return a value
    • Nicht alle Codepfade müssen einen Wert zurückgeben, da es im AL-Code einen Standardrückgabewert gibt.
  • LC0010
    • Cyclomatic Complexity threshold exceeded
    • Die Zyklomatische Komplexität ist keine gute Metrik, um Code Komplexität zu prüfen. Sie kann Sinnvoll für Testfälle bzw. automatisierte Tests sein. Diese Prüfung wird durch LC0090 besser behandelt.
  • LC0098
    • Event subscriber name does not match the configured template
    • Da in der Codebasis unterschiedliche Namenskonventionen verwendet werden, wird diese Regel unterdrückt.
  • LC0099
    • Event subscriber parameter is not referenced
    • Nicht referenzierte Parameter von Ereignisabonnenten sind zulässig und müssen nicht entfernt werden.

Einschränkungen

  • LC0090
    • Cognitive Complexity threshold exceeded
      • Es wird eine alcops.json im Repository Template bzw. Projekt hinterlegt. In dieser wird die Grenze auf 20 anstatt 15 angehoben.
      • Nähere Informationen zur alcops.json gibt es auf dieser Seite: ALCops

Prüfung für alle Objekte in einem Projekt aktivieren

Standardmäßig wird in einem Projekt nur die Datei nach den Code Analyzer Richtlinien geprüft, die gerade geöffnet ist. Wenn man sich alle auftauchenden Probleme für ein Projekt ansehen will muss man die Prüfung ändern. Dies geht über die VS Code Einstellung al.backgroundCodeAnalysis:

ALCops Background Analysis

Wenn diese Einstellung auf Project gestellt wird, dann laufen die Richtlinienprüfungen über alle Objekte im Projekt. Für eine Prüfung des ganzen Projekts ist die Einstellung sehr gut geeignet. Das sollte allerdings nicht standardmäßig aktiviert und auch nicht in das Repository eingecheckt werden, da dies die Performance der Entwicklungsumgebung stark beeinflusst.

Für Per Tenant Apps sollten folgende Cops verwendet werden:

  • CodeCop
  • UICop
  • PerTenantExtensionCop
  • Optional: ALCops
    • ApplicationCop
    • DocumentationCop
    • FormattingCop
    • LinterCop
    • PlatformCop

In Produkt Apps sollten folgende Cops verwendet werden:

  • CodeCop
  • UICop
  • AppSourceCop
  • Optional: ALCops
    • ApplicationCop
    • DocumentationCop
    • FormattingCop
    • LinterCop
    • PlatformCop

  1. https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/diagnostics/diagnostics-overview ↩

  2. https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/analyzers/codecop ↩

  3. https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/analyzers/uicop ↩

  4. https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/analyzers/pertenantextensioncop ↩

  5. https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/analyzers/appsourcecop ↩

  6. https://alcops.dev/docs/analyzers ↩