AL Auto Namespace

Automatically maintain AL namespaces and missing using directives in Visual Studio Code projects for Dynamics 365 Business Central.

The extension adds a file namespace when one is missing and resolves supported AL object references against downloaded symbol packages. It reads the AL source rather than relying on compiler diagnostic codes or error-message text.

Features

• Add a namespace to an AL file on save when the file does not already declare one, based on the configured prefix and the project's app.json name.
• Add missing using directives for supported object references from Microsoft Base Application, Microsoft Business Foundation, and direct dependencies declared in the active project's app.json.
• Match references by object kind and exact object name, and avoid duplicate using directives.
• Skip references when their namespace cannot be identified unambiguously.
• Format the header with one blank line between namespace and the using block, and one blank line between the using block and the AL object.
• Run missing-using resolution manually from the Command Palette or enable it on save.

Example

Before:

namespace Example.Inventory;

codeunit 50100 "Item Example"
{
    var
        Item: Record Item;
        NoSeries: Codeunit "No. Series";
}

After resolving references against the downloaded symbol packages:

namespace Example.Inventory;

using Microsoft.Foundation.NoSeries;
using Microsoft.Inventory.Item;

codeunit 50100 "Item Example"
{
    var
        Item: Record Item;
        NoSeries: Codeunit "No. Series";
}

The namespaces actually inserted come from the symbol packages selected for your project. The example file namespace is illustrative.

The same mechanism can resolve an object from another extension when that extension is a direct dependency in app.json and its matching symbol package is available and readable. You do not need to hard-code the extension's name in AL Auto Namespace.

Getting started

1. Open a local AL project with an app.json file.
2. Download the symbols needed by that project, including the symbol packages for any declared dependencies you want the extension to resolve.
3. Configure the extension's namespace prefix for your project's naming convention.
4. Save an AL file, or run AL Auto Namespace: Add Missing Standard Usings from the Command Palette.

The extension looks in the project's configured al.packageCachePath directories. If a referenced dependency has not been downloaded there, the extension cannot resolve its namespace.

Settings

• alAutoNamespace.enabled: Controls the extension's automatic behavior.
• alAutoNamespace.addStandardUsingsOnSave: Controls automatic insertion of missing usings after saving.
• Namespace prefix: Set the prefix used for generated file namespaces in the extension's settings. Check the extension's package.json for the exact setting key.

Supported AL references

The source scanner recognizes these forms:

• Typed declarations such as Record Item, Page "Item Card", and Codeunit "No. Series".
• Qualified references such as Page::"Item Card" and Codeunit::"Sales-Post".
• Targets of table, page, report, and enum extensions using extends.
• SourceTable, LookupPageId, and DrillDownPageId properties.
• TableRelation table targets, including supported conditional branches.
• CalcFormula destination tables in Exist, Count, Sum, Average, Min, Max, and Lookup formulas.
• Tables in report and query dataitem(Name; Table) declarations and XMLport tableelement(Name; Table) declarations.
• Pages in part(Name; Page) declarations.
• Page, report, codeunit, and query references in RunObject properties.

The scanner skips comments and AL text literals. It recognizes the listed constructs rather than parsing the entire AL language.

How dependency resolution works

1. The extension locates the active project's app.json and the configured AL symbol cache directories.
2. It selects Base Application and a compatible Business Foundation package from the available versions. For other extensions, it considers direct dependencies listed in app.json.
3. It reads each candidate .app package's embedded NavxManifest.xml to compare its app ID, name, publisher, and version with the declared dependency. The filename is not used as the sole identity check.
4. It selects the highest cached version satisfying the dependency's declared minimum version. If multiple candidates have the same highest version, it skips that dependency rather than choosing arbitrarily.
5. It reads SymbolReference.json from selected packages, caches successfully indexed packages, and matches source references by object kind and exact name.
6. It adds a using only when the match yields one namespace that is not already the file's namespace or an existing using.

Unrelated .app files in the cache are not treated as dependencies merely because they are present. A package that cannot be read is skipped without preventing the working Base Application usings from being added.

Limitations and troubleshooting

• Direct dependencies only: External packages must be declared in the active project's app.json. This implementation does not automatically resolve arbitrary cached apps or every transitive dependency.
• Downloaded symbols required: A declared dependency without a matching cached .app cannot provide a namespace. Check al.packageCachePath and download the project's symbols.
• Unreadable symbol packages: If a selected package has a missing or unparsable SymbolReference.json, the extension skips it and logs a warning. Other readable packages can still be used.
• Ambiguous object names: If the same object kind and name resolve to different namespaces, no using is guessed. Review the reference manually.
• Supported syntax only: AL constructs not listed above may need a manually added using.
• No removal of unused usings: The extension adds missing directives but does not remove existing ones.
• Version selection: The highest cached eligible version is not necessarily the exact version used by the AL compiler or connected environment. Verify the selected packages when a project has multiple versions in its cache.
• Project-local objects: The index covers selected symbol packages, not every object defined in the active project's source files. Review a proposed import if an object of the same kind and name also exists locally.