Ir al contenido

Troubleshooting in AL-ontwikkeling

Gids voor het oplossen van veelvoorkomende fouten bij deployment, afhankelijkheden en het downloaden van symbolen in Business Central-omgevingen.

0lecturas

In onze DevSecOps-operaties komen de meeste blokkades niet voort uit logische fouten in onze code, maar uit configuratiefouten in de omgeving, versie-incompatibiliteiten of netwerkcommunicatieproblemen tussen onze lokale IDE (VS Code) en de cloud-tenant.

Dit is onze kennisbank om incidenten die tijdens de ontwikkelings- en integratiefasen zijn geregistreerd, onmiddellijk op te lossen.

Incident 1: Fout 404 Not Found (Symbolen downloaden)

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

Bij het uitvoeren van het commando AL: Download Symbols (of bij het proberen te bouwen met F5), geeft de terminal (Output -> AL) enorme foutblokken terug die lijken op deze:

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

Dit is een fout door versie-desynchronisatie in het manifest. Business Central is extreem strikt (version-sensitive). De fout geeft aan dat ons lokale bestand app.json van de server eist dat de core-bibliotheken in versie 27.4.45366 worden verzonden. Echter, de sandbox waarnaar we verwijzen (geconfigureerd in launch.json) heeft een oudere versie geïnstalleerd (bijvoorbeeld 25.0.0.0). Omdat de server niet over de versie beschikt die we eisen, geeft hij een 404 terug.

  1. De serverversie identificeren: We kunnen de werkelijke versie controleren door naar de Business Central-website te gaan -> Help en ondersteuning -> Over.
  2. De app.json versoepelen: Open het bestand app.json in ons lokale project.
  3. We verlagen de vereiste minimale versie. We passen "application" en "platform" aan naar een versie waarvan we weten dat deze veilig en universeel is (bijv. 25.0.0.0).
  4. We verlagen de runtime-engine "runtime" naar een compatibele versie (bijv. 13.0 of 16.0).
  5. Cache legen: We verwijderen fysiek de inhoud van de verborgen map .alpackages.
  6. Opnieuw proberen: Voer AL: Download Symbols opnieuw uit. De terminal zou All reference symbols have been downloaded moeten weergeven.

Incident 2: Fout door spookafhankelijkheden (“API Reports”)

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

Bij het proberen om symbolen te downloaden of te compileren, geeft het systeem aan dat er een specifieke afhankelijkheid ontbreekt die we niet kunnen lokaliseren, zoals bijvoorbeeld: A package with publisher 'Microsoft', name 'API Reports - Finance', could not be found.

VS Code injecteert soms, bij het initialiseren van projecten via AL: Go!, afhankelijkheden van zeer specifieke modules (zoals geavanceerde financiële modules) in het blok "dependencies" van app.json. Als onze Sandbox-server die specifieke Microsoft-app niet heeft geïnstalleerd, zal het globale pakketproces in een kettingreactie mislukken.

We moeten de afhankelijkheden van ons project opschonen.

  1. We openen app.json.
  2. We zoeken naar de array "dependencies": [ ... ].
  3. Als we generieke integraties of eenvoudige API's ontwikkelen, verwijderen we de blokken met vreemde afhankelijkheden (zoals API Reports - Finance) volledig, waardoor de array leeg blijft [] of we alleen de kritieke afhankelijkheden van ons eigen bedrijf behouden.
  4. Cache van .alpackages wissen en symbolen opnieuw downloaden.

Incident 3: Mythe van mappen en naamgeving (CamelCase vs Snake_case)

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

Vraag van het team: “Faalt de AL-compiler als de project-rootmappen op mijn harde schijf (bijv. Consulta_Datos_Comercial) niet geschreven zijn in camelSensitive / CamelCase?”

Het absolute antwoord is NEE. De AL-compiler is niet hoofdlettergevoelig of gevoelig voor formaten in de fysieke namen van Windows-mappen.

  1. OS-bestandssysteem: Voor Visual Studio Code en Windows maakt het niet uit of het pad C:/Proyectos/Consulta_Datos of c:/proyectos/cOnSuLtAdAtOs is.
  2. Compilergedrag: Zodra we het build-commando uitvoeren, verpakt de engine de inhoud uitsluitend op basis van de metadata die is gedefinieerd binnen app.json (Eigenschappen "name" en "publisher"). De naam van je lokale directory wordt genegeerd en is irrelevant voor de cloudserver.

Aanbeveling voor naamgeving: Wij gebruiken de Snake_Case-conventie (underscores) in de directories (Entradas_Salidas_AL) uitsluitend voor menselijke leesbaarheid en visuele orde in onze Git-repositories, niet vanwege een technische verplichting van de compiler.

  • ✓ Opschonen: Preventief legen van de map .alpackages bij het uitvoeren van structurele wijzigingen in app.json.
  • ✓ Validatie: Absolute consistentie tussen de suite van in het manifest gedefinieerde afhankelijkheden en de in de cloud geïnstalleerde extensies.
  • ✓ Opvolging: Monitoring van de VS Code “AL Language” output channel voor een nauwkeurige diagnose van netwerkfouten.