Umbraco 13 naar 17 upgraden: checklist en breaking changes per versie

Een upgrade van Umbraco 13 naar 17 is geen gewone update, omdat u in één keer vier major-versies overslaat, elk met eigen breaking changes. In versie 14 is de backoffice volledig vervangen: AngularJS verdwijnt, eigen backoffice-extensies moeten opnieuw gebouwd worden, en macro's, Nested Content, Grid Layout, de oude Media Picker en XPath zijn verwijderd. Versie 15 brengt een nieuwe content-cache en een nieuw opslagformaat voor blocks. In versie 16 is TinyMCE uit de kern gehaald en worden rich text editors omgezet naar Tiptap. Versie 17 draait op .NET 10 en slaat systeemdatums op in UTC. Een goede upgrade begint daarom met een inventaris op uw huidige 13-site, niet met het ophogen van NuGet-packages.

Ik werk sinds 2010 met Umbraco en heb deze checklist opgesteld vanuit de officiële version specific upgrades-documentatie van Umbraco, aangevuld met wat ik in de praktijk tegenkom. Wilt u dat ik meekijk naar uw eigen site? Op mijn pagina over Umbraco upgraden met een gratis inspectie leest u hoe dat werkt.

Waarom haast geboden is

Umbraco 13 is een LTS-versie, maar de ondersteuning loopt af. Volgens de Long Term Support and End of Life-pagina van Umbraco stopt de ondersteuning voor Umbraco 13 op 14 december 2026. Daarna komen er geen beveiligingsupdates meer. Wat dat concreet betekent voor uw site, heb ik uitgewerkt in het artikel over het einde van de ondersteuning van Umbraco 13.

Overweegt u om meteen door te gaan naar Umbraco 18? Dat kan vanaf 13 niet rechtstreeks: versie 18 upgradet alleen vanaf 16.4. De afweging tussen 17 en 18 staat in Umbraco 18 of 17: waar upgradet u naartoe?

Wat er per versie verandert

Hieronder de breaking changes die voor een gemiddelde bedrijfswebsite het meeste werk opleveren. De volledige lijst per versie staat in de Umbraco-documentatie. Lees die ook, want daar staan ook de minder zichtbare API-wijzigingen.

Umbraco 14: de nieuwe backoffice

Dit is de versie die het meeste werk geeft. De backoffice is opnieuw gebouwd met webcomponents en TypeScript. Alles wat u in AngularJS heeft gemaakt (een eigen dashboard, een custom property editor, een aangepaste sectie, een package.manifest) werkt niet meer en moet opnieuw geschreven worden als extensie met een umbraco-package.json-manifest. Ook backoffice-controllers die op de oude API leunden, moeten over naar de nieuwe Management API.

Daarnaast verdwijnen onderdelen waar veel oudere sites op draaien:

• Macro's: vervangen door blocks in de rich text editor.
• Nested Content: vervangen door Block List.
• Grid Layout: vervangen door Block Grid.
• De oude Media Picker: vervangen door Media Picker 3.
• XPath, bijvoorbeeld als startpunt van een Multinode Treepicker: vervangen door Dynamic Root.

De fout die ik het vaakst zie: eerst upgraden en dan pas ontdekken dat de content in een Nested Content- of Grid-veld niet meer te bewerken is. Zet die editors om terwijl u nog op 13 zit. Daar bestaan tools voor, zoals uSync Migrations van Jumoo, maar controleer na de omzetting altijd steekproefsgewijs de content en de views die de data renderen.

Umbraco 15: nieuwe cache en nieuw block-formaat

