Development Coding Rules and Naming Conventions for Microsoft AL
Hi guys, in this short post i want to talk about “Development Coding Rules and Naming Conventions for Microsoft AL Language Extension”; previously i already dealt with this topic in relation to C/AL, now I try to do it for Microsoft AL.
For the development on Al, plan rules come up both for the management of the object names and for the development rules. The “Ready-to-go” program prepares developers to create certified apps so they can be published on App Source. We will now see how to retrieve information from multiple sources available to operate as correctly as possible according to the rules existing to date; as said the sources are many, I will try to list a good part of them.
Below a short list of documents\pages\links\videos about this topic (ALL Documents are available on Microsoft Docs)
#0 – The “Ready-to go” Program – Start from here!
The “Ready to Go” program is designed to support you in the journey of bringing offerings to market. The program contains learning, coaching, and tooling. The “Ready to Go” learning catalog is an extensive collection of materials for Dynamics 365 Business Central, including training resources, white papers, and tools for both app developers (ISVs) as well as resellers (VARs). It is designed for marketeers, business decision makers, sales and pre-sales roles, architects, consultants, and developers.
#1 – 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.
ALL Topics
- Critical errors (ex: Code uses ASSERTERROR)
- Important errors (ex: Temporary files are not cleaned up after use)
- Common pitfalls
(ex: Prefix/Suffix missing, Required translation files missing, Missing permission sets, Permission errors, Missing application area tagging, Usage Category not set, OnCompany procedure, Upgrade procedures, Profiles, App file not properly code signed, User scenario document unclear, The .json file is incorrect etc)
https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/compliance/apptest-overview
#2 – Best Practices for AL
This page defines some of the best practices to follow when writing AL code for Dynamics 365 Business Central. These best practices are additional to rules and guidelines that are caught during compilation of AL code. We recommend following these best practices when developing extensions in AL to ensure consistency and discoverability on file, object, and method naming, as well as better readability of written code.
Pre-requirement (from old C/AL Coding Guidelines)
https://community.dynamics.com/nav/w/designpatterns/156.3-cal-coding-guidelines
ALL Topics
- Extensions Structure
- File naming
- Examples of file naming
- Formatting
- Line length
- Object naming
- File structure
- Referencing
- Variable naming
- Method declaration
- Calling methods
- Type definition (colon)
File naming notation:
| Full objects | Extensions |
|---|---|
| <Type><Id>.<ObjectName>.al | <Type><BaseId>-Ext<ObjectId>.<ObjectName>.al |
Object Abbreviation Rules
Examples of file naming
The following table illustrates how the file naming should look
| Object name | File name |
|---|---|
| codeunit 1000 “Job Calculate WIP” | Cod1000.JobCalculateWIP.al |
| page 21 “Customer Card” | Pag21.CustomerCard.al |
| page 1234 “MyPag” extends “Customer Card” | Pag21-Ext1234.MyPag.al |
Object naming
Object names are prefixed. They start with the feature/group name, followed by the logical name as in these
Two examples:
- Intrastat extension validation codeunit for Denmark
- codeunit 123 “IntrastatDK Validation”
Detailed MAP is also available on My GitHub page
https://github.com/rstefanetti/AL-Samples/edit/AL-CodingRules/CodingRules.md
#3 – Benefits and Guidelines for using a Prefix or Suffix
In your extension, the name of each new application object (table, page, codeunit), must contain a prefix or suffix. This rule applies to all objects. You can use the Caption values for what you decide to display to the user. When you modify a core Dynamics 365 Business Central Object using a Table Extension or Page Extension (report extensions is not available to date), the prefix/suffix must be defined at the control/field/action/group level.
Genaral Rules
- The prefix/suffix must be at least 3 characters
- The object/field name must start or end with the prefix/suffix
- If a conflict arises, the one who registered the prefix/suffix always wins
- For your own pages/tables/codeunits, you must set the prefix/suffix at the top object level
- For pages/tables in the base application of Business Central that you extend, you must set the prefix/suffix at the top object level
- For pages/tables of Business Central in the base application that you extend, you must also set at the control/field/action level
Examples of acceptable prefix/suffix:
No Delimiter
- FABSalespersonCode
- SalespersonCodeFAB
Space
- “FAB Salesperson Code”
- “Salesperson Code FAB”
Underscore
- FAB_Salesperson_Code
- Salesperson_Code_FAB
#4 – The “AppScourceCop Tool”
Use the AppSourceCop tool to find all missing prefixes and/or suffixes. Configuration options for this tool can be found here https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-using-code-analysis-tool The Rules section explains the different checks the cop will do. For prefix/suffix detection, refer to the Configuration section. It explains how to set your prefix in the AppSourceCop.json file.
https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/analyzers/codecop
#5 – Technical Validation Checklist
The following is a checklist of all requirements that you must meet before submitting an extension for validation. If you do not meet these mandatory requirements, your extension will fail validation.
Enabling Code Analysis
- Press Alt + A, Alt + L to create a new project.
- Open the Command Palette Ctrl+Shift+P and choose either User Settings or Workspace Settings.
- Copy the setting al.enableCodeAnalysis to the settings file and set it to true: “al.enableCodeAnalysis“: true.
Adding your own code to the project ex:
pageextension 50100 CustomerListExt extends “Customer List”
{
trigger OnOpenPage();
var
result: Integer;
begin
// The following line will trigger the warning
// AA0001 “There must be exactly one space character on each side
// of a binary operator such as := + – AND OR =.”
result := 2+2;
Message(‘2 + 2 = ‘ + Format(result));
end;
}
Viewing the results of the code analysis
table of rules
https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/analyzers/codecop
#6 – Business Central Courses
Best Practices in Visual Studio Code Development for Dynamics 365 Business Central
You are developing your IP for Dynamics 365 Business Central. Discover some industry best practices and tips and tricks to enhance your development expert.
- Migrate Dynamics NAV C/AL Code to Visual Studio Code AL for Dynamics 365 Business Central
- Develop SaaS User Experiences for Dynamics 365 Business Central
- Cloud Solution Provider for Developers
- Source Code Management for Dynamics 365 Business Central Apps
#7 – AL Coding Rules RECAP PAGE (on my GitHub page)
https://github.com/rstefanetti/AL-Samples/blob/AL-CodingRules/CodingRules.md
AL Formatter
The AL Language extension offers users the option to automatically format their source code. This capability increases the usability of the editor by allowing developers to instantly fix the indentation and formatting of their code. The auto-formatter analyzes the syntax tree of the AL code that you are formatting and, using rules developed based on the coding and style guidelines for AL, inserts and removes whitespace from key points in the document to make it more readable. The rules used by the auto-formatter cannot be configured by the user. This limitation is present to allow for a uniform style to be used throughout the community of AL developers.
My Old post about C/AL Coding Guidelines
“ALL About” C/AL Coding Guidelines
https://robertostefanettinavblog.com/2016/11/01/all-about-cal-coding-guidelines/
https://community.dynamics.com/nav/w/designpatterns/156.cal-coding-guidelines
Hi, it seems like a part of this post is deprecated since MS has updated the “Best practices for AL”
https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/compliance/apptest-bestpracticesforalcode
Currently the have changed the file naming structure from
..al,
.Ext.al
to
..al,
-Ext..al
To me now it seems harder to find files that are extending certain objects 🙁