Umbraco: Adding custom query strings for GetCropUrl()

Richard Ockerby — Fri, 17 Jan 2025 00:54:52 +0000

I needed to use Imgix to serve images from Umbraco. Most of the out-of-the-box parameters with the current Umbraco v13 implementation (ImageSharp) were working great, like width and height, but the cropping mode wasn't quite there.

Simple enough, just add fit=crop to the query string. But how do we add that as a default parameter to the generated query string from GetCropUrl()? Sure; you can add optional params using that function but if you have an already existing site, going through and changing it everywhere just isn't feasible.

My solution was to swap out the implementation of IImageUrlGenerator, ImageSharpImageUrlGenerator.

Start by taking a copy of that and putting it in your project, then changing the query string value. Like:

using System.Globalization;
using Microsoft.AspNetCore.WebUtilities;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Options;
using Microsoft.Extensions.Primitives;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.Web;
using SixLabors.ImageSharp.Web.Middleware;
using SixLabors.ImageSharp.Web.Processors;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Cms.Core.Media;
using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Imaging.ImageSharp.ImageProcessors;
using static Umbraco.Cms.Core.Models.ImageUrlGenerationOptions;

namespace Your.Namespace
{
    public class CustomImageSharpImageUrlGenerator : IImageUrlGenerator
    {
        ... the rest of the original class implementation here...

        /// <inheritdoc />
        public string? GetImageUrl(ImageUrlGenerationOptions? options)
        {
            // ... original function definition here

            // Add a custom query string
            queryString.Add("fit", "crop");

            return QueryHelpers.AddQueryString(options.ImageUrl, queryString);
        }
    }
}

And now we need to replace the current implementation with our own. It's registered as a singleton in the Umbraco composer, so let's sort that in our own composer:

public class ImagingComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.Services.Replace(
          ServiceDescriptor.Singleton<IImageUrlGenerator, 
          CustomImageSharpImageUrlGenerator>()
        );
    }
}

And that's it! Visit the front end and you'll see your new fit param, like so:

https://localhost:44832/media/c0klecps/image.jpeg?width=1500&height=1100&v=1db5078d578e850&fit=crop&format=webp

Happy coding!

DEV Community: Richard Ockerby

Umbraco: Adding custom query strings for GetCropUrl()