Edit

Share via

Rules and guidelines for AL code

  • Article

This page defines the rules and guidelines to follow when writing AL code in an extension package for Business Central. The rules and guidelines are grouped according to two importance levels: critical errors that must be resolved, and important errors that should be resolved. Errors that aren't resolved must include an explanation and justification for the error.

Critical errors

  • Code uses encryption key functions such as ImportEncryptionKey, ExportEncryptionKey, CreateEncryptionKey, and DeleteEncryptionKey. (It's fine to use the Encrypt and Decrypt methods.)
  • Code uses AssertError.
  • External data connections don't properly handle sensitive data.
  • It doesn't encrypt sensitive table data. (that is, credit card info, passwords, etc.).

Important errors

  • Temporary files aren't cleaned up after use.
  • Code uses codeunits that require printers to be selected.
  • Code uses a specific time zone or locale.

Common pitfalls

To help you save time, we're sharing a list of the top 15 common pitfalls that regularly lead to app validation failures.

  1. Prefix/Suffix missing

    One of the app requirements is for you to reserve a prefix/suffix for your app. This is needed to ensure a healthy app ecosystem by avoiding collision amongst apps. This common failure occurs due to not setting your prefix/suffix in some or all required places. For more information, see Benefits and Guidelines for using a Prefix or Suffix.

  2. DataClassification missing or set incorrectly

    Due to the requirements of privacy laws and regulations, fields of field class Normal must use the DataClassification property, and its value must be different from ToBeClassified. This applies to fields in tables and table extensions. Use the AppSourceCop tool for detecting this.

  3. Required translation files missing

    There are many country/regions today that where Dynamics 365 Business Central is available, and that you can support as well with your app. For specifying extra languages, we no longer support Caption ML. You must use xliff translation files instead. For more information, see Working with Translation Files.
    Microsoft provides a free translation tool that you can access from https://lcs.dynamics.com. To support a specific country/region, you must include a translation file per for each language code. For example, to support Switzerland, you must provide fr-CH, de-CH, and it-CH.

  4. Missing permission sets

    Your app must provide one or more permission sets so that users can use your app's functionality. Your app must never require the SUPER permission set.

  5. Permission errors

    For your app to be a good citizen in Dynamics 365 Business Central, permission errors must not appear unless it's a necessary reason for showing the error.
    It's acceptable to throw an error to a user that does not have your permission set marked and tries to access your page object. It isn't acceptable to throw an error to that same user trying to access Business Central pages in the base application, or to throw an error to a user who isn't trying to access your app's functionality.

  6. Missing application area tagging

    Tag in which part your app participates. Pages, controls, actions, and fields won't appear in Dynamics 365 Business Central if the Application Area property hasn't been set.

  7. Usage Category not set

    You enable a page or report to be available through search in Dynamics 365 Business Central by using the UsageCategory property. For more information, see Using Tell Me to Find Features and Information.

  8. OnCompany procedure

    Due to their performance impact, OnBeforeCompanyOpen and OnAfterCompanyOpen can't be used. For more information, see Replacing OnBeforeCompanyOpen and OnAfterCompanyOpen.

  9. Upgrade procedures

    Make sure that your app can be upgraded properly. For more information, see Upgrading extensions.

  10. Profiles

    Don't insert into the Profile table. Use the Profile object instead.

  11. App file not properly code-signed

    Your app file must be digitally signed with a certificate from a third-party certification authority trusted by Windows.

  12. You tested your app on an obsolete Dynamics 365 Business Central version (or never even tested it)

    Make sure that your app is properly tested on the correct version. For more information, see Current Build - Developing for Dynamics 365 Business Central on the Collaborate site.

  13. You tested using SUPER permissions

    You tested your app, but your user had SUPER permissions. This can hide critical errors. You must test with a user that doesn't have the SUPER permissions. The user must have the ESSENTIAL license. For more information, see Testing your Extension.

  14. User scenario document unclear

    Our validation team is testing your app functionality manually, so we need to be able to understand the core functionality of your app. If your user scenario document is missing important details that are needed for us to properly walk through your app's setup and usage scenarios, we can't validate your app successfully. For more information, see User Scenario Documentation.

  15. The .json file is incorrect

    There are many values in the app.json file that may not be mandatory to compile your app, but are mandatory for your app to be in AppSource. For example, your app can't be published to a production tenant if the target value is set to OnPrem. It must be set to Cloud. For information, see JSON Files.

Best practices for AL code
Checklist for submitting your app