Like in all other languages, symbols represent references to a collection of standard objects, properties, and functions. They are a special extension file themselves with the typical .app naming convention and are used to maintain object reference consistency while compiling, and they also populate valid IntelliSense entries.

Symbols are typically stored inside the database in a BLOB field in JSON for each object record. It is worth mentioning that in multitenancy, the Object Metadata table is part of the application database, so in customer tenant databases there are no system symbols or metadata stored, only data.

With Dynamics 365 Business Central, symbols are already preloaded inside the application database, and these can be grouped into two classes:

• Standard symbols
• Extension symbols

Prior to the Fall 2019 update, standard application symbols were all generated by Microsoft through a special compilation of standard legacy objects using the CSIDE development environment. The same happened for the on-premises version: symbols were generated asynchronously, or could have been imported as a normal extension through PowerShell scripts.

Standard application symbols were stored in the Symbol Reference BLOB field in the Object Metadata table.

The following table shows us the standard symbols. Understanding what they are and their importance is vital for the successful compilation and deployment of any kind of extension prior to the Fall 2019 update:

• Application: Contains symbols for all the application objects described in the CSIDE object designer, except system tables in the 2000000004 to 2000000199 ID range and standard Test Toolkit objects. With an on-premises version or Docker-contained sandbox, if you're making changes to a standard legacy object, you must opt for (re)generating symbols through the CSIDE development environment, as described in the following blog post: Generate Symbols in a Modern Development environment with Microsoft Dynamics NAV 2018 (https://blogs.msdn.microsoft.com/nav/2018/01/16/generate-symbols-in-a-modern-development-environment-with-microsoft-dynamics-nav-2018/). With the upgraded on-premises version, symbols coming from earlier versions must be extracted from a standard on-premises database (or from the product DVD), imported in the upgrade database, and regenerated, as described in the following blog post: https://blogs.msdn.microsoft.com/nav/2018/02/02/import-symbols-in-new-or-upgrade-databases-with-microsoft-dynamics-nav-2018/.
• System: 
  • Contains symbols for system tables in the 2000000004 to 2000000199 ID range, and also virtual table definitions.
  • System and virtual table structures cannot be modified through extensions.
  • System and virtual table symbols cannot be regenerated.
  • For this reason, if you are developing extensions, they should never be considered for any changes within the CSIDE development environment.
• Test: Contains symbols for application Test Toolkit objects. Standard application Test Toolkit object symbols cannot be regenerated. Developers should create their own test objects. For this reason, in a modern development environment for SaaS deployment, they should never be considered for any changes within the CSIDE development environment.

Whenever you extend an application, you always need to have the appropriate symbols in place. You can achieve this in two ways:

• Connect to a sandbox environment, run the Command Palette (Ctrl + Shift + P), and type and select AL: Download Symbols.
• Download the required symbols from another place (such as the product DVD, for on-premises deployment) and store them in the defined symbol storage directory.

For on-premises deployment, you will find the System.app and Test.app symbols on the Dynamics 365 Business Central Spring 2019 product DVD in the following directory: ModernDevprogram filesMicrosoft Dynamics NAV140AL Development Environment. In the Dynamics 365 Business Central Fall 2019 DVD you will only find System.app in the following directory: ModernDevprogram filesMicrosoft Dynamics NAV150AL Development Environment. Since the Fall 2019 update, application and test symbols are no longer downloaded automatically by the AL Language runtime, and they no longer need to be stored inside the database, since all of the objects that belong to the application, including Test Toolkit ones, have been converted into AL objects. These AL objects are now part of standard extension packages. Extension packages contain symbols natively.

If you have a multiuser environment with developers that are working on the same staging tenant, you might think of downloading symbols through the Command Palette once and then setting a common path for storing the symbols for all users. In this way, it is possible to avoid downloading the same set of symbols every time, thereby increasing the development productivity.

The default symbol-storing path can be changed using one of the following shortcuts:

• From the Menu bar, go to File (Alt + F) | Preferences (P) | Settings (S) and then select AL Language settings.
• Use the settings shortcuts (Ctrl) and then select AL Language settings.

The parameter to change is Al: Package Cache Path, the default value of which is set to the relative path, ./.alpackages.

Alternatively, you could run the Command Palette (Ctrl + Shift + P), type and select Preferences: Configure language specific settings…, then choose AL. The settings.json file will open, and you can then add or change the values of the al.packageCachePath parameter. The following screenshot shows the AL settings symbol path when it has been changed to a storage location:

Later in this chapter, we will also discuss other AL Language configuration settings.

Together with system application extension, base application extension, and standard symbols, your extension might also depend on other custom or third-party extensions. These extensions, then, should emit symbols that you should be able to download from the application database when invoking AL: Download Symbols from the Command Palette.

Extension symbols are stored in the Symbols BLOB field in the NAV App table.

To specify that your extension has a dependency on another extension(s), you must populate the relevant JSON array parameter in the app.json file. This is what the app.json file parameter looks like for an extension that depends on two other apps:

  "dependencies": [
      {
          "appId":  "63ca2fa4-4f03-4f2b-a480-172fef340d3f",
          "publisher":  "Microsoft",
          "name":  "System Application",
          "version":  "15.0.0.0"
      },
      {
         "appId":  "437dbf0e-84ff-417a-965d-ed2bb9650972",
         "publisher":  "Microsoft",
         "name":  "Base Application",
         "version":  "15.0.0.0"
      },
      {
        "appId": "99ddd910-3aa8-4c3e-936c-be20edeaf777",
           "name": "Preferred Wine Basic"
            "publisher": "Tacconi Inc."
             "version": "1.0.0.0"
      },  
     {
        "appId": "77ddd910-3aa8-4c3e-936c-be20edeaf888",
        "name": "Preferred Wine Tools",
        "publisher": "Tacconi Inc.",
        "version": "2.1.0.0"
     }
   ],

The version parameter of the dependent extension(s) represents the lower bound for the compiler to accept the symbols. In other words, symbol versions of the dependent extension lower than the one reported are not considered valid for download or compile operations.