Skip to content

Upgrading Umbraco.Cms.Web.Website 16 to 17

Breaking16.5.1 → 17.8.0Breaking35Security29Deprecated8New164Changed210Fixed866Other247

Full comparisonBack to Umbraco.Cms.Web.Website
Fetching 48 releases from GitHub…45 / 48
BreakingUpgrade verdict

35 breaking changes and 29 security fixes.

In plain terms
  • The old entityType field is no longer included in document property values.
  • Sites now enforce HTTPS unless you explicitly turn that requirement off.
  • Removes obsoleted code for properties and validators in v17.
  • Adds property level default segment fallback.
Must act Top 5 of 72 that need code or config changes

Target frameworks requirement changed in 17.0.0-beta: net9.0 → net10.0.

Adds asp.versioning.mvc 8.1.1, asp.versioning.mvc.apiexplorer 8.1.1, dazinator.extensions.fileproviders 2.0.0, examine 3.10.0, examine.core 3.10.0, htmlagilitypack 1.13.0, k4os.compression.lz4 1.3.8, mailkit 4.18.1, markdig 0.45.0, markdown 2.2.1, messagepack 3.1.11, microsoft.extensions.caching.abstractions 10.0.12, microsoft.extensions.caching.hybrid 10.10.0, microsoft.extensions.caching.memory 10.0.12, microsoft.extensions.configuration.abstractions 10.0.12, microsoft.extensions.configuration.json 10.0.12, microsoft.extensions.dependencyinjection 10.0.12, microsoft.extensions.fileproviders.embedded 10.0.12, microsoft.extensions.fileproviders.physical 10.0.12, microsoft.extensions.hosting.abstractions 10.0.12, microsoft.extensions.http 10.0.12, microsoft.extensions.identity.core 10.0.12, microsoft.extensions.identity.stores 10.0.12, microsoft.extensions.logging 10.0.12, microsoft.extensions.options 10.0.12, microsoft.extensions.options.configurationextensions 10.0.12, microsoft.extensions.options.dataannotations 10.0.12, miniprofiler.aspnetcore.mvc 4.5.4, miniprofiler.shared 4.5.4, ncrontab 3.4.0, npoco 6.3.0, openiddict.abstractions 7.7.1, serilog 4.4.0, serilog.aspnetcore 9.0.0, serilog.enrichers.process 3.0.0, serilog.enrichers.thread 4.0.0, serilog.expressions 5.0.0, serilog.extensions.hosting 9.0.0, serilog.formatting.compact 3.0.0, serilog.formatting.compact.reader 4.0.0, serilog.settings.configuration 9.0.0, serilog.sinks.async 2.1.0, serilog.sinks.file 7.0.0, serilog.sinks.map 2.0.0, system.linq.async 7.0.1, system.security.cryptography.pkcs 10.0.13, system.security.cryptography.xml 10.0.13.

What you must change

Breaking35
Removes the deprecated entityType from document property values.
entityType
17.2.0GitHub ReleaseSummarizedView source
Requires HTTPS by default, with an opt-out available.
17.0.0-rc3GitHub ReleaseSummarizedView source
Removes obsoleted code for properties and validators in v17.
17.0.0-betaGitHub ReleaseSummarizedView source
Adds property level default segment fallback.
17.0.0-betaGitHub ReleaseSummarizedView source
Removes client-side v17 deprecated code.
17.0.0-betaGitHub ReleaseSummarizedView source
Removes the SectionSidebarContextMenu element and its interaction methods.
SectionSidebarContextMenu
17.0.0-betaGitHub ReleaseSummarizedView source
Refactors backoffice sections with a default element and context API.
17.0.0-betaGitHub ReleaseSummarizedView source
Removes obsoleted code from Umbraco.Extension.
17.0.0-betaGitHub ReleaseSummarizedView source
Removes obsoleted code from Umbraco.Examine.
17.0.0-betaGitHub ReleaseSummarizedView source
Removes obsoleted code from Umbraco.Infrastructure.
17.0.0-betaGitHub ReleaseSummarizedView source
Removes obsoleted code from Cms.Api.
17.0.0-betaGitHub ReleaseSummarizedView source
Removes obsoleted code from Umbraco.Web.
17.0.0-betaGitHub ReleaseSummarizedView source
Removes obsoleted code from Umbraco.Cms.Core.Cache and .Routing.
17.0.0-betaGitHub ReleaseSummarizedView source
Removes obsoleted code from Umbraco.Core.
17.0.0-betaGitHub ReleaseSummarizedView source
Application URL auto-detection from the Host header becomes opt-in via the new ApplicationUrlDetection setting.
ApplicationUrlDetectionApplicationMainUrlUmbracoApplicationUrl
17.4.0GitHub ReleaseSummarizedView source
Updates MailKit to 4.15.1, requiring core changes for nullability constraints; projects using MailKit or MimeKit may be affected.
MailKitMimeKit
17.3.0GitHub ReleaseSummarizedView source
Updates MailKit to 4.15.1.
MailKit
17.3.0GitHub ReleaseSummarizedView source
Updates Swashbuckle to v10, a breaking dependency change; the CMS still generates OpenAPI 3.0.4 schemas.
Swashbuckle
17.0.0-rc4GitHub ReleaseSummarizedView source
Completes the renaming of SignProviders to FlagProviders.
SignProvidersFlagProviders
17.0.0-rc2GitHub ReleaseSummarizedView source
Cleans up extension methods.
17.0.0-betaGitHub ReleaseSummarizedView source
Fixes models builder generating different types for color picker value.
17.0.0-betaGitHub ReleaseSummarizedView source
Reworks audit entries.
17.0.0-betaGitHub ReleaseSummarizedView source
Updates the existing date/time property editor to provide a kind of unspecified.
17.0.0-betaGitHub ReleaseSummarizedView source
Uses the audit service instead of the repository directly in services.
17.0.0-betaGitHub ReleaseSummarizedView source
Fixes nullability of return types that can be non-null.
17.0.0-betaGitHub ReleaseSummarizedView source
Changes methods in ServiceCollectionExtensions to return IServiceCollection instead of void.
ServiceCollectionExtensionsIServiceCollection
17.0.0-betaGitHub ReleaseSummarizedView source
Moves current-user related entities from the 'user' package to the 'current-user' package.
17.0.0-betaGitHub ReleaseSummarizedView source
Quotes table and column names and uses NPoco extensions over raw SQL in repositories.
NPoco
17.0.0-betaGitHub ReleaseSummarizedView source
Relocates the Tiptap external extensions/package.
Tiptap
17.0.0-betaGitHub ReleaseSummarizedView source
Adds the ability to set the telemetry level during unattended install.
17.0.0-betaGitHub ReleaseSummarizedView source
Segmentation backoffice now uses the enhanced endpoint to fetch segment options for documents based on GUID.
17.0.0-betaGitHub ReleaseSummarizedView source
Updates server dependencies.
17.0.0-betaGitHub ReleaseSummarizedView source
Changes the member type container in the management API.
17.0.0-betaGitHub ReleaseSummarizedView source
Implements distributed background jobs for load balancing.
17.0.0-betaGitHub ReleaseSummarizedView source
Changes the property editor data source.
17.0.0-betaGitHub ReleaseSummarizedView source
Security29
Updates SixLabors.ImageSharp to 3.2.0 and ImageSharp.Web to 3.3.0 to take Six Labors' security fixes.
SixLabors.ImageSharpSixLabors.ImageSharp.Web
17.8.0-rcGitHub ReleaseSummarizedView source
Pins System.Security.Cryptography.Pkcs and .Xml to 10.0.13 to resolve vulnerability warnings.
System.Security.Cryptography.PkcsSystem.Security.Cryptography.Xml
17.8.0-rcGitHub ReleaseSummarizedView source
Signs out disabled or locked out users in the Management API instead of issuing new tokens.
17.8.0-rcGitHub ReleaseSummarizedView source
Fixes an authorization bypass that let low-privileged users delete media outside their start node.
17.7.1GitHub ReleaseSummarizedView source
Fixes backoffice users being able to read content outside their start node via the document version endpoints.
17.7.1GitHub ReleaseSummarizedView source
Fixes unauthenticated SignalR hubs disclosing content identifiers and editorial activity.
SignalR
17.7.1GitHub ReleaseSummarizedView source
Fixes upload file extension restrictions not being enforced for file names ending in a period.
17.7.1GitHub ReleaseSummarizedView source
Fixes incorrect authorization that let Content-only backoffice users modify Templates, enabling remote code execution.
17.6.2GitHub ReleaseSummarizedView source
Fixes insufficient authorization on Management API search endpoints.
17.6.2GitHub ReleaseSummarizedView source
Updates MessagePack to 3.1.7 to address security advisories.
MessagePack
17.6.0GitHub ReleaseSummarizedView source
Pins SQLitePCLRaw.lib.e_sqlite3 to a non-vulnerable version.
SQLitePCLRaw.lib.e_sqlite3
17.6.0GitHub ReleaseSummarizedView source
Addresses a vulnerability involving expansion of property values for protected, picked content.
17.5.3GitHub ReleaseSummarizedView source
Adds a localize.htmlString() helper to prevent XSS in HTML-rendered translations in the backoffice.
localize.htmlString()
17.4.0GitHub ReleaseSummarizedView source
Pins System.Security.Cryptography.Xml to resolve a vulnerability warning.
System.Security.Cryptography.Xml
17.4.0GitHub ReleaseSummarizedView source
Removes the token cookie if decryption fails, mitigating issue #16107.
17.4.0GitHub ReleaseSummarizedView source
Prevents an XXE opportunity in OEmbedProviderBase.
OEmbedProviderBase
17.4.0GitHub ReleaseSummarizedView source
Validates the redirect URL in public surface controllers.
17.4.0GitHub ReleaseSummarizedView source
Auto-generates an HMAC secret key for new installs to make Umbraco more secure by default; not forced for upgrades.
17.3.0GitHub ReleaseSummarizedView source
Auto-generates an HMAC secret key for new installs in imaging configuration.
17.3.0GitHub ReleaseSummarizedView source
Updates MailKit because the previously depended-on version has a security vulnerability raised against it.
MailKit
17.3.0-rc3GitHub ReleaseSummarizedView source
Fixes a privilege escalation issue relating to user group memberships.
17.2.2GitHub ReleaseSummarizedView source
Fixes an XSS vulnerability involving property type descriptions.
17.2.2GitHub ReleaseSummarizedView source
Fixes authorization checks on node domain access.
17.2.2GitHub ReleaseSummarizedView source
Updates Microsoft packages to 10.0.1 and pins vulnerable transitive dependencies.
17.2.0GitHub ReleaseSummarizedView source
Adds protection to restrict access to media in the recycle bin.
17.1.0GitHub ReleaseSummarizedView source
Marks the UMB-DEBUG cookie as HttpOnly and Secure in debug mode.
UMB-DEBUG
17.1.0GitHub ReleaseSummarizedView source
Moves backoffice login access and refresh tokens to secure cookies.
17.0.0-rc3GitHub ReleaseSummarizedView source
Redacts backoffice PKCE codes from the server.
17.0.0-rc3GitHub ReleaseSummarizedView source
Updates the node development dependency to the latest secure version of major 17.
17.0.0-rc2GitHub ReleaseSummarizedView source

Deprecations to plan for

Deprecated8
Retires the legacy tree-item-children collection view.
tree-item-children
17.8.0-rcGitHub ReleaseSummarizedView source
Obsoletes ServerVariablesParsingNotification, which is no longer published.
ServerVariablesParsingNotification
17.8.0-rcGitHub ReleaseSummarizedView source
Cleans up and deprecates the Block Rich Text Editor implementation.
17.7.0GitHub ReleaseSummarizedView source
Marks auth services already removed in V19 as obsolete.
17.7.0GitHub ReleaseSummarizedView source
Deprecates the unused HttpClient registered with certificate validation bypass.
HttpClient
17.5.0-rcGitHub ReleaseSummarizedView source
Documents that Single Block Mode in the Block List Editor is deprecated.
17.2.0GitHub ReleaseSummarizedView source
Deprecates the Management API controller for the defunct our.umbraco.com version checker.
17.1.0GitHub ReleaseSummarizedView source
Adds deprecation notices to AllowNonExistingSegmentsCreation.
AllowNonExistingSegmentsCreation
17.0.0-betaGitHub ReleaseSummarizedView source