Ir al contenido

Troubleshooting při vývoji AL

Průvodce řešením běžných chyb při nasazování, závislostech a stahování symbolů v prostředích Business Central.

0čtení

V naší operativě DevSecOps většina blokací nepochází z logických chyb v našem kódu, ale z chyb v konfiguraci prostředí, nesouladu verzí nebo problémů se síťovou komunikací mezi naším lokálním IDE (VS Code) a cloudovým tenantem.

Toto je naše znalostní báze pro okamžité řešení incidentů zaznamenaných během fází vývoje a integrace.

Incident 1: Chyba 404 Not Found (Stahování symbolů)

Sección titulada «Incidente 1: Error 404 Not Found (Descarga de Símbolos)»

Při spuštění příkazu AL: Download Symbols (nebo při pokusu o Build pomocí F5) terminál (Output -> AL) vrátí masivní bloky chyb podobné tomuto:

[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.

Toto je selhání synchronizace verzí v manifestu. Business Central je extrémně přísný (version-sensitive). Chyba indikuje, že náš lokální soubor app.json vyžaduje, aby server poslal knihovny jádra ve verzi 27.4.45366. Nicméně sandbox, na který poukazujeme (konfigurovaný v launch.json), má nainstalovanou předchozí verzi (například 25.0.0.0). Protože server nemá verzi, kterou požadujeme, vrátí 404.

  1. Identifikace verze serveru: Skutečnou verzi můžeme ověřit vstupem na web Business Central -> Nápověda a podpora -> O systému.
  2. Zmírnění app.json: Otevřeme soubor app.json v našem lokálním projektu.
  3. Snížíme minimální požadovanou verzi. Upravíme "application" a "platform" na verzi, o které víme, že je bezpečná a univerzální (např. 25.0.0.0 ).
  4. Snížíme spustovací motor "runtime" na kompatibilní verzi (např. 13.0 nebo 16.0 ).
  5. Vyčištění mecache: Fyzicky smažeme obsah skryté složky .alpackages.
  6. Znovný pokus: Znovu spustíme AL: Download Symbols. Terminál by měl zobrazit All reference symbols have been downloaded.

Incident 2: Chyba kvůli fantomovým závislostem („API Reports“)

Sección titulada «Incidente 2: Error por Dependencias Fantasma (“API Reports”)»

Při pokusu o stažení symbolů nebo kompilaci nám systém indikuje chybějící specifickou závislost, kterou nejsme schopni lokalizovat, například: A package with publisher 'Microsoft', name 'API Reports - Finance', could not be found.

VS Code při inicializaci projektů pomocí AL: Go! občas vkládá závislosti velmi specifických modulů (jako pokročilé finanční moduly) do bloku "dependencies" v app.json. Pokud náš Sandbox server nemá tuto konkrétní aplikaci Microsoftu nainstalovanou, globální balení selže řetězově.

Musíme vyčistit závislosti našeho projektu.

  1. Otevřeme app.json.
  2. Hledáme pole "dependencies": [ ... ].
  3. Pokud vyvíjíme obecné integrace nebo jednoduchá API, zcela odstraníme bloky neobvyklých závislostí (jako API Reports - Finance) a necháme pole [] prázdné nebo si ponecháme pouze kritické závislosti naší vlastní společnosti.
  4. Vymazat mezipaměť .alpackages a znovu stáhnout symboly.

Incident 3: Mýtus o složkách a názvosloví (CamelCase vs Snake_case)

Sección titulada «Incidente 3: Mito de las Carpetas y Nomenclatura (CamelCase vs Snake_case)»

Dotaz týmu: „Selže AL kompilátor, pokud kořenové složky projektu na mém disku (např. Consulta_Datos_Comercial) nejsou napsány ve formátu camelSensitive / CamelCase?“

Jednoznačná odpověď zní NE. AL kompilátor není citlivý na velikost písmen ani na formát fyzických názvů složek ve Windows.

  1. Souborový systém OS: Pro Visual Studio Code i Windows je jedno, zda je cesta C:/Proyectos/Consulta_Datos nebo c:/proyectos/cOnSuLtAdAtOs.
  2. Chování kompilátoru: Jakmile spustíme příkaz pro sestavení (Build), engine balí obsah výhradně na základě metadat deklarovaných v app.json (Vlastnosti "name" a "publisher"). Název vašeho lokálního adresáře je ignorován a pro cloudový server je irelevantní.

Doporučení pro pojmenovávání: V adresářích (Entradas_Salidas_AL) používáme konvenci Snake_Case (podtržítka) striktně kvůli lidské čitelnosti a vizuálnímu řádu v našich Git repozitářích, nikoliv z technického vynucení kompilátoru.

  • ✓ Vyčištění: Preventivní vyčištění složky .alpackages při provádění strukturálních změn v app.json.
  • ✓ Ověření: Absolutní koherence v sadě závislostí deklarovaných v manifestu s nainstalovanými rozšířeními v cloudu.
  • ✓ Sledování: Monitorování výstupního kanálu „AL Language“ ve VS Code pro přesnou diagnostiku chyb sítě.