--- id: release/al-17.0 type: release title: AL Language extension 17.0 summary: "AL Language extension 17.0 for Business Central 2026 release wave 1 (BC28): previewed 2025-08-29, released 2026-04-01; 29 changelog entries, 13 GitHub issues linked." tier: official language: en system: development tags: - agents in business central move to gpt-5.3-chat - bug fixes - al language changes - "new warning al0914: excel layout contains an orphaned sheet after automatic multi-sheet upgrade" - github issues - runtime changes - support for packaging analysis views in extensions - support for namespaces and fully qualified names review: state: derived by: null at: null flags: [] generated: at: "2026-10-09T15:15:16.849Z" pipeline: 0.2.0 prompts: {} input_hash: 4753ad03912c159d3c58a67af372c53c6b74e142a292ba7c211032a7ad493599 evidence: - kind: marketplace url: https://marketplace.visualstudio.com/items/ms-dynamics-smb.al/changelog title: AL Language extension changelog, version 17.0 date: "2026-04-01" commit: null t: null quote: null links: learn: [] objects: [] features: [] topics: [] localizations: [] videos: [] posts: [] guidelines: [] source_id: al-language-extension extension: ms-dynamics-smb.al version: "17.0" wave: 2026 release wave 1 major: "28" preview_at: "2025-08-29" released_at: "2026-04-01" published_at: "2026-04-01" prerelease: false entry_count: 29 issues: - 8028 - 8094 - 8132 - 8133 - 8143 - 8174 - 8177 - 8180 - 8181 - 8191 - 8197 - 8198 - 8199 changes: [] --- # AL Language extension 17.0 > AL Language extension 17.0 for Business Central 2026 release wave 1 (BC28): previewed 2025-08-29, released 2026-04-01; 29 changelog entries, 13 GitHub issues linked. [Changelog on the Visual Studio Marketplace](https://marketplace.visualstudio.com/items/ms-dynamics-smb.al/changelog) · Business Central 2026 release wave 1 · BC28 ## Agents in Business Central move to GPT-5.3-chat From May through June, Agents in Business Central are upgrading to GPT-5.3-chat as the default model. This update rolls out gradually to environments across all regions. **What's changing:** - **New default model** — GPT-5.3-chat replaces the previous model, bringing improved quality and performance for agents in Business Central. - **Model control for coded agents** — New methods when coding agents let you control model selection programmatically from AL. - **Model visibility and selection in agent design experience** - Administrators can see which language model their agents use and select their preferred model from the available options in the agent configuration page. **What to expect during rollout:** The model update and the new UI for model selection roll out independently. Your environment might receive GPT-5.3-chat before the model selection UI and new methods become available. During this period, agents continue to work as expected with the new model. Environments in the UK, India, and Australia will receive the update at a later date. If you want to switch models for your *designed* agents after the selection UI becomes available, you can do so from the **Agents** page in Business Central. For coded agents, use the new model selection methods to control which model your agent uses. For those of you having started on the journey of designing and coding agents, then we highly recommend evaluating your agents again once the model has updated, as agent behavior, as well as accuracy, might be impacted. ## Bug fixes - Fixed an issue where the AL compiler would always emit the fully qualified assembly name for DotNet types, even when only the simple name was specified in the dotnet block. The compiler now respects the developer's choice and only includes version, culture, and public key token information in the emitted C# code when explicitly specified in the AL source. ## AL Language changes ### New warning AL0914: Excel layout contains an orphaned sheet after automatic multi-sheet upgrade When an existing single-sheet Excel layout is reused with a report that has `ExcelLayoutMultipleDataSheets` set to `true`, the compiler now automatically adds the required dataitem sheets. However, the original template sheet (typically named `Data`) is left in the workbook as an orphan; the rendered report will contain this orphaned sheet, which may confuse end users. To resolve the warning, delete the layout file and let the compiler regenerate it cleanly. ## GitHub issues - [#8028](https://github.com/microsoft/AL/issues/8028) The AL extension no longer creates `.alpackages` and `.snapshots` folders in non-AL workspace folders. - [#8094](https://github.com/microsoft/AL/issues/8094) "Publish extension without building" command ignores al.compilationOptions.outFolder setting. - [#8143](https://github.com/microsoft/AL/issues/8143) If a system overload is not available in the used runtime, why AL0196 "call is ambiguous"? - [#8174](https://github.com/microsoft/AL/issues/8174) This keyword doesn't get found when used in TableExtension. - [#8180](https://github.com/microsoft/AL/issues/8180) Debugger 'Out of Scope' value when hovering a variable with a value. - [#8132](https://github.com/microsoft/AL/issues/8132) Automatic variable "Return Value" missing in VSCode Debugger Variables -> Locals - [#8181](https://github.com/microsoft/AL/issues/8181) vscode.commands.executeCommand('al.publishNoDebug') not returning result? - [#8177](https://github.com/microsoft/AL/issues/8177) No new ID is suggested when using namespaces - [#8199](https://github.com/microsoft/AL/issues/8199) DataItemLink using FlowFilter not recognized in Query for runtime < 19 - [#8191](https://github.com/microsoft/AL/issues/8191) Procedure decorators prevent proper XML comment parameter highlighting. - [#8197](https://github.com/microsoft/AL/issues/8197) Added al.disableTestRunning setting to disable test discovery and execution features. - [#8198](https://github.com/microsoft/AL/issues/8198) Quick Fix to add a missing using statement does not respect AL0897 - [#8133](https://github.com/microsoft/AL/issues/8133) When an error occurs while publishing an app, cancelling the dialog also clears the Debug Console ## Runtime changes ### Support for packaging analysis views in extensions Analysis views can now be packaged and delivered as part of AL extensions for list pages, including extensions and customizations. This feature enables developers to create standardized data analysis views that can be easily distributed and reused across different Business Central environments. To do so: 1. Use Analysis Mode in the web client to create and export your analysis view as an `.analysis.json` file. 2. Include the `.analysis.json` file in your AL extension project. 3. Add an `analysisview` component within the `analysisviews` section to your page to reference the analysis view definition. **Page example:** ```al page 50120 "My Sales Analysis Page" { PageType = List; SourceTable = "Sales Line"; analysisviews { analysisview(SalesPerformanceView) { DefinitionFile = 'SalesPerformanceAnalysis.analysis.json'; Caption = 'Sales Performance Analysis'; } analysisview(RegionalSalesView) { DefinitionFile = 'RegionalSalesAnalysis.analysis.json'; Caption = 'Regional Sales Breakdown';e } } } ``` **Page extension example:** ```al pageextension 50121 "Customer List Analysis" extends "Customer List" { analysisviews { analysisview(CustomerAnalyticsView) { DefinitionFile = 'CustomerAnalytics.analysis.json'; Caption = 'Customer Analytics Dashboard'; } } } ``` ### Support for namespaces and fully qualified names New method overloads are introduced to support running codeunits, pages, and reports using their fully-qualified names. Additionally, `RecordRef.Open` can now be invoked with the fully-qualified name of a table. ```al codeunit 10 MyCodeunit { procedure MyProcedure() var rec: Record Customer; recRef: RecordRef; begin // Run codeunit by fully qualified name Codeunit.Run('MyNamespace.CodeunitName'); // Page methods by fully qualified name Page.Run('MyNamespace.PageName'); Page.RunModal('MyNamespace.PageName'); // Report methods by fully qualified name Report.Run('MyNamespace.ReportName'); Report.RunModal('MyNamespace.ReportName'); Report.Execute('MyNamespace.ReportName', 'foo', rec); // Load record by fully qualified name recRef.Open('MyNamespace.TableName'); end; } ``` Record and RecordRef instances now expose a `FullyQualifiedName` property. ```al codeunit 10 MyCodeunit { procedure MyProcedure() var rec: Record Customer; recRef: RecordRef; begin Message(rec.FullyQualifiedName); Message(recRef.FullyQualifiedName); end; } ``` ## Visual Studio Code Editor changes ### New template for getting started with creating agents in Business Central A new template for creating Business Central agents is now added. You can access it via the `AL: New Project` command by choosing the template `Agent`. The template comes with instructions on how to get started. ### Connecting to the Business Central Troubleshooting MCP Server It's now possible to connect to the Business Central Troubleshooting MCP server during troubleshooting. The Business Central Troubleshooting MCP server will appear in the list of available MCP servers in Visual Studio Code. When paused at a breakpoint, you can leverage the Visual Studio Agent to deepen your investigation by utilizing the capabilities of the Business Central Troubleshooting MCP server. ### Visual Studio Code authentication options - Integrates with Visual Studio Code's authentication API so sign-in behaves consistently across environments. - `useVsCodeAuthentication` lets you reuse Visual Studio Code-issued access tokens; configure it in user or workspace settings and override it per launch configuration when needed. - `vsCodeAuthenticationProvider` chooses the Visual Studio Code authentication provider to request tokens from, for example, `microsoft` or `microsoft-sovereign-cloud`. - When `useVsCodeAuthentication` is enabled, the extension ignores `useInteractiveLogin` and `entraIdAuthentication`, because those settings only apply when Visual Studio Code authentication is disabled. ### Download Symbols from Global NuGet Sources A new command **AL: Download Symbols from Global Sources** allows downloading app packages directly from Microsoft's public NuGet feeds. The feature supports country/region-specific packages using the `al.symbolsCountryRegion` setting. Custom NuGet feeds can be configured via `al.customNugetFeeds`, with the option to restrict downloads to custom feeds only using `al.useOnlyCustomFeeds`. ### Run tests from Visual Studio Code It is now possible to use the VSCode Test Explorer to run tests. Running tests is only supported on Business Central version 28.0 and newer, on both sandboxes and local servers. We support the following run profiles: - **Publish & Run**: Publishes the test project and any of its dependencies before running the selected tests. - **Run**: Runs all selected tests without pre-publishing the test project. If what is published on the server is out of sync with what is in VSCode, some tests may not get executed. - **Run & Debug**: Starts a debugging session and runs the selected tests. This will pre-publish the test project to ensure that what is debugged matches what is on the server. - **Run with Coverage**: Starts a test run and collects code coverage information. **Test execution** Tests executed from VSCode do not use an AL test runner and there is no way to specify one. Instead, the isolation level of the tests is determined by the [RequiredTestIsolation](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/properties/devenv-requiredtestisolation-property) property on the test codeunit. If the property is not specified, it will run with `Codeunit` level isolation. You can choose to run entire test codeunits, or specific tests within those codeunits by selecting them in the Test Explorer. **Code coverage** **Note:** We currently do not support full line-based code coverage. When tests are executed with the `Run with Coverage` profile, a new codelens bar above procedures will be visible. This bar shows the number of tests that cover a specific procedure, as well as their current pass/fail count. Clicking on this codelens will run the tests that cover the specific procedure. This is useful for running the most relevant tests when modifying a specific procedure. **Agentic test running** Agents within Visual Studio Code are able to run tests via Visual Studio Code's in-built `runTest` tool. For enabling test-running for other agents, refer to the `ALMCP` server that is part of the `al` dotnet tool package. See [here](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-al-tool-package) for more information. **Disabling test integration** If you are using a third-party extension for running AL test from VSCode, these new capabilities may conflict with your existing solution. In this case, you can add `al.disableTestRunning: "true"` to your VSCode settings to disable this feature. ### New AL Tools Available for Agents The following AL development tools are now accessible to agents: | Tool Name | Purpose | |-----------|---------| | `al_build` | Build AL project(s). Supports scope parameter: 'current' for single project, 'all' for workspace with dependencies. | | `al_debug` | Start a debugging session without publishing the extension. | | `al_downloadsymbols` | Download symbols for the current project. | | `al_publish` | Publish AL package with flexible skipbuild, debugging, incremental, and dependency modes. Use skipbuild=true for already packaged extensions, fulldependencytree=true for full dependency chain. | | `al_setbreakpoint` | Set, remove, or toggle breakpoints in AL code. Supports actions: 'toggle' (default), 'add', 'remove'. | | `al_snapshotdebugging` | Manage snapshot debugging sessions. Supports actions: 'initialize', 'finish', 'view' (opens snapshots view). | | `al_symbolsearch` | Search for AL symbols in the open workspace and dependencies. | These tools streamline common AL development workflows and improve automation capabilities for agents. **Note:** These tools are experimental and subject to change in future updates. ### Tool Workflow Suggestions AL tools now suggest logical next steps after execution, streamlining common task sequences and reducing context switching. ### AL Tools Enhanced Error Handling Improved error diagnostics with better categorization, actionable hints using `get_errors` tool for automated error retrieval, and comprehensive guidance for common issues. ### Standalone MCP Server provided as part of ALTool The [AL dotnet tool](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-al-tool-package) now supports a new command: `LaunchMcpServer`. This starts up an HTTP based MCP server which can be used by coding agents to invoke AL-specific development tools. The basic usage is: `al LaunchMcpServer --projects "C:\Users\MyUser\MyALProject"` This launches an MCP server, which will track changes within the `MyALProject` folder and provide tools such as the ability to compile the project. In addition to the `projects` parameter, the following parameters can be used to configure the behavior of the MCP server: ``` --projects Required. Semicolon-separated list of AL project paths to load. --port (Default: 5000) Port number for the HTTP server (default: 5000). --codeanalyzers Semicolon-separated list of code analyzers to enable. --rulesetpath Path to the ruleset file. --packagecachepath Semicolon-separated list of package cache directories. --assemblyprobingpaths Semicolon-separated list of assembly probing paths. --outfolder Output folder for compilation artifacts. --help Display this help screen. --version Display version information. ``` ### ALTool: Workspace commands The AL command line tool now includes a set of `workspace` commands for working with multi-project AL workspaces. The recommended way to install the tool is via the [Business Central Development Tools NuGet package](https://www.nuget.org/packages/Microsoft.Dynamics.BusinessCentral.Development.Tools), which is a [.NET tool](https://learn.microsoft.com/dotnet/core/tools/global-tools) that provides the `al` command: ```bash dotnet tool install --global Microsoft.Dynamics.BusinessCentral.Development.Tools ``` ##### `workspace create` Creates a `.code-workspace` file by recursively searching one or more folders for AL projects (folders containing `app.json`). Each discovered project is added to the workspace with its name read from the manifest. ```bash al workspace create my.code-workspace ./src ``` When the specified folders are themselves AL projects, only those folders are included. Otherwise, the command searches subdirectories recursively and excludes nested projects that fall under another project root. ##### `workspace compile` Compiles all projects in a workspace in the correct dependency order. The command reads each project's manifest to build a dependency graph, then parallelizes compilations where possible. ```bash al workspace compile my.code-workspace ``` The following options are available: | Option | Description | |---|---| | `--maxcpucount` | Maximum number of concurrent compilations. Defaults to the number of processors. | | `--packagecachepath` | Semicolon-separated list of package cache directories. | | `--assemblyprobingpaths` | Semicolon-separated list of assembly probing paths. | | `--analyzers` | Built-in analyzers to run (CodeCop, AppSourceCop, PTECop, UICop). | | `--customanalyzers` | Paths to custom analyzer assemblies. Supports absolute paths, paths relative to the workspace directory, and well-known variables (for example, `${AnalyzerFolder}/MyAnalyzer.dll`). | | `--features` | Features to enable (LcgTranslationFile, TranslationFile, GenerateCaptions). | | `--generatereportlayout` | Generate report layout. | | `--define` | Preprocessor symbols to define. | | `--sourcerepositoryurl` | Source repository URL for the workspace. | | `--sourcecommit` | Source commit ID for the workspace. | | `--loglevel` | Logging level. | | `--logdirectory` | Directory to store compilation log files. | ##### `workspace map` Generates a Markdown file with a Mermaid dependency diagram from a workspace. The output includes a visual graph of inter-project dependencies, a project details table, and warnings for any circular dependencies detected. ```bash al workspace map my.code-workspace al workspace map my.code-workspace output.md ``` ### ALTool: Symbol-only and runtime package detection ALTool now supports detecting whether an app is symbol-only and whether a package is a runtime package. These checks help tools like ALGo determine if an extension can be published to SaaS or containers. ## AL code analyzers changes ### CodeCop - CodeCop rule [AA0247](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/analyzers/codecop-aa0247) has been enabled by default. ### Code actions for namespaces - Added a code action to sort `using` statements alphabetically. ### AppSourceCop - Fixed an issue where, in certain scenarios, rule [AS0025](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/analyzers/appsourcecop-as0025) wouldn't allow retyping procedure parameters that are referencing an obsolete removed table or a removed application object. ## Miscellaneous - Added new compiler warning [AL0910](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/diagnostics/diagnostic-al910) and error [AL0911](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/diagnostics/diagnostic-al911) for detecting empty field and key names that cause runtime errors. The warning is shown for runtime versions before Spring 2027 and becomes an error from Spring 2027 onwards. - Added new compiler error [AL0896](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/diagnostics/diagnostic-al896) for detecting FlowField definitions that are recursively dependent and could cause infinite evaluation. - Added new compiler warning [AL0910](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/diagnostics/diagnostic-al910) (becomes error in Spring 2027) to prevent FlowFields and FlowFilters from being used in Query DataItemLink properties, as these field types are computed at runtime and cannot be used in SQL join operations. - Update the compiler error [AL0279](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/diagnostics/diagnostic-AL279) to take the total number of fields into account, including fields added to the key automatically from the primary key. - Fixed an issue where dotnet assembly loading would crash in certain scenarios. - Fixed an issue where the AL Profile Visualizer would not correctly restore expanded nodes when loading persisted state. - Add support for `AddDestinationFilter` for `DataTransfer`. A common use-case is to only overwrite blank fields on upgrade. - Fixed an issue where it was possible to create invalid folder paths containing leading or trailing whitespace using AL:Go! - Fixed issue where fields on report request pages didn't get dynamic captions from their underlying table fields. - Fixed issue where caption of field didn't show up in the filter pane. - When a built-in method call with a `Variant` argument is ambiguous between two overloads, the compiler now resolves the ambiguity by implicitly choosing the oldest available overload and emitting a new compiler warning [AL0916](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/diagnostics/diagnostic-al916) instead of an error. ### Attach to agent session It's now possible to attach to agent sessions and debug the AL code they're executing. To do so, the new client type `Agent` has been introduced along with two new launch configurations to attach to an agent session on a cloud sandbox or your own server. ### Quick uptake of namespaces A new code action has been introduced to fix CodeCop rule [AA0247](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/analyzers/codecop-aa0247) by adding namespaces to .al files that are missing them. The namespace is resolved in the following order: 1. Read and parse the newly added `al.namespaceTemplate` setting. The `$(parentfolder)` placeholder can be used to dynamically insert the directory of an AL file. 2. If `namespaceTemplate` is not defined or any part of it does not resolve to a valid identifier name, the system attempts to deduce the namespace from sibling files (AL files in the same folder) by parsing their namespaces and using the longest common part. 3. If there are no sibling files, they don't specify a namespace, or there is no common part, the fallback is `publisher.projectname`. 4. If `publisher.projectname` does not resolve to a valid namespace name, no namespace is added. ## AL Language changes ## JsonToken, JsonArray, and JsonObject - SelectTokens New method that supports selecting multiple tokens from a JsonToken, JsonArray, or JsonObject into a newly created output list. The syntax and usage is the same as SelectToken, but instead of setting a single JsonToken in the result, all the matching elements are placed in the result list. Alterations in the list do not reflect in the queried JsonToken. Source: Visual Studio Marketplace, ms-dynamics-smb.al changelog, Microsoft's text unchanged. Dates from the gallery's upload records.