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

  • 20 minutes

After you become familiar with Visual Studio Code, AL, and Business Central object types, configure Visual Studio Code for development.

Visual Studio Code is designed for many small, related projects instead of a single large project. Because the base application isn't divided into smaller modules or components, we recommend the following performance optimizations.

Open your settings.json file in the project (or global settings if you prefer that). To do so, press Ctrl+Shift+P, and then choose Preferences: Open Settings (UI) for workspace settings, or Preferences: Open User Settings for user settings. Under Extensions > AL Language extension configuration, you can view the available AL Language extension settings. If a setting isn't available through the UI, you can edit it directly in the settings.json file. Set the following options.

  • 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 extends the compiler and analyzes your code during 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 Marketplace. 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. Under Extensions, go to AL Language extension configuration. When you scroll down, you find the Code Analyzers section, where you can select Edit in settings.json.

  3. Set the al.enableCodeAnalysis setting in the settings file 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.

The selected analyzers now run on the project. Add code that violates the following rule to see how code analysis works. Violate 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. Hover over the underlined code to view the warning message. You can also view the list of issues by selecting the View tab of Visual Studio Code and selecting the Problems option.

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

By default, code analysis runs in the background. For large projects, you can limit or disable background analysis to improve performance. 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 al.backgroundCodeAnalysis setting. The setting accepts the following values.

    • File (the default) - analysis runs only on the file that is active in the editor.

    • Project - analysis runs on the entire project, with a significant performance penalty. This value is only advised for high-performance machines.

    • None - background analysis is turned off, so that it only runs during a full build.

If code analysis still takes too long, you can turn on the al.outputAnalyzerStatistics setting to get an overview of the runtime of each rule, and then switch off long-running rules in the ruleset of your project. For more information, see Code analysis performance configuration.

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, a custom ruleset file controls how code analysis reports issues. Different settings affect rule behavior. To enable IntelliSense in Visual Studio Code, name ruleset files using 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

  • enableExternalRulesets

    • Controls whether a ruleset in an external location, which is pointed to by the al.ruleSetPath setting, is used.

    • This setting is not mandatory.

    • Type: Boolean

  • 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. When you save a new ruleset path entry, the change applies automatically to all projects that use 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 apply changes to a ruleset file, use one of the following methods:

  • 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.