Устранение неполадок при разработке AL
Руководство по решению общих ошибок развертывания, зависимостей и загрузки символов в средах Business Central.
В нашей оперативной деятельности DevSecOps большинство блокировок происходит не из-за ошибок логики в нашем коде, а из-за сбоев в конфигурации среды, расхождений версий или проблем с сетевой связью между нашим локальным IDE (VS Code) и арендатором в облаке.
Это наша база знаний для мгновенного решения зарегистрированных инцидентов во время фаз разработки и интеграции.
Инцидент 1: Ошибка 404 Not Found (Загрузка символов)
Sección titulada «Incidente 1: Error 404 Not Found (Descarga de Símbolos)»Симптом
Sección titulada «Síntoma» При выполнении команды AL: Download Symbols (или при попытке выполнить сборку с помощью F5) терминал (Вывод -> AL) возвращает массивные блоки ошибок, аналогичные этому:
[2026-03-24 10:15:23] Sending request to https://api.businesscentral.../v2.0/sandbox/dev/packages?publisher=Microsoft&appName=Application&versionText=27.4.45366[2026-03-24 10:15:24] Error: Not Found[2026-03-24 10:15:24] The request for path ... failed with code NotFound.error AL1022: A package with publisher 'Microsoft', name 'Application', and a version compatible with '27.4.45366' could not be found.Диагностика коренной причины (чувствительность версий)
Sección titulada «Diagnóstico Raíz (Sensibilidad de Versiones)» Это ошибка несинхронизации версий в манифесте. Business Central очень строг ( чувствителен к версиям ). Ошибка указывает на то, что наш локальный файл app.json требует от сервера отправки библиотек ядра в версии 27.4.45366. Однако песочница, на которую мы нацеливаемся (настроена в launch.json), имеет более раннюю версию (например, 25.0.0.0). Поскольку сервер не имеет версии, которую мы требуем, он возвращает 404.
Решение шаг за шагом
Sección titulada «Resolución Paso a Paso»- Определение версии сервера: Мы можем проверить фактическую версию, войдя на веб-сайт Business Central -> Справка и поддержка -> О программе.
- Отмена
app.json: Мы открываем файлapp.jsonв нашем локальном проекте. - Мы снижаем минимальную требуемую версию. Мы изменяем
"application"и"platform"на версию, которую мы знаем как безопасную и универсальную (например,25.0.0.0). - Понижаем версию движка исполнения
"runtime"до совместимой версии (например,13.0или16.0). - Очистка кэша: Физически удаляем содержимое скрытой папки
.alpackages. - Повторная попытка: Повторно запускаем
AL: Download Symbols. Терминал должен отобразитьAll reference symbols have been downloaded.
Инцидент 2: Ошибка из-за фантомных зависимостей («API Reports»)
Sección titulada «Incidente 2: Error por Dependencias Fantasma (“API Reports”)»Симптом
Sección titulada «Síntoma»При попытке скачать символы или скомпилировать, система сообщает нам, что не хватает определенной зависимости, которую мы не можем найти, например: A package with publisher 'Microsoft', name 'API Reports - Finance', could not be found.
Диагностика коренной причины
Sección titulada «Diagnóstico Raíz»VS Code, при инициализации проектов через AL: Go!, иногда внедряет зависимости специфических модулей (например, финансовых модулей) в блок "dependencies" файла app.json. Если на нашем сервере Sandbox не установлено это приложение Microsoft, глобальное упаковывание завершится с ошибкой.
Мы должны очистить зависимости нашего проекта.
- Открываем
app.json. - Ищем массив
"dependencies": [ ... ]. - Если мы разрабатываем общие интеграции или простые API, полностью удаляем блоки посторонних зависимостей (например,
API Reports - Finance), оставляя пустой массив[]или сохраняя только критически важные зависимости нашей компании. - Удаляем кэш из
.alpackagesи повторно скачиваем символы.
Инцидент 3: Миф о папках и номенклатуре (CamelCase vs Snake_case)
Sección titulada «Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)»Часто задаваемый вопрос
Sección titulada «Consulta/Duda Frecuente»Вопрос команды: «Сбой компилятора AL, если корневые папки проекта на моем жестком диске (напр., Consulta_Datos_Comercial) не написаны в camelSensitive / CamelCase?»
Техническое разъяснение DevSecOps
Sección titulada «Aclaración Técnica DevSecOps»Ответ категорический: НЕТ. Компилятор AL не чувствителен к регистру или форматам в физических именах папок Windows.
- Файловая система ОС: Visual Studio Code и Windows безразличны к тому, является ли путь
C:/Proyectos/Consulta_Datosилиc:/proyectos/cOnSuLtAdAtOs. - Поведение компилятора: Как только мы запускаем команду компиляции (Build), движок упаковывает содержимое, основываясь исключительно на метаданных, объявленных внутри
app.json(Свойства"name"и"publisher"). Имя вашего локального каталога игнорируется и не имеет значения для сервера Cloud.
Рекомендация по именованию: Мы используем соглашение Snake_Case (нижние подчеркивания) в каталогах (Entradas_Salidas_AL) строго для человеческой читаемости и визуального порядка в наших репозиториях Git, а не из-за технического диктата компилятора.
4. Критерии успеха триажа
Sección titulada «4. Criterios de Éxito de Triage»- ✓ Очистка: Предотвратительное очищение папки
.alpackagesпри внесении структурных изменений вapp.json. - ✓ Проверка: Абсолютная согласованность в наборе зависимостей, объявленных в манифесте, с расширениями, установленными в облаке.
- ✓ Отслеживание: Мониторинг канала вывода «AL Language» в VS Code для точной диагностики сетевых ошибок.

