Restore

ALWasp restores AL symbol packages from NuGet feeds for a single project, a .code-workspace, or the selected projects in a config-driven build.

When workspace build selects an explicit --bc-target, --bc-version, or --bc-country alone, its Microsoft symbols come from the selected Business Central artifact instead. Partner dependencies continue through NuGet, including transitive dependencies and the existing feed/authentication options. Microsoft dependencies are excluded from that NuGet traversal. See Workspace artifact selection for the isolated package caches. Standalone workspace restore retains its existing NuGet behavior. An explicit --bc-target current on build or workspace build uses the latest released artifact for the country. With no target or version, build keeps NuGet symbols, including country-only builds; workspace build keeps NuGet only when all BC options are omitted. Artifact builds stage only required Microsoft dependencies, transitively including those of partner packages, plus System and Application, removing previously staged artifact packages first.

alwasp restore
alwasp restore path/to/app.json
alwasp workspace restore ./project.code-workspace

For localized Microsoft symbols, set restore.country in alwasp.json:

{
  "restore": {
    "country": "DE"
  }
}

The configured localization is preferred for Microsoft symbols, including explicit test-library dependencies, with the unlocalized package as fallback. Omitting country or setting it to W1 prefers unlocalized/W1 packages and never substitutes a different country.

Dependency discovery

Explicit dependencies come from each project’s app.json dependencies array.

ALWasp also injects implicit Microsoft dependencies:

Dependency	Notes
System Application	Always added
Base Application	Always added
Application	Added when the application property requires Microsoft’s wrapper package
System	Uses Microsoft.Platform.symbols
Business Foundation	Added for Business Central 26+

For workspace restore, implicit dependencies are emitted once using the highest workspace app/platform version.

Package ID generation

When a dependency has no package ID, ALWasp generates:

{Publisher}.{Name}.symbols.{AppGuid}

Publisher and name keep only [A-Za-z0-9_], and the app GUID is lowercase. The producer command alwasp symbols pack uses the same convention, so its packages can be resolved directly. See Symbol Packages to create and publish a feed’s packages. Existing restore IDs and NuGet-based version lookup are unchanged in 0.5.9.

It also tries canonical package ID variants, including inserted .symbols., Microsoft application canonicalization, Microsoft.Platform.symbols, and a fallback GUID search across feeds.

Resolution modes

Mode	CLI	Behavior
Locked	default	Stable major-aware graph selection
LatestAll	--latest	Floating latest available graph

Locked mode prefers versions matching the project/workspace target major, then dependency-declared major, then any available version.

If a feed is behind the requested Microsoft symbols version, ALWasp does not replace a newer compatible Microsoft .app already present in the package cache with the older fallback. This is especially important for preview versions and compatibility validation caches seeded from downloaded Business Central artifacts.

Feed order

Repositories are searched in this order:

1. CLI --feed entries
2. Built-in public Business Central symbol feeds
3. Enabled feeds from nuget.config or default NuGet settings

Duplicate feed URLs are removed by normalized URL key.

Incremental restore manifest

ALWasp writes:

~/.alwasp/state/<packages-key>/restore-manifest.txt

The key contains the packages folder’s name and a hash of its normalized full path, so different package folders have separate state. The manifest stores packageId@version|file.app entries. An exact match is skipped only while its .app file still exists in the package cache; deleted or superseded files are downloaded again. Newer versions remain eligible. A legacy <packagesFolder>/.alwasp-packages is removed on the next restore; its entries are not trusted, while existing packages are still detected in the cache.

The package folder holds .app files between commands. Its shared .alwasp.lock remains in the cache while a command runs so all writers coordinate on the same lock, including other OS users and earlier ALWasp versions. After a killed command, the next command on that folder removes the leftover lock.

Restore prints its symbol source and destination, for example Symbols: NuGet feeds -> /repo/.alpackages.

Package overrides

Config-driven builds can replace a restored dependency with a pre-built .app, such as an artifact produced by another repository before its next NuGet release:

{
  "restore": {
    "packagesFolder": ".alpackages",
    "overridesFolder": "artifacts/package-overrides"
  }
}

overridesFolder is relative to alwasp.json and is applied after restore completes. It is also applied when restore itself is disabled with restore.enabled: false.

• Overrides and restored packages are matched by the AppId embedded in SymbolReference.json, never by file name.
• If the cache contains multiple packages with that AppId, ALWasp deterministically replaces the highest version. This avoids filesystem enumeration order deciding which package is overridden.
• A matching override always wins, regardless of version. A lower override version is accepted with a warning.
• An override with no matching package in the cache is not injected; it is reported as unmatched.
• Two override files with the same AppId fail before the package cache is changed.
• Malformed files in the overrides folder are skipped.
• Results expose overriddenCount and overriddenUnmatchedCount.

When a match is found, ALWasp copies the override under its own file name before removing the stale restored file. If the stale file is locked and cannot be deleted, the build continues with a warning because the requested override is already present.

Examples

alwasp restore --latest
alwasp restore --output ./symbols
alwasp restore --feed https://pkgs.dev.azure.com/org/_packaging/feed/nuget/v3/index.json
alwasp workspace restore --packages ./shared/.alpackages

The same feed, auth, country, and override settings can be supplied through alwasp.json for config-driven builds, where restore runs before compilation unless disabled with restore.enabled: false.

Credential-safe feed output

Restore masks embedded URL credentials and secret query parameters in NuGet feed log/error lines. Use the existing authentication options for private feeds; build effective-configuration reports apply the same protection to reported credentials and connection strings.

Workspace VS Code package caches

Since 0.5.7, workspace restore reads al.packageCachePath from project .vscode/settings.json, then the selected .code-workspace settings. --packages overrides these settings. A value can be a string or array, and relative paths resolve against each project folder. Cache entries are combined in project order; restore writes only the first cache and warns that additional entries are not used. Without an effective entry, the default remains .alpackages beside the workspace file.

workspace restore does not apply compiler or output-folder settings. It recognizes al.nugetFeeds and al.symbolsCountryRegion without applying them; use CLI or ALWasp configuration for feeds and localization. The restore summary reports detected settings, their sources, cache, mode, status, and duration; structured results include alSettings.