Naar de inhoud
VANGELDER

Business Central

Upgrade-safe AL: de saaie gewoontes die zich terugbetalen

Business Central update volgens zijn eigen kalender, of jouw maatwerk er nu klaar voor is of niet. Wat event subscribers, table extensions en upgrade codeunits werkelijk doen op het moment van de update — en hoe het zich laat zien als die discipline ontbrak.

18 okt 2026 · 7 min leestijd

Business Central online update in een vast ritme: twee major releases per jaar, met minor updates ertussen. Ongeveer een maand voor elke major release test Microsoft automatisch de per-tenant extensions die in productie draaien tegen de komende versie, en mailt het de beheerders die als notification recipient staan opgegeven over elke incompatibiliteit. Breekt een extensie de update dan nog altijd, dan mislukt die, wordt de omgeving teruggezet en volgt een week later een nieuwe poging — tot aan de enforced update period.

Dat is meteen de hele ontwerpbeperking. Er is geen release die je kunt overslaan. Code die alleen werkt tegen de versie van Business Central waarop ze geschreven is, is geen afgewerkte code; het is een geplande storing met een datum erop. De gewoontes die dat ritme overleven zijn saai, goedkoop bij de start van een project, en duur om er halverwege nog in te bouwen.

Abonneer je, override niet

De base app is niet van jou om te wijzigen. Velden voeg je toe met table extensions, controls met page extensions, gedrag door je op events te abonneren. Een publisher weet niets van zijn subscribers, en precies die asymmetrie is het punt: Microsoft kan de binnenkant van een methode herschrijven zonder iemand te breken die aan de rand is aangehaakt.

IsHandled is een achterdeur, geen pattern. Microsofts eigen richtlijn is om het tot een absoluut minimum te beperken, en die redenering is de moeite om te lezen. Dat maar één subscriber het event mag afhandelen is een afspraak zonder handhaving — een tweede subscriber kan de vlag gewoon terugzetten. En wie een blok base code overslaat, zorgt er ook voor dat de events in dat blok niet meer afgevuurd worden, waardoor extensies breken die niets met jou te maken hadden. Er zitten meer dan 8.000 IsHandled-events in de base app, dus die achterdeur ligt altijd binnen handbereik.

Table extensions zijn goedkoop om te schrijven en duur om te wijzigen

Een table extension was vroeger een tweede tabel. Vanaf 2023 release wave 2 deelden alle extensies op één basistabel dezelfde companion table, en versie 29 (release wave 2 van 2026) bewaart alle velden van een AL-tabel in dezelfde databasetabel. De join is weg, de breedte niet: velden die je aan G/L Entry of Sales Line hangt, laden nog altijd mee bij elke read zonder partial records. Voor alles wat niet in lijsten of zoekresultaten hoeft, kost een gerelateerde tabel met een FlowField de basistabel niets.

Companion-velden zetten bulkbewerkingen uit. ModifyAll en DeleteAll worden normaal één SQL-statement. Ze vallen terug op een lus rij per rij zodra de tabel, op versies vóór 29, velden uit companion tables heeft — en ook zodra er subscribers zijn op OnBeforeModify, OnAfterModify, OnBeforeDelete en verwanten. Twee toevoegingen die er redelijk uitzien, en een batchroutine die in seconden klaar was wandelt nu door de tabel.

Velden toevoegen is makkelijk, terugnemen bijna onmogelijk. Een gepubliceerd veld verwijderen aanvaardt de sync engine niet. Een veld korter maken wordt geweigerd (AS0080, of AS0118 als het in de primaire sleutel zit), en het type wijzigen ook (AS0004). Zelfs langer maken wordt gemeld (AS0086), omdat een afhankelijke extensie die waarde aan een Text[50] kan toewijzen. De uitweg heeft altijd dezelfde vorm: zet het oude veld op ObsoleteState = Pending met reden en tag, voeg het nieuwe veld toe, verhuis de data in een upgrade codeunit, en haal het oude er een versie later uit. Rechtstreeks van No naar Removed springen is op zich al een fout (AS0115).

Sleutels hebben hun eigen regels. Sinds release wave 2 van 2026 (runtime 18.0) mag een key in een table extension velden uit de basistabel en uit de extensie combineren — op oudere versies niet — maar nooit velden uit een andere table extension, en Unique wordt daar niet ondersteund. Blijf ook van de primaire sleutel af: velden toevoegen, weghalen of van volgorde wisselen breekt het schema, net als DataPerCompany omzetten in welke richting dan ook.

Install code en upgrade code zijn twee verschillende dingen

Een upgrade codeunit is een codeunit met Subtype = Upgrade, en die geeft je precondition-, upgrade- en validatietriggers, in die volgorde, elk in een per-company- en een per-database-variant. De per-company-triggers lopen één keer per bedrijf, elk in hun eigen systeemsessie; de per-database-triggers één keer, zonder dat er een bedrijf openstaat. Een fout ergens in die reeks annuleert de hele extensie-upgrade.

