Rozwiązywanie problemów w rozwoju AL
Przewodnik rozwiązywania typowych błędów wdrożeniowych, zależności i pobierania symboli w środowiskach Business Central.
W naszej operacji DevSecOps, większość blokad nie pochodzi z błędów logicznych w naszym kodzie, lecz z awarii konfiguracji środowiska, rozbieżności wersji lub problemów z komunikacją sieciową między naszym lokalnym IDE (VS Code) a tenantem w chmurze.
Jest to nasza baza wiedzy, aby natychmiast rozwiązać zarejestrowane incydenty podczas faz rozwoju i integracji.
Incydent 1: Błąd 404 Not Found (Pobieranie symboli)
Sección titulada «Incidente 1: Error 404 Not Found (Descarga de Símbolos)»Podczas wykonywania polecenia AL: Download Symbols (lub podczas próby kompilacji za pomocą F5), terminal (Output -> AL) zwraca ogromne bloki błędów podobne do tego:
[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.Diagnoza Pierwotna (Wrażliwość na wersje)
Sección titulada «Diagnóstico Raíz (Sensibilidad de Versiones)»Jest to awaria spowodowana niezgodnością wersji w Manifeście. Business Central jest niezwykle restrykcyjny (czuły na wersję). Błąd wskazuje, że nasz lokalny plik app.json wymaga od serwera, aby wysłał nam biblioteki rdzenia w wersji 27.4.45366. Jednak Sandbox, na który celujemy (skonfigurowany w launch.json), ma zainstalowaną wcześniejszą wersję (np. 25.0.0.0). Ponieważ serwer nie posiada wersji, której wymagamy, zwraca 404.
Rozwiązanie krok po kroku
Sección titulada «Resolución Paso a Paso»- Identyfikacja wersji serwera: Możemy sprawdzić rzeczywistą wersję, wchodząc na stronę Business Central -> Pomoc i obsługa -> Informacje o.
- Zmniejszenie
app.json: Otwieramy plikapp.jsonw naszym lokalnym projekcie. - Zmniejszamy minimalną wymaganą wersję. Modyfikujemy
"application"i"platform"do wersji, o której wiemy, że jest bezpieczna i uniwersalna (np.25.0.0.0). - Zmniejszamy silnik wykonywania
"runtime"do wersji kompatybilnej (np.13.0lub16.0). - Czyszczenie pamięci podręcznej: Fizycznie usuwamy zawartość ukrytej folderu
.alpackages. - Ponowna próba: Wykonujemy ponownie
AL: Download Symbols. Terminal powinien wyświetlićAll reference symbols have been downloaded.
Incydent 2: Błąd z powodu zależności widmowych („API Reports”)
Sección titulada «Incidente 2: Error por Dependencias Fantasma (“API Reports”)»Podczas próby pobrania symboli lub skompilowania, system informuje nas, że brakuje określonej zależności, której nie możemy zlokalizować, np. A package with publisher 'Microsoft', name 'API Reports - Finance', could not be found.
Diagnoza pierwotna
Sección titulada «Diagnóstico Raíz»VS Code, podczas inicjowania projektów za pomocą AL: Go!, czasami wstrzykuje zależności modułów bardzo specyficznych (takich jak zaawansowane moduły finansowe) do bloku "dependencies" app.json. Jeśli nasz serwer Sandbox nie ma zainstalowanej tej konkretniej aplikacji Microsoft, globalne pakowanie zakończy się niepowodzeniem.
Rozwiązanie
Sección titulada «Resolución»Musimy oczyścić zależności naszego projektu.
- Otwieramy
app.json. - Szukamy tablicy
"dependencies": [ ... ]. - Jeśli opracowujemy ogólne integracje lub proste API, usuwamy całkowicie bloki zewnętrznych zależności (takich jak
API Reports - Finance), pozostawiając pustą tablicę[]lub zachowując tylko krytyczne zależności naszej własnej firmy. - Czyszczenie pamięci podręcznej
.alpackagesi ponowne pobieranie symboli.
Incydent 3: Mit o folderach i nazwach (CamelCase vs Snake_case)
Sección titulada «Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)»Zapytanie / Często zadawane pytania
Sección titulada «Consulta/Duda Frecuente»Wątpliwość zespołu: „Czy kompilator AL zawodzi, jeśli główne foldery projektu na moim dysku twardym (np. Consulta_Datos_Comercial) nie są napisane w camelSensitive / CamelCase?”
Wyjaśnienie techniczne DevSecOps
Sección titulada «Aclaración Técnica DevSecOps»Odpowiedź brzmi: NIE. Kompilator AL nie jest wrażliwy na wielkość liter ani formaty w nazwach fizycznych folderów systemu Windows.
- System plików SO: Dla Visual Studio Code i Windows jest obojętne, czy ścieżka jest
C:/Proyectos/Consulta_Datosczyc:/proyectos/cOnSuLtAdAtOs. - Zachowanie kompilatora: Po uruchomieniu polecenia kompilacji (Build) silnik pakuje zawartość wyłącznie na podstawie metadanych deklarowanych wewnątrz
app.json(Właściwości"name"i"publisher"). Nazwa Twojego lokalnego katalogu jest ignorowana i nieistotna dla serwera Cloud.
Zalecenie dotyczące nomenklatury: Używamy konwencji Snake_Case (podkreślników) w katalogach (Entradas_Salidas_AL) ściśle ze względu na czytelność ludzką i porządek wizualny w naszych repozytoriach Git, a nie z powodu technicznych nakazów kompilatora.
4. Kryteria Sukcesu Triage
Sección titulada «4. Criterios de Éxito de Triage»- ✓ Czyszczenie: Zapobiegawcze opróżnianie folderu
.alpackagespodczas wprowadzania zmian strukturalnych wapp.json. - ✓ Weryfikacja: Zupełna spójność w deklarowanej suitie zależności w manifeście z rozszerzeniami zainstalowanymi w chmurze.
- ✓ Śledzenie: Monitorowanie kanału wyjścia „AL Language” w VS Code w celu dokładnej diagnostyki błędów sieciowych.