De oude NuCache, die alle gepubliceerde content bij het opstarten in het geheugen laadde, is vervangen door een nieuwe content-cache. Voor de meeste sites is dat sneller bij het opstarten. Code die bij elk verzoek door de hele contentboom loopt (een menu dat via Descendants() alle pagina's ophaalt, een zoekfunctie zonder Examine) kan wel trager worden. Dat moet u meten, niet aannemen.

Ook block-data wordt in een nieuw formaat opgeslagen. Bij de upgrade zet Umbraco alle bestaande Block List-, Block Grid- en rich text-blocks om. Op een grote site kan dat lang duren, en de site is in die tijd niet beschikbaar. Draai de upgrade daarom eerst op een kopie van de productiedatabase en noteer hoe lang de migratie duurt. Dan weet u hoe lang uw onderhoudsvenster moet zijn.

Umbraco 16: van TinyMCE naar Tiptap

Tiptap kwam al als optie in versie 15. In 16 is TinyMCE uit de kern verwijderd en worden bestaande rich text editors automatisch omgezet naar Tiptap. Wilt u dat (nog) niet, dan kunt u vóór de upgrade een extern TinyMCE-package installeren. Let op eigen TinyMCE-plugins, aangepaste stylesheets voor de editor en opmaak die redacteuren via de broncode-weergave hebben ingevoerd. Vergelijk na de omzetting een aantal pagina's met veel opmaak, zoals tabellen en ingesloten video's.

Umbraco 17: .NET 10, UTC en HTTPS

Versie 17 is de nieuwe LTS en draait op .NET 10. Umbraco 13 draait op .NET 8, dus uw hosting, build-server en eventuele Docker-images moeten mee. Systeemdatums worden voortaan in UTC opgeslagen. Code die ervan uitgaat dat een datum in Nederlandse tijd staat (geplande publicaties, exports, "nieuw sinds"-labels, koppelingen met een CRM) kan een of twee uur verschuiven. Daarnaast staat HTTPS standaard aan, wat lokale ontwikkelomgevingen en interne testservers zonder certificaat kan raken.

Checklist vóór de upgrade

Deze lijst kunt u kopiëren of printen en per punt afvinken. Ik loop hem bij elke inspectie in deze volgorde door.

Downloadbare checklist: Umbraco 13 naar 17

1. Versie vastleggen: noteer de exacte Umbraco-versie (13.x) en update eerst naar de laatste 13-patch.
2. Packages inventariseren: maak een lijst van alle NuGet- en Umbraco-packages, met per package of er een versie voor Umbraco 17 is, wie het onderhoudt en wat het alternatief is als er geen versie komt.
3. Eigen backoffice-code: zoek in de App_Plugins-map naar package.manifest-bestanden en AngularJS-code. Alles wat u vindt, moet opnieuw gebouwd worden.
4. Property editors: loop per documenttype alle datatypes na. Markeer Nested Content, Grid Layout, de oude Media Picker en custom editors.
5. Macro's: tel hoeveel macro's er zijn en op hoeveel pagina's ze in de rich text editor staan.
6. XPath: controleer Multinode Treepicker-configuraties en eigen code op XPath-queries.
7. Rich text editor: noteer eigen TinyMCE-plugins, stylesheets en toolbar-instellingen.
8. Umbraco Forms en licenties: controleer welke Forms-versie u gebruikt, of uw licentie geldig is voor de nieuwe versie en of er eigen veldtypes of workflows zijn. Hetzelfde geldt voor andere betaalde packages.
9. Code met datums: zoek naar DateTime.Now en vergelijkbare code die van lokale tijd uitgaat.
10. Hosting en .NET: controleer of uw hosting .NET 10 ondersteunt, en of de build-pipeline en deployment-scripts aangepast moeten worden.
11. Integraties: noteer koppelingen met CRM, nieuwsbriefsoftware, betaalproviders en API's van derden.
12. Back-up: maak een volledige back-up van database, mediabestanden en code, en test of u die back-up werkelijk kunt terugzetten.
13. Testomgeving: zet een kopie op met een recente kopie van de productiedatabase.
14. Content freeze plannen: spreek met redacteuren af wanneer er niets meer gepubliceerd wordt.

Stappenplan van de upgrade

1. Werk de site bij naar de laatste 13.x-versie en los alle waarschuwingen over verouderde (obsolete) code op. Wat in 13 als obsolete gemarkeerd staat, is in latere versies vaak verdwenen.
2. Zet legacy editors om op versie 13: Nested Content naar Block List, Grid Layout naar Block Grid, macro's naar blocks, de oude Media Picker naar Media Picker 3. Pas de views aan en controleer de content.
3. Maak een volledige back-up en zet een kopie van de site op een aparte omgeving.
4. Pas het project aan: target framework naar net10.0, Umbraco.Cms-packages naar versie 17, en alle andere packages naar hun 17-compatibele versie. Vervang of verwijder packages zonder 17-versie.
5. Los compileerfouten op. Verwacht gewijzigde namespaces, verwijderde services en andere methodenamen.
6. Herbouw backoffice-extensies als webcomponents met een umbraco-package.json-manifest.
7. Draai de upgrade op de kopie. Umbraco voert de databasemigraties uit bij het opstarten (eventueel unattended). Houd de logbestanden in de gaten en noteer hoe lang de migratie duurt.
8. Bouw de Examine-indexen opnieuw op en controleer de cache.
9. Test volledig volgens de testlijst hieronder.
10. Plan de productie-upgrade: content freeze, verse back-up, upgrade uitvoeren, rooktest, freeze opheffen. Houd een terugvalplan klaar: als de rooktest faalt, zet u de back-up en de oude code terug.

Testen na de upgrade

Een upgrade die compileert en opstart, is nog niet klaar. Dit test ik altijd, zowel aan de voorkant als in de backoffice:

• Inloggen in de backoffice met elke gebruikersgroep, inclusief rechten per sectie.
• Elk documenttype openen, bewerken, opslaan en publiceren.
• Block List- en Block Grid-velden: blocks toevoegen, verplaatsen en verwijderen.
• Rich text: pagina's met tabellen, ingesloten media en voormalige macro's vergelijken met de oude site.
• Formulieren: inzenden, e-mailnotificatie ontvangen, inzending terugvinden in de backoffice.
• Zoekfunctie en Examine-resultaten.
• Media: uploaden, bijsnijden, image cropper-instellingen.
• URL's, redirects en 404-pagina. Een gewijzigde URL kost u posities in Google.
• Meertalige content en domeininstellingen per taal.
• Geplande publicaties en alles wat met datums werkt (UTC).
• Leden-login, als uw site een afgeschermd deel heeft.
• Koppelingen met externe systemen.
• Sitemap, robots.txt en canonieke URL's.
• Laadtijd van de zwaarste pagina's, vóór en na de upgrade.
• Logbestanden: geen nieuwe fouten of waarschuwingen na een dag normaal gebruik.

Wat kost een upgrade van Umbraco 13 naar 17?

Ik geef een vaste prijs na een gratis inspectie van uw site. Een eenvoudige site blijft in de praktijk meestal onder €4.000. Of uw site eenvoudig is, hangt af van wat de checklist hierboven oplevert:

• het aantal eigen backoffice-extensies dat opnieuw gebouwd moet worden;
• packages zonder versie voor Umbraco 17, waarvoor een vervanger nodig is;
• hoeveel Nested Content, Grid Layout en macro's er omgezet moeten worden;
• eigen Umbraco Forms-veldtypes en -workflows;
• koppelingen met externe systemen;
• de hoeveelheid content, omdat die de migratietijd bepaalt.

Gebruikt u Umbraco Forms en twijfelt u of u daarbij wilt blijven, lees dan mijn vergelijking van CampaignCanvas en Umbraco Forms. Een upgrade is een logisch moment om die keuze opnieuw te maken.

Na de upgrade kan ik de site hosten en onderhouden. Hosting kost €39 per maand. Wilt u dat ik ook updates, kleine wijzigingen en vragen oppak, dan is er WebCare. Beide staan op de productpagina.

Zelf doen of laten doen?

Zelf doen is goed te doen als u een eigen developer heeft die .NET en TypeScript beheerst, uw site weinig packages gebruikt en er geen maatwerk in de backoffice zit. Reken dan wel op leeswerk in de documentatie van vier versies, en plan de upgrade niet in een drukke periode.

Laten doen is verstandig als uw site eigen dashboards of property editors heeft, als er nog Nested Content, Grid Layout of macro's in zitten, of als niemand in huis weet hoe de site destijds gebouwd is. De meeste tijd zit dan in het uitzoeken, niet in het ophogen van versies.

Bij mij werkt u direct met de persoon die de upgrade uitvoert. Ik ben een eenmanspraktijk, dus geen accountmanager en geen doorverwijzing naar een junior. Ik bouw websites sinds 1996 en werk sinds 2010 met Umbraco, dus ik ken zowel de oude AngularJS-backoffice als de nieuwe.

Wilt u weten wat er bij uw site breekt? Vraag een gratis inspectie voor uw Umbraco-upgrade aan. U krijgt daarna een vaste prijs, zodat u weet waar u aan toe bent voordat de ondersteuning van versie 13 stopt. Meer over mij en mijn werk vindt u op datapad.nl.

Veelgestelde vragen

Wanneer stopt de ondersteuning van Umbraco 13?

Volgens de Long Term Support and End of Life-pagina op umbraco.com stopt de ondersteuning voor Umbraco 13 op 14 december 2026. Daarna verschijnen er geen beveiligingsupdates meer voor die versie.

Kan ik van Umbraco 13 direct naar Umbraco 18 upgraden?

Nee. Umbraco 18 upgradet alleen vanaf versie 16.4. Vanaf 13 gaat u eerst naar 17 (of minimaal 16.4) en daarna eventueel naar 18.

Wat zijn de grootste breaking changes van Umbraco 13 naar 17?

De nieuwe backoffice in versie 14 (AngularJS verdwijnt, eigen extensies moeten opnieuw gebouwd worden, macro's, Nested Content, Grid Layout, de oude Media Picker en XPath zijn verwijderd), de nieuwe content-cache en het nieuwe block-formaat in 15, de overstap van TinyMCE naar Tiptap in 16, en .NET 10 met datums in UTC in 17.

Moet ik content opnieuw invoeren na de upgrade?

Normaal niet. Umbraco migreert de database bij de upgrade. Content in Nested Content, Grid Layout of macro's moet u wel eerst omzetten naar Block List, Block Grid of blocks, het liefst nog op versie 13. Controleer daarna steekproefsgewijs of alles goed is overgekomen.

Wat kost een upgrade van Umbraco 13 naar 17?

Bij Datapad krijgt u een vaste prijs na een gratis inspectie. Een eenvoudige site blijft meestal onder €4.000. De prijs hangt af van eigen backoffice-code, packages zonder versie voor Umbraco 17, de hoeveelheid om te zetten legacy-content en koppelingen met andere systemen.