AL Auto Namespace

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

The extension builds a file's namespace from a configurable template (or the legacy prefix setting), scans supported AL object references, and resolves their namespaces from downloaded symbol packages. It does not rely on compiler diagnostic codes or error-message text.

Features

• Add a missing namespace when an AL file is saved.
• Configure namespace naming per project with alAutoNamespace.namespaceTemplate and the ${appName} placeholder.
• Retain the existing alAutoNamespace.prefix behavior when the template is empty.
• Add missing using directives from Microsoft Base Application, Business Foundation, System Application, and System symbol packages, as well as direct dependencies declared in the project's app.json.
• Match references by object kind and exact name; skip unavailable or ambiguous matches instead of guessing.
• Avoid duplicate using directives and keep one blank line on either side of the using block when adding usings.
• Process the active AL project with an explicit Command Palette command. Saving one file never starts a project-wide scan.

Example

With this project's settings:

{
    "alAutoNamespace.namespaceTemplate": "myPartner.PTE.${appName}"
}

and "name": "AppNameExample" in app.json, a file containing:

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

can become:

namespace myPartner.PTE.AppNameExample;

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

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

The using namespaces come from the symbol packages selected for the project. Other extensions can contribute usings when they are direct dependencies in app.json and their matching symbol packages are available and readable.

Getting started

1. Open a local AL project with an app.json file.
2. Download the project's symbols, including those for any direct dependencies whose objects you want resolved.
3. Configure alAutoNamespace.namespaceTemplate in the project's VS Code settings, or leave it empty to continue using alAutoNamespace.prefix.
4. Save an AL file for the enabled single-file automation, or run one of the commands below.

The extension searches the project's configured al.packageCachePath directories. A missing symbol package cannot supply a namespace.

Configure the namespace

Template setting

Set alAutoNamespace.namespaceTemplate in the project's .vscode/settings.json:

{
    "alAutoNamespace.namespaceTemplate": "myPartner.PTE.${appName}"
}

${appName} inserts the normalized name from the nearest app.json. The existing app-name normalization removes separators, capitalizes each part, and prefixes a name starting with a digit with App. Fixed text in the template retains its casing.

Examples for an app named ShopfloorIntegration:

• myPartner.PTE.${appName} produces myPartner.PTE.ShopfloorIntegration.
• myPartner.PTE produces exactly myPartner.PTE, with no app name appended.
• ${appName}.Extensions produces ShopfloorIntegration.Extensions.

A nonempty template takes precedence over prefix. If it is invalid, uses an unknown placeholder, or needs ${appName} when app.json has no usable name, the extension does not insert a namespace; it does not silently fall back to prefix. An existing namespace declaration is never replaced.

This is alAutoNamespace.namespaceTemplate, the setting for this extension. It is separate from the AL Language extension's al.namespaceTemplate setting.

Per-project settings and legacy fallback

VS Code workspace settings can override your User settings. Put the template in each project's .vscode/settings.json to give each project its own naming convention. The extension reads the effective setting for the AL file it is processing.

To keep the original naming behavior, leave namespaceTemplate empty or unset:

{
    "alAutoNamespace.namespaceTemplate": "",
    "alAutoNamespace.prefix": "myPartner.PTE"
}

The extension then builds myPartner.PTE.<NormalizedAppName>. Existing prefix-based projects therefore do not need to migrate immediately.

Note: Changing a namespace already used by other AL apps can break their references. The extension adds missing namespace declarations; it does not rename existing ones.

Commands

• AL Auto Namespace: Apply Namespace to Current File: Apply the configured namespace to the active AL file if it has none.
• AL Auto Namespace: Add Missing Standard Usings: Resolve missing usings in the active AL file. Despite the existing command name, resolution also considers selected direct dependencies.
• AL Auto Namespace: Apply Namespaces and Missing Usings to Active Project: Process .al files belonging to the active AL file's nearest app.json.
• AL Auto Namespace: Enable and AL Auto Namespace: Disable: Change the extension's enabled setting at the applicable configuration scope.

Project-wide command versus saving a file

The project-wide operation runs only when you invoke its command. Saving an AL file processes that file only.

The project command processes files sequentially, uses the same namespace template and using resolvers as the single-file workflows, and saves files it changes. Those saves may also invoke the existing single-file save listeners, but they do not start another project-wide scan.

The project command skips files belonging to a different nested app, files with unsaved changes, and files for which the extension is disabled. It reports changed, unchanged, skipped, partially processed, and failed files, and supports cancellation between files. It runs the using resolver even if alAutoNamespace.addStandardUsingsOnSave is false; that setting only controls automatic save-time insertion.

Settings

{
    "alAutoNamespace.enabled": true,
    "alAutoNamespace.namespaceTemplate": "myPartner.PTE.${appName}",
    "alAutoNamespace.addStandardUsingsOnSave": true
}

• alAutoNamespace.enabled: Master switch for automatic behavior; the project command also skips files where it is disabled.
• alAutoNamespace.namespaceTemplate: Preferred namespace convention. Supports ${appName} or a fixed namespace. An empty value uses prefix instead.
• alAutoNamespace.prefix: Legacy prefix; the normalized app name is appended when the template is empty.
• alAutoNamespace.addStandardUsingsOnSave: Add missing usings automatically after saving an AL file. Set to false if you prefer the manual commands.

Supported AL references

The source scanner recognizes:

• 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 symbol resolution works

1. Find the AL file's nearest app.json and the configured AL symbol cache directories.
2. Select available Microsoft Base Application, Business Foundation, System Application, and System packages. Consider other extensions only when they are direct dependencies in app.json.
3. Check package identity using the embedded NavxManifest.xml. For declared dependencies, compare app ID, name, publisher, and version; a filename alone is not authoritative.
4. Select the highest eligible cached version under the extension's package-selection rules. Skip equally ranked ambiguous candidates rather than selecting one arbitrarily.
5. Read SymbolReference.json from selected packages and cache successfully indexed objects.
6. Match each recognized reference by object kind and exact name. Add a using only when the matching objects identify one namespace that is not already the file namespace or an existing using.

Unrelated .app files in the cache are not treated as dependencies merely because they are present. An unreadable optional package is skipped without preventing readable packages from contributing usings.

Limitations and troubleshooting

• Direct dependencies only: External extensions must be declared in the active project's app.json. Arbitrary cached apps and every transitive dependency are not automatically indexed.
• Downloaded symbols required: Check al.packageCachePath and download symbols if a Microsoft or declared dependency package is missing.
• Unreadable packages: A selected package with a missing or unparsable SymbolReference.json is skipped and logged. Other readable packages can still work.
• Ambiguous object names: If an object kind and name resolve to different namespaces, the extension does not guess.
• Supported syntax only: Unrecognized AL constructs may require a manually added using.
• No removal of unused usings: The extension adds missing directives but does not remove existing ones.
• Version selection: The highest eligible cached version may not be the exact version used by the connected environment or AL compiler.
• Project-local objects: The symbol index does not include every object defined in the active project's source files. Review an import if a local object has the same kind and name.
• Project command scope: Open an AL file in the intended app first; files with unsaved changes are skipped rather than overwritten.
• Invalid namespace template: Check for empty segments, unsupported characters, or placeholders other than ${appName}. The extension leaves the file unchanged rather than inserting an invalid namespace.

If Base Application usings work but another package's usings do not, check the extension's output or debug console for package-selection and symbol-parsing warnings, and verify the cached package and app.json dependency.