Uppgradera Umbraco 13 till 17: vad som faktiskt går sönder

Supporten för Umbraco 13 upphör i december 2026. Supporten för Umbraco 16 upphör i juni 2026. Kör ni en 13-sajt är LTS-klockan redan det minst intressanta problemet – den verkliga frågan är vad som faktiskt går sönder mellan här och 17, och om teamet är förberett på det.

Det ärliga svaret: mer än vad de flesta uppgraderingsartiklar erkänner. Det här är ingen minor-uppdatering. Mellan 13 och 17 passerar ni backoffice-omskrivningen, ett helt byte av JSON-serialisering, borttagningen av flera property editors och hela makrosystemet, samt två .NET-versionshopp. Att behandla det som en rutinmässig NuGet-uppdatering är hur projekt slutar med en trasig backoffice i produktion.

Här är vad som faktiskt förändras, version för version, och vad det betyder för ett riktigt projekt – inte en demosajt.

Kan man hoppa direkt från 13 till 17?

Tekniskt sett, ja. Umbracos egen dokumentation säger att direkta uppgraderingar över flera major-versioner stöds – ni får inga deprecation-varningar för versionerna ni hoppade över, men själva uppgraderingen kommer att köras. I praktiken, för allt utöver en liten broschyrsajt, bör det behandlas som en stegvis migrering: 13 → 14 → 15 → 16 → 17, med testning i varje steg. De brytande förändringarna staplas på varandra, och att isolera vilken version som gjorde sönder er egna property editor eller er makroberoende partial view är mycket enklare ett steg i taget än efter ett femversionshopp.

Är kodbasen ren och har få beroenden är ett direkt hopp med grundlig regressionstestning försvarbart. Har ni egna AngularJS-baserade backoffice-tillägg, Nested Content, Grid, eller makron någonstans i mixen – budgetera för den stegvisa vägen.

Umbraco 14: backoffice byggs om från grunden

Det här är versionen som gör sönder flest projekt, för det är ingen refaktorering – det är ett byte.

AngularJS är borta. Hela backoffice-gränssnittet byggdes om som Web Components med Lit och Umbraco UI Library (“Bellissima”). Egna backoffice-tillägg, dashboards eller property editor-gränssnitt byggda mot det gamla AngularJS-ramverket måste skrivas om, inte lappas ihop. Komponentnamn ändrades i grunden (umb-button → uui-button, umb-box → uui-box), egna ikoner behöver den nya extension-typen ”icons”, och egna översättningar behöver en ”localization”-extension.

API-lagret ändrades under er. De gamla /umbraco/api-backoffice-controllerna ersätts av Management API. UmbracoAuthorizedApiController och UmbracoAuthorizedJsonController är borta. UmbracoApiController kompilerar fortfarande men är obsolet. Egna backoffice-riktade endpoints behöver flyttas till ManagementApiControllerBase eller en vanlig ASP.NET Core-controller.

Newtonsoft.Json är ute, System.Text.Json är inne. Det låter som rörledningsarbete tills ni har egna property editors eller API-controllers med serialiseringsantaganden inbyggda – System.Text.Json är strängare som standard, och kod som tidigare tyst tolererade lös JSON under Newtonsoft kan kasta undantag där den inte gjorde det förut. Det här kräver riktig regressionstestning, inte en snabb titt i changeloggen.

Nested Content, den gamla Grid, den gamla Media Picker och Macros tas alla bort. Inte fasas ut – tas bort. Finns någon av dessa i era innehållsmodeller måste de migreras till Block List, Block Grid eller MediaPicker3 innan ni rör 14. Macros och Partial View Macros har ingen direkt ersättning; RTE-makron behöver konverteras till Block-syntax, och partial view-makron behöver konverteras till element types eller vanliga partial views. På en innehållstung sajt är den här migreringen oftast den enskilt största posten i hela uppgraderingen.

Umbraco 15: cache-modellen ändras

Snapshot-arkitekturen är borta. IPublishedSnapshot och IPublishedSnapshotAccessor tas bort helt. Kod som injicerar dessa direkt – vanligt i äldre egen kod och en del tredjepartspaket – behöver flyttas till IPublishedContentCache eller IPublishedMediaCache. Det här är lätt att missa eftersom det kompilerar utan problem – ända tills det inte gör det.

.NET 9. ASP.NET Core 9 komprimerar statisk JS/CSS automatiskt, vilket kan dubbleras med eventuell komprimerings-middleware ni redan kör. Hanterar ni er egen asset-pipeline, kontrollera dubbelkomprimering och sätt CompressionEnabled till false i projektfilen vid behov.

ModelsBuilder-modellerna behöver byggas om helt i den här versionen – rensa mappen umbraco/Data/TEMP/InMemoryAuto i stället för att anta att en ren omkompilering fångar allt.

Umbraco 16: TinyMCE är borta

