Learn how to properly set up code cop tools for app validation

  • 20 minutes

After you are more familiar with the development environment, Visual Studio Code, and the programming language (AL) and different object types, it's time to properly set up Visual Studio Code.

Visual Studio Code is built to handle many smaller, dependent projects, and not one large project. However, as the base application isn't split into modules or components that allow managing code in smaller projects, we recommend the following performance optimizations.

Open your settings .json file in the project (or global settings if you prefer that) pressing Ctrl+P. Set the following options in the file.

  • al.enableCodeAnalysis: false to remove code analysis.

  • al.enableCodeActions: false

  • editor.codeLens: false to remove code lens in Visual Studio Code.

  • Add the build folder to the exclusion list for Windows Defender.

Code Analyzer tools

A code analyzer is a library that builds on the compiler's functionality to offer enhanced analysis of the syntax and semantics of your code at build time. The AL Language extension for Visual Studio Code contains four analyzers.

CodeCop

CodeCop is an analyzer that enforces the official AL Coding Guidelines. For more information about the CodeCop rules, see CodeCop Analyzer Rules.

PerTenantExtensionCop

PerTenantExtensionCop is an analyzer that enforces rules that must be respected by extensions that are meant to be installed for individual tenants. For more information about the PerTenantExtensionCop rules, see PerTenantExtensionCop Analyzer Rules.

AppSourceCop

AppSourceCop is an analyzer that enforces rules that must be respected by extensions meant to be published to Microsoft AppSource. For additional information about the AppSourceCop rules, see AppSourceCop Analyzer rules.

UICop

UICOP is an analyzer that enforces rules that must be respected by extensions that are meant to customize the Web Client. For more information about the UserInterfaceCop rules, see UICop Analyzer Rules.

Using the Code Analysis Tool

Follow the steps below to create a basic project in AL.

  1. Press Alt + A, and then Alt + L to create a new project.

  2. Open the Command Palette (Ctrl+Shift+P) and select either User Settings or Workspace Settings.

  3. Copy the setting al.enableCodeAnalysis to the settings file, and set it to true; al.enableCodeAnalysis: true.

  4. Copy the setting al.codeanalyzers to the settings file, and then use Ctrl+Space to pick from the available code analyzers. Separate the list of code analyzers with commas.

At this point, the selected analyzers will be run on your project. You can add some code to the project that can be used to demonstrate a violation of the AA0001 "There must be exactly one space character on each side of a binary operator such as := + - AND OR =." code analysis rule.

The code analysis tools will run in the background. You'll see the faulty expression underlined and the warning that there must be exactly one space character on each side of an operator. This warning message is displayed if you mouse over the underlined code. You can also view the list of issues by selecting the View tab of Visual Studio Code and selecting the Problems option.

Using the Ctrl+Shift+B shortcut to build your project will run the code analysis tools on the entire project, and the detected issues will be displayed in the Output window of Visual Studio Code.

To improve performance when running code analysis on large projects, you can switch off running code analysis in the background. To do so, follow these steps.

  1. open the Command Palette (Ctrl+Shift+P) and select either User Settings or Workspace Settings.

  2. Specify the setting al.backgroundCodeAnalysis: false.

Creating and customizing a ruleset

To create and customize a ruleset of your own, follow these steps.

  1. On the File tab in Visual Studio Code, select New File.

  2. Save the empty file with a name, for example <name>.ruleset.json and make a note of the file path.

  3. Add the following code to the <name>.ruleset.json file:

    {
    "name": "My Custom ruleset",
    "rules": [
        {
        "id": "AA0001",
        "action": "None"
        }
    ]
}

  4. In your project settings, set al.ruleSetPath to the path of the <name>.ruleset.json file, relative to the project root.

You can use the truleset and trule snippets provided by the AL Language extension to create your ruleset. The ruleset will be applied to all the analyzers enabled for the current project.

In an AL project, you can use a custom ruleset file to specify how code analysis will report the issues it encounters. Different settings can affect how rules are applied and each ruleset file name must follow the pattern <name>.ruleset.json to benefit from IntelliSense in Visual Studio Code.

The following list describes the schema of a ruleset object:

  • Name

    • The name of the ruleset.

    • This setting is mandatory.

    • Type: String

  • Description

    • The description of the ruleset. You can use this description to document the purpose of the ruleset.

    • This setting is not mandatory.

    • Type: String

  • generalAction

    • The action to apply to all the diagnostics that have rules defined in this file, or in other files that have a Default action specified, and to all the diagnostics generated by the current set of analyzers that don't have a rule defined. If an included file has a stricter generalAction, that one will be used.

    • This setting is not mandatory.

    • Type: Error | Warning | Info | Hidden

  • includedRuleSets

    • List of external ruleset files to include in the current ruleset. The order in which the files are processed is undefined.

    • This setting is not mandatory.

    • Type: Array of IncludedRuleSet

  • Rules

    • Collection of rules to apply to diagnostics generated by analyzers.

    • This setting is not mandatory.

    • Type: Array of Rule

An IncludedRuleSet is a complex JSON object that defines the inclusion of an external ruleset file in the current ruleset, and has the following properties.

  • Path - The path to the included file. For includes specified in the file to which the al.ruleSetPath is set, the path can be absolute or relative to the project folder. For files included from the root ruleset file, the path is relative to the file. Adding an entry to the ruleset path and saving it will automatically be applied to all projects that are using the ruleset.

  • Action The action to apply for all the diagnostics that have an action specified in the included ruleset that is different from None and Hidden.

A Rule is a complex JSON object that specifies how you can process a specific diagnostic. A Rule object has the following properties.

  • ID - The string that uniquely identifies a diagnostic.

  • Action - The action to apply if the diagnostic is emitted. There can't be two rules with the same ID and different actions in the same rule file.

The following example shows a ruleset that sets the severity of rule (AA0001 : There must be exactly one space character on each side of a binary operator such as := + - AND OR =). provided by the CodeCop analyzer set to Error.

{
    "name": "Company ruleset",
    "description": "These rules must be respected by all the AL code written within the company.",
    "rules": [
        {
            "id": "AA0001",
            "action": "Error",
            "justification": "This diagnostic helps to improve readability. It must be respected in all cases."
        }
    ]
}

The following example shows a project-specific ruleset that extends a company-wide ruleset contained in the file company.ruleset.json, and sets the severity of the rule (AA0005 : Only use BEGIN..END) to enclose compound statements. provided by the CodeCop analyzer set to Info.

{
    "name": "Personal Project ruleset",
    "description": "A list of project specific rules",
    "includedRuleSets": [
        {
            "action": "Default",
            "path": "./company.ruleset.json"
        }
    ],
    "rules": [
        {
            "id": "AA0005",
            "action": "Info",
            "justification": "For this specific project, this diagnostic should be informational."
        }
    ]
}

Limitations

Changing the contents of the ruleset file will not be detected by the AL Language extension. To see the effects of changing the ruleset file, you can try any of the following actions:

  • Reload the window.

  • In the project settings, change the al.ruleSetPath setting to an invalid path.

  • Save the settings file, change back the setting, and save it.