Het onderscheid waar mensen op vastlopen: install code loopt niet bij een upgrade. Ze loopt bij een eerste installatie en bij het opnieuw installeren van een eerder verwijderde versie — niet wanneer een nieuwe versie een bestaande vervangt. Alles wat je in versie 2 aan de install codeunit toevoegt, bereikt dus alleen omgevingen die versie 2 van nul af installeren. Wie van versie 1 komt slaat het over, en dat gat merk je pas wanneer iemand een pagina opent die een setup-record verwacht dat nooit gezet is. De verwante valkuil: OnInstallAppPerCompany loopt alleen voor bedrijven die bij het installeren al bestaan, dus een bedrijf dat volgend jaar wordt aangemaakt krijgt niets van jouw setup. CodeCop meldt dat als AA0235; de oplossing is je daarnaast te abonneren op OnCompanyInitialize van codeunit Company-Initialize.

En dan het bestand dat niemand schrijft. Op de dag dat je versie 2 bouwt staat er nergens data die geüpgraded moet worden, dus voelt de upgrade codeunit als werk voor iets hypothetisch. Zes maanden later staat er data in een handvol bedrijven en is het veld dat je had moeten obsoleten uit de broncode verdwenen. Schrijf ze zolang dat oude veld er nog staat — dat is het enige moment waarop de data verhuizen vijf regels code is.

Upgrade code moet ook weten of ze al gelopen heeft, via de versiedata van de extensie of met upgrade tags. Die tags moet je registreren in de install codeunit en via OnGetPerCompanyUpgradeTags, anders draait je upgrade code bij verse installaties en bij elk nieuw bedrijf. Gebruik je meerdere upgrade codeunits, dan ligt hun onderlinge volgorde niet vast; elke codeunit moet op zichzelf kunnen staan.

Wat er stukgaat bij een update, en hoe je het merkt

Een compilerfout tijdens de validatie. De goede afloop. Microsoft zet objecten in de base app lang voor de verwijdering op ObsoleteState = Pending, en er gaan minstens twaalf maanden en twee versies overheen. Verwijzingen naar Pending geven warnings, naar Removed errors. De warnings waar je een jaar lang langs gescrold bent, zijn de errors die de update van een klant blokkeren. Met obsoleteTagMinAllowedMajorMinor in AppSourceCop maak je daar een falende build van.

Een synchronisatiefout. Het schema in de app past niet meer op de data in de database. De melding is bot en noemt het object — the field ‘X’ cannot be located; removing fields is not allowed — en de omgeving blijft staan tot iemand een build publiceert die wél synct.

Een geforceerde upgrade met jouw extensie eruit. Wanneer een productieomgeving niet geüpgraded raakt door een per-tenant extension, contacteert Microsoft de verkopende partner met richtlijnen. Lukt het nog altijd niet tegen de tijd dat de versie van de omgeving in haar enforced update period komt — na de updateperiode van vijf maanden en een maand gratieperiode — dan verwijdert Microsoft de extensie automatisch zodat de update kan slagen. De data in je tabellen blijft staan, maar de functionaliteit is weg bij de klant, en niemand daar heeft dat beslist.

Dataverlies waar je zelf om vroeg. syncMode = "ForceSync" duwt breaking changes door, waarbij doorgaans de data verdwijnt in de objecten waarvan het schema veranderde, en andere apps op jouw objecten mee kunnen sneuvelen. Legitiem bij een geplande upgrade waarbij je exact weet wat eruit gaat; de duurste sluipweg van het platform als het dient om een vastgelopen deployment door te drukken.

Niets, een tijdlang. Het faalgedrag zonder foutmelding: een override die nog altijd compileert, nog altijd draait, en niet langer overslaat wat hij oversloeg toen je hem testte, omdat de base code binnen dat blok herschreven is. Geen exception, geen signaal in telemetrie, geen mislukte update — alleen een cijfer waar iemand weken later naar kijkt.

De code is van de klant

Per-tenant extensions horen bij één omgeving, en jij bepaalt wanneer ze gepubliceerd, geïnstalleerd, geüpgraded of verwijderd worden. Houd de app-ID gelijk en verhoog het versienummer: hercompileren zonder dat nummer op te trekken levert een nieuw pakket op voor een ID en versie die al uitgerold zijn, en de upload wordt geweigerd.

We bouwen PTE’s zo dat de broncode eigendom van de klant zelf wordt — geen vendor lock-in. Die belofte is alleen iets waard als de code eronder het waard is om te bezitten. Een extensie die bij elkaar gehouden wordt door IsHandled-overrides en een table extension waar niemand nog aan durft, is juridisch van de klant en praktisch van niemand. Overdraagbaarheid is geen clausule in een contract. Het is de vraag of de volgende ontwikkelaar het ding kan lezen, publiceren tegen de release van volgend voorjaar, en terugdraaien.

Alle insights