Media: Add support for Media URL providers with cache busting (Closes #23282) by kjac · Pull Request #23327 · umbraco/Umbraco-CMS

kjac · 2026-07-08T12:13:37Z

Prerequisites

I have added steps to test this contribution in the description below

If there's an existing issue for this PR then this fixes #23282 (in part)

Description

Umbraco does not automatically append cache busting parameters to raw media URLs. This is by design, to prevent cache misses downstream.

This does however come with a few drawbacks, as described in ##23282.

One would then assume that a custom Media URL provider would be able to solve these drawbacks for a concrete implementation --- but unfortunately, the rich text rendering assumes a bit too much when rendering local image sources; it does not expect Media URLs with query string parameters.

In effect, if a Media URL provider yields Media URL with a cache buster parameter (e.g. /media/something/image.png?rand=123), the rich text conversion ends up generating Media URLs with two ? parts (/media/something/image.png?rand=123?rmode=max&....).

This PR ensures that the rich text rendering appends query string parameters safely, thus enabling Media URL providers with cache busting by query string.

Note

Crop URLs are cache busted by default as-is, because the effective crops are expected to change over time.

Testing this PR

Replace the default Media URL provider with a custom implementation which adds cache busting (example code below), and verify that:

Rich text rendering produces valid Media URLs which include the cache busting part.
Media picker "bare" URLs contain the cache busting part.
Media picker crop URLs also contain the cache busting part (despite them already having a cache buster by default).

Verify all of the above both for templated rendering (example template below) and for the Delivery API output.

Example template

@using Umbraco.Cms.Core.Models
@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage
@{
	Layout = null;
    var cropUrl = Model.Value<MediaWithCrops>("mediaPicker")?.GetCropUrl("small");
    var imageUrl = Model.Value<MediaWithCrops>("mediaPicker")?.Url();
}
<html>
<body>
<h2>Bare Media URL</h2>
<img src="@imageUrl" width="300px"/>
<hr/>
<h2>Media crop URL</h2>
<img src="@cropUrl"/>
<hr/>
<h2>Rich text</h2>
@Model.Value("richtextEditor")
</body>
</html>

Example Media URL provider

using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.Routing;

namespace My.Site.Providers;

public class MyMediaUrlProvider : DefaultMediaUrlProvider
{
    public MyMediaUrlProvider(MediaUrlGeneratorCollection mediaPathGenerators, IUrlAssembler urlAssembler)
        : base(mediaPathGenerators, urlAssembler)
    {
    }

    public override UrlInfo? GetMediaUrl(IPublishedContent content, string propertyAlias, UrlMode mode, string? culture, Uri current)
    {
        UrlInfo? urlInfo = base.GetMediaUrl(content, propertyAlias, mode, culture, current);
        if (urlInfo?.Url is null)
        {
            return urlInfo;
        }

        // assemble a new Media URL with a calculated cache buster
        var cacheBuster = content.UpdateDate.Ticks;
        var url = new Uri($"{urlInfo.Url}?r={cacheBuster}", urlInfo.Url.IsAbsoluteUri ? UriKind.Absolute : UriKind.Relative);
        return new UrlInfo(url, Constants.UrlProviders.Media, culture);
    }
}

public class MyMediaUrlProviderComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
        => builder.MediaUrlProviders().Replace<DefaultMediaUrlProvider, MyMediaUrlProvider>();
}

claude · 2026-07-08T12:13:58Z

Claude finished @kjac's task in 6m 4s —— View job

PR Review

Target: origin/v17/dev · Based on commit: 324eeaf1 · Skipped: 0 noise files

Fixes the double-? bug that occurred when a custom Media URL provider appended cache-busting query parameters and rich text rendering naively concatenated the stored query string onto the already-parameterised URL. The core change — swapping $"{mediaUrl}{queryString}" for mediaUrl.AppendQueryStringToUrl(queryString) — is exactly right for the happy path and is covered by new tests.

Other changes: Rich text rendering now always calls AppendQueryStringToUrl instead of string concatenation; behavior changes for images with cache-busting URLs (intended) and, inadvertently, for images without any query string (see Important findings below).