TinyMCE tas bort helt, inte fasas ut, på grund av licensändringen – innehåll migreras automatiskt till TipTap vid uppgradering. Använder era redaktörer egna TinyMCE-plugins eller specifika verktygsfältskonfigurationer, kontrollera dem innan uppgradering; TipTaps kontextuella style-menyer var inte i full paritet vid den här releasen. Behöver ni behålla TinyMCE specifikt måste ni installera ett tredjepartspaket innan uppgraderingen, inte efter.

Paketmigreringar blev asynkrona och är binärt inkompatibla med byggen från 15-eran – egna paket med egna migreringsplaner behöver byggas om mot 16, inte bara omkompileras.

Umbraco 17: LTS-versionen ni faktiskt uppgraderar mot

Umbraco 17 är den nya LTS-versionen och körs på .NET 10. Några förändringar värda att känna till innan ni landar här:

• HTTPS är aktiverat som standard. Antog er appsettings.json HTTP i vissa miljöer, kontrollera det explicit.
• Swagger är borta, ersatt av OpenAPI – API-dokumentationen flyttar från /swagger till /openapi.
• Systemdatum lagras nu i UTC, med en automatisk migrering och konfigurerbar tidszonshantering. Allt som gör manuell datumaritmetik mot lokal tid behöver en granskning.
• XPath-stöd i Multinode Tree Picker tas bort, och XPath-baserade picker-konfigurationer nollställs tyst vid uppgradering i stället för att ge ett fel. Konfigurera om gamla XPath-pickers med Dynamic Root innan ni uppgraderar – inte efter att ni upptäcker tomma pickers i produktion.
• Beroendeuppdateringar värda att kontrollera mot era egna paket: NPoco 5.7.1 → 6.1.0 (major-version), Serilog hosting 9.0.0 → 10.0.0.

Inget av detta är svårt var för sig. Tillsammans, på en sajt som samlat på sig flera års egna editors och innehållsmodeller, blir det ett riktigt utvecklingsarbete.

Vad det här faktiskt kostar på ett riktigt projekt

Mönstret genom alla fem versionerna är konsekvent: Umbraco fortsätter ta bort vägarna som lät er skjuta upp ett beslut – gamla editors, makron, AngularJS-tillägg, lös JSON-hantering, XPath-konfigurationer. Varje borttagning är försvarbar för sig. Staplade över fyra major-versioner blir de ett projekt som ser ut som en rutinuppgradering på ticketen men beter sig som en delvis ombyggnad av er innehållsarkitektur och era backoffice-tillägg.

Teamen som bränner sig är de som scopar det här som ”uppdatera NuGet-paketen och se vad som händer”. Teamen som inte gör det är de som granskar först och kontrollerar:

• Vilka content types som fortfarande använder Nested Content, Grid eller den gamla Media Picker.
• Vilka mallar eller RTE-fält som är beroende av makron.
• Om några egna backoffice-tillägg fortfarande är AngularJS.
• Om någon kod injicerar IPublishedSnapshot direkt, eller har serialiseringslogik som förutsätter Newtonsofts släpphänthet.
• Om några pickers använder XPath.

Gör den granskningen innan ni rör ett versionsnummer, inte under uppgraderingen.

En vettig uppgraderingsstrategi

Granska först, uppgradera sedan. Katalogisera varje egen property editor, backoffice-tillägg, makro och gammal content type innan ni börjar – det är det arbetet som faktiskt avgör tidsplanen, inte själva paketuppdateringen.

Stega uppgraderingen om inte kodbasen verkligen är ren: 13 till 14 till 15 till 16 till 17, med ett fungerande, testat bygge i varje steg. Det är långsammare än ett enda hopp, men det förvandlar ”något gick sönder någonstans i fem major-versioner” till ”något gick sönder i just den här versionen”, vilket är ett felsökningsbart problem i stället för ett gissningsspel.

Budgetera riktig tid för migrering av innehållsmodeller. Borttagningen av Nested Content, Grid och makron i v14 är oftast den enskilt största kostnaden i hela uppgraderingen, och den som lättast underskattas eftersom den ser ut som en innehållsuppgift snarare än en utvecklaruppgift.

Testa backoffice, inte bara frontend. Ett grönt bygge betyder inte att era egna dashboards, property editors eller backoffice-tillägg fortfarande renderas – Bellissima gjorde sönder mycket som aldrig rörde den publika sajten.

Varför det här fortsätter hända

Inget av det här handlar om att Umbraco är oansvariga. Att ta bort AngularJS, TinyMCE och gamla editors är rätt beslut på lång sikt – det blir en renare, snabbare och säkrare plattform på andra sidan. Men det betyder att varje projekt som byggs utan uppgraderingsdisciplin i åtanke samlar på sig en avbetalningsskuld, och den skulden förfaller till betalning i exakt den typen av flerversionshopp den här artikeln handlar om.

Det är argumentet för att starta nya projekt – och ombygga gamla – på en grund som inte samlar på sig den skulden från början: aktuella beroenden, inga gamla editors inbakade i innehållsmodellen, inga AngularJS-baserade backoffice-tillägg att skriva om senare. Det är betydligt billigare att hålla sig aktuell en LTS-version i taget än att möta exakt den här listan av brytande förändringar igen om tre år.