The AL developer environment is evolving with frequent updates. To stay up to date on the latest information and announcements, follow us on the Dynamics NAV Team Blog.
Rules and Guidelines for AL Code
This page defines the rules and guidelines to follow when writing AL code in an extension package for Dynamics 365 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 are not resolved must include an explanation and justification for the error.
- Code uses encryption key functions such as IMPORTENCRYPTIONKEY, EXPORTENCRYPTIONKEY, CREATEENCRYPTIONKEY, and DELETEENCRYPTIONKEY. (It is fine to use the ENCRYPT and DECRYPT functions.)
- Code uses ASSERTERROR.
- External data connections do not properly handle sensitive data.
- Code uses
AutoIncrement = Yesfor a table field that may be used in a Foreign Key relationship. Recommend code comment that the table field will not be used in a Foreign Key relationship to pass validation.
- It does not encrypt sensitive table data. (i.e. credit card info, passwords, etc.).
- Temporary files are not cleaned up after use.
- Code uses codeunits that require printers to be selected.
- Code uses a specific time zone or locale.
To help you save time, we‘re sharing a list of the top 15 common pitfalls that regularly lead to app validation failures.
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.
DataClassification missing or set incorrectly
Due to GDPR requirements, 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.
Required translation files missing
There are many countries today that where Business Central is available, and that you can support as well with your app. For specifying additional 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, 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.
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.
For your app to be a good citizen in Business Central, permission errors must not appear unless it is a necessary reason for showing the error.
It is acceptable to throw an error to a user that does not have your permission set marked and tries to access your page object. It is not 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 is not trying to access your app's functionality.
Missing application area tagging
Tag in which part your app participates. Pages, controls, actions, and fields will not appear in Business Central if the Application Area property has not been set.
Usage Category not set
Due to their performance impact, OnBeforeCompanyOpen and OnAfterCompanyOpen cannot be used. For more information, see Replacing OnBeforeCompanyOpen and OnAfterCompanyOpen.
Make sure that your app can be upgraded properly. For more information, see Upgrading extensions.
Do not insert into the Profile table. Use the Profile object instead.
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.
You tested your app on an obsolete 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.
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.
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 cannot validate your app successfully. For more information, see User Scenario Documentation.
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 App Source. For example, your app cannot be published to a production tenant if the target value is set to Internal. It must be set to Extension. For information, see JSON Files.
Send feedback about: