如何在Business Central中强制指定符号版本？解决编译报错

问题 #

我正在ES Business Central 25.3版本的沙盒环境中开发，环境版本详情：

• Platform：25.2.29913.0
• Application：25.3.28755.30175

我的app.json配置如下：

{
  "id": "97a3ace3-8ba8-4732-af0c-22e1fc6091f8",
  "name": "Tracking Central",
  "publisher": "ProgramadorBC.es",
  "version": "1.0.0.0",
  "brief": "",
  "description": "Tracking Central es una aplicación que permite a los usuarios realizar un seguimiento de los envíos de sus paquetes.",
  "privacyStatement": "",
  "EULA": "",
  "help": "",
  "url": "https://programadorbc.es",
  "logo": "./Logo/programadorbc.png",
  "dependencies": [
    {
      "id": "63ca2fa4-4f03-4f2b-a480-172fef340d3f",
      "name": "System Application",
      "publisher": "Microsoft",
      "version": "25.3.28755.29171"
    },
    {
      "id": "f3552374-a1f2-4356-848e-196002525837",
      "name": "Business Foundation",
      "publisher": "Microsoft",
      "version": "25.3.28755.29171"
    },
    {
      "id": "437dbf0e-84ff-417a-965d-ed2bb9650972",
      "name": "Base Application",
      "publisher": "Microsoft",
      "version": "25.3.28755.29242"
    }
  ],
  "screenshots": [],
  "platform": "25.2.0.0",
  "application": "25.3.0.0",
  "idRanges": [
    {
      "from": 53200,
      "to": 53249
    }
  ],
  "resourceExposurePolicy": {
    "allowDebugging": true,
    "allowDownloadingSource": false,
    "includeSourceInSymbolFile": false
  },
  "runtime": "14.0",
  "features": ["NoImplicitWith"]
}

下载符号时自动获取了25.4版本的应用，与当前环境版本不符，编译时出现以下错误：

Compilation started for project 'Tracking Central' containing '1' files at '10:50:40.512'.

error AL1022: A package with publisher 'Microsoft', name 'System Application', and a version compatible with '25.4.0.0' could not be found in the package cache folders: c:\Users\Adrian\Desktop\OneDrive - programadorbc.es\AA - ProgramadorBC\Tracking Central\.alpackages
error AL1022: A package with publisher 'Microsoft', name 'Base Application', and a version compatible with '25.4.0.0' could not be found in the package cache folders: c:\Users\Adrian\Desktop\OneDrive - programadorbc.es\AA - ProgramadorBC\Tracking Central\.alpackages
error AL1022: A package with publisher 'Microsoft', name 'Business Foundation', and a version compatible with '25.4.0.0' could not be found in the package cache folders: c:\Users\Adrian\Desktop\OneDrive - programadorbc.es\AA - ProgramadorBC\Tracking Central\.alpackages

Compilation ended at '10:50:40.532'.

Error: The package could not be created.

已尝试删除.alpackages和.snapshots文件夹、清除凭据缓存、重载VS Code开发窗口、添加对应依赖等操作，问题仍未解决，求强制使用正确符号版本的方法。

解决方案 #

1. 锁定符号源与版本 #

在VS Code的settings.json中添加以下配置，强制指定符号服务器的版本范围，避免自动拉取高版本：

{
  "al.symbolReferenceHandling": "strict",
  "al.packageCachePath": "./.alpackages",
  "al.symbolServerAddress": "https://api.businesscentral.dynamics.com/v2.0/es-ES/sandbox/dev/packages?version=25.3.0.0"
}

注意：将es-ES替换为你的环境区域代码，版本号与环境的Application版本匹配。

2. 手动下载指定版本符号包 #

• 按以下格式拼接下载链接，直接获取对应版本的官方包：
  https://api.businesscentral.dynamics.com/v2.0/<区域代码>/sandbox/dev/packages/microsoft/<包名>/<版本号>
  示例：https://api.businesscentral.dynamics.com/v2.0/es-ES/sandbox/dev/packages/microsoft/System%20Application/25.3.28755.29171
• 下载后将.app文件放入项目的.alpackages文件夹中。

3. 精确约束依赖版本 #

在app.json的依赖项中，给版本号添加=前缀，强制使用指定版本，避免自动兼容高版本：

"dependencies": [
  {
    "id": "63ca2fa4-4f03-4f2b-a480-172fef340d3f",
    "name": "System Application",
    "publisher": "Microsoft",
    "version": "=25.3.28755.29171"
  }
]

4. 清理全局符号缓存 #

除了项目内的缓存，还需清理全局缓存：

• 打开VS Code命令面板（Ctrl+Shift+P），执行AL: Clear All Symbol Caches命令。
• 手动删除全局缓存目录：C:\Users\<你的用户名>\.alpackages

5. 重新配置环境连接 #

• 打开VS Code命令面板，执行AL: Configure Project，重新选择对应的25.3沙盒环境。
• 确认连接时选择的环境版本与本地配置完全一致，避免自动升级到高版本。

内容的提问来源于stack exchange，提问作者kuhi