Important

src/Umbraco.Core/Templates/HtmlImageSourceParser.cs:139: When the stored image src has no query string (plain, uncropped image), src.Groups[2].Value is "". AppendQueryStringToUrl("") filters the empty string out of nonEmpty, then calls "".EnsureStartsWith('?') = "?" (or '&'), appending a stray trailing character to the URL — a regression vs. the old $"{mediaUrl}{""}" which cleanly produced mediaUrl. Guard before delegating: queryString.IsNullOrWhiteSpace() ? mediaUrl : mediaUrl.AppendQueryStringToUrl(queryString).
src/Umbraco.Infrastructure/DeliveryApi/ApiRichTextMarkupParser.cs:129: Same issue — currentImageQueryString is now string.Empty (previously null) when no ? is present. null was safe in the old string interpolation; "" is not safe as an argument to AppendQueryStringToUrl. Same guard pattern fixes both files.

Suggestions

tests/Umbraco.Tests.UnitTests/Umbraco.Core/Templates/HtmlImageSourceParserTests.cs:281: The new tests cover the with-query-string path. Adding a test for a plain image (no crop params in src) + cache-busting provider would prevent the regression from going undetected. The suggested test is on the inline comment.

Request Changes

The fix correctly addresses the primary bug, but the empty-query-string edge case introduces a regression (trailing ? or & on plain image URLs) that should be fixed before merging.

…h-cache-busting

sonarqubecloud · 2026-07-10T07:51:14Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

Zeegaan

Looks good and works like a charm 🚀

Add support for media URL providers with cache busting

324eeaf

kjac changed the title ~~Add support for Media URL providers with cache busting~~ Media: Add support for Media URL providers with cache busting (Closes #23282) Jul 8, 2026

kjac mentioned this pull request Jul 8, 2026

Media URLs inside the Rich Text Editor are rendered without a cache buster #23282

Closed

claude Bot reviewed Jul 8, 2026

View reviewed changes

Comment thread src/Umbraco.Core/Templates/HtmlImageSourceParser.cs Outdated

claude Bot reviewed Jul 8, 2026

View reviewed changes

Comment thread src/Umbraco.Infrastructure/DeliveryApi/ApiRichTextMarkupParser.cs Outdated

claude Bot reviewed Jul 8, 2026

View reviewed changes

Comment thread tests/Umbraco.Tests.UnitTests/Umbraco.Core/Templates/HtmlImageSourceParserTests.cs

claude Bot added area/backend category/api labels Jul 8, 2026

kjac added 2 commits July 8, 2026 14:33

Fixes for Claude review

a6901d9

Merge branch 'v17/dev' into v17/bugfix/support-media-url-provider-wit…

6d5fbee

…h-cache-busting

Zeegaan approved these changes Jul 12, 2026

View reviewed changes

Zeegaan merged commit 168f9af into v17/dev Jul 12, 2026
30 of 31 checks passed

Zeegaan deleted the v17/bugfix/support-media-url-provider-with-cache-busting branch July 12, 2026 23:31

Zeegaan added release/18.1.0 release/17.6.0 labels Jul 12, 2026

Navigation Menu

Uh oh!

Media: Add support for Media URL providers with cache busting (Closes #23282) - #23327

Media: Add support for Media URL providers with cache busting (Closes #23282)#23327
Zeegaan merged 3 commits into
v17/devfrom
v17/bugfix/support-media-url-provider-with-cache-busting

kjac commented Jul 8, 2026

Uh oh!

claude Bot commented Jul 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud Bot commented Jul 10, 2026

Uh oh!

Zeegaan left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

kjac commented Jul 8, 2026

Prerequisites

Description

Testing this PR

Example template

Example Media URL provider

Uh oh!

claude Bot commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review

Important

Suggestions

Request Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud Bot commented Jul 10, 2026

Quality Gate passed

Uh oh!

Zeegaan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

claude Bot commented Jul 8, 2026 •

edited

Loading