Nov 27, 2014
(9 votes)

Extending the ImageDescriptor attribute

We all know the ImageDescriptor attribute. You can use it in your image file model to define different sizes for you images.

For example:

[MediaDescriptor(ExtensionString = "jpg,jpeg,jpe,ico,gif,bmp,png")]
public class ImageFile : ImageData
    //Small 150x200
    [ImageDescriptor(Width = 200, Height = 150)]
    public virtual Blob Small { get; set; }

    //Large 300x400
    [ImageDescriptor(Width = 400, Height = 300)]
    public virtual Blob Large { get; set; }

The scaling of images by using an ImageDescriptor is somewhat limited. 

For example: if your original image is 500 by 500 pixels and you want to get the Small version you will end with an image with two white borders on the side. This is because EPiServer will scale your image, while keeping the aspect ratio, until it fits entirely into the specified width and height.

Image 500x500.png     Image 400x300area.png     Image 400x300result.png

This may not be what you want. Maybe you want it to fill the entire area and cut off some of the image. Or maybe you want to fit it exactly and loose the aspect ratio. We can extent the ImageDescriptor with an extra parameter to accomplish this.

First we create a new attribute that inherits from the ImageDescriptor.

[AttributeUsage(AttributeTargets.Property, AllowMultiple = false, Inherited = true)]
public class MyImageDescriptorAttribute : ImageDescriptorAttribute
    public ImageScaleType ScaleMethod { get; set; }
    public MyImageDescriptorAttribute() : this(48, 48, ImageScaleType.ScaleToFill)
    public MyImageDescriptorAttribute(int width, int height, ImageScaleType scaleMethod)
        Height = height;
        Width = width;
        ScaleMethod = scaleMethod;

And we use an Enum to specify the different scaling methods

public enum ImageScaleType

We have 3 different scaling methods:

  • ScaleTofit
    This will scale the image by keeping its aspect ratio until both width and height will fit
    Image 400x300result.png

  • ScaleToFill
    This will scale the image by keeping its aspect ratio until either the width or the height will fit
    Image 400x300ScaleToFill.png

  • Resize
    This will simply resize the image to the specified width and height
    Image 400x300Resize.png

To implement the different ways of scaling we need to replace the current ThumbnailManager with our own.

In the Alloy site we can do that by adding:


in the DependencyResolverInitialization class.

Our new ThumbnailManager will ook like this:

public class ExtendedThumbnailManager : ThumbnailManager
    private readonly BlobFactory _blobFactory;

    public ExtendedThumbnailManager(IContentRepository contentRepository, BlobFactory blobFactory, BlobResolver blobResolver)
        : base(contentRepository, blobFactory, blobResolver)
        _blobFactory = blobFactory;

    public override Blob CreateImageBlob(Blob sourceBlob, string propertyName, ImageDescriptorAttribute descriptorAttribute)
        Validator.ThrowIfNull("sourceBlob", sourceBlob);
        Validator.ThrowIfNullOrEmpty("propertyName", propertyName);
        Validator.ThrowIfNull("descriptorAttribute", descriptorAttribute);

        var uriString = string.Format("{0}{1}_{2}{3}", new object[]
        var customDescriptorAttribute = descriptorAttribute as ImageScaleDescriptorAttribute;
        return customDescriptorAttribute == null
                ? CreateBlob(new Uri(uriString), sourceBlob, descriptorAttribute.Width, descriptorAttribute.Height)
                : CreateScaledBlob(new Uri(uriString), sourceBlob, customDescriptorAttribute);

    private Blob CreateScaledBlob(Uri thumbnailUri, Blob blobSource, ImageScaleDescriptorAttribute imageDescriptorAttribute)
        switch (imageDescriptorAttribute.ScaleMethod)
            case ImageScaleType.Resize:
                var imgOperation = new ImageOperation(ImageEditorCommand.Resize, imageDescriptorAttribute.Width, imageDescriptorAttribute.Height);
                return CreateBlob(thumbnailUri, blobSource, new List<ImageOperation> {imgOperation}, MimeMapping.GetMimeMapping(blobSource.ID.LocalPath));
            case ImageScaleType.ScaleToFit:
                return CreateBlob(thumbnailUri, blobSource, imageDescriptorAttribute.Width, imageDescriptorAttribute.Height);
                var imgOperations = CreateImageOperations(blobSource, imageDescriptorAttribute.Width, imageDescriptorAttribute.Height);
                return CreateBlob(thumbnailUri, blobSource, imgOperations, MimeMapping.GetMimeMapping(blobSource.ID.LocalPath));

    private IEnumerable<ImageOperation> CreateImageOperations(Blob blobSource, int width, int height)
        var imgOperations = new List<ImageOperation>();
        int orgWidth;
        int orgHeight;
        using (var stream = blobSource.OpenRead())
            var image = System.Drawing.Image.FromStream(stream, false);

            orgWidth = image.Width;
            orgHeight = image.Height;


        var scaleFactor = Math.Max((double)width / orgWidth, (double)height / orgHeight);

        var tempWidth = (int) (orgWidth*scaleFactor);
        var tempHeight = (int) (orgHeight*scaleFactor);
        imgOperations.Add(new ImageOperation(ImageEditorCommand.ResizeKeepScale, tempWidth , tempHeight));
        imgOperations.Add(new ImageOperation(ImageEditorCommand.Crop, width, height) { Top = (tempHeight - height)/2, Left = (tempWidth - width)/2});

        return imgOperations;

    private Blob CreateBlob(Uri thumbnailUri, Blob blobSource, IEnumerable<ImageOperation> imgOperations, string mimeType)
        byte[] buffer;
        using (Stream stream = blobSource.OpenRead())
            var numArray = new byte[stream.Length];
            stream.Read(numArray, 0, (int)stream.Length);
            buffer = ImageService.RenderImage(numArray, 
                mimeType, 1f, 50);
        Blob blob = _blobFactory.GetBlob(thumbnailUri);
        using (Stream stream = blob.OpenWrite())
            stream.Write(buffer, 0, buffer.Length);
        return blob;

First we override the CreateImageBlob method. Part of the code is copied from the original CreatImageBlob method. We will add an extra check to see if the extended attribute is used. If so, we will call our own CreateScaledBlob method, else we will use the original CreateBlob method.

In the CreateScaledBlob method the Blob is scaled depending on the specified ImageScaleType.

For ImageScaleType.Resize we can use the ImageOperation ImageEditorCommand.Resize from the image library.

ImageScaleType.ScaleToFit is the normal EPiServer behavior, so we use the original CreateBlob method to do this.

For ImageScaleType.ScaleToFill, the default scaling type in this case, we have to use 2 steps which are created in the CreateImageOperations method. First we scale the image until either width or height fits the requested size, after that we cut off the borders.
The final CreateBlob statement is a copy of the original CreateBlob from the ThumbnailManager, with the only difference that you can call it with a chain of ImageOperations instead of a single one.

We can now use the new attribute in our ImageFile model:

//Tiny 75x40
[MyImageDescriptor(Width = 75, Height = 40, ScaleMethod = ImageScaleType.Resize)]
public virtual Blob Tiny { get; set; }
//Small 150x80
[MyImageDescriptor(Width = 150, Height = 80, ScaleMethod = ImageScaleType.ScaleToFill)]
public virtual Blob Small { get; set; }
//Medium 300x160
[MyImageDescriptor(Width = 300, Height = 160, ScaleMethod = ImageScaleType.ScaleToFit)]
public virtual Blob Medium { get; set; }

Nov 27, 2014


Nov 28, 2014 01:26 PM

Superb! I see immediate uses for your code in my current project... Thank you!

ainteger Apr 1, 2015 11:40 AM

container.For().Use(); should be changed to container.For().Use();

Kirolos Gerges
Kirolos Gerges Jun 2, 2015 04:27 PM

A splendid post Mark!! This solution might be what every episerver devloper is looking for. Thank you for sharing it!

Mar 17, 2016 02:32 PM

If you plan to use the ScaleTofit method and want to get rid of the eventually white background make sure that you save the image without background colour before you upload it to the Meda Assets Panel. Here's an example on how it can look like.

Eric Jun 11, 2018 04:35 PM

Is there an example project or code that shows how this us used?

Please login to comment.
Latest blogs
Caching & Rendering of metadata from the DAM

For the EPiServer.Cms.WelcomeIntegration.UI 1.2.0 release, we have facilitated the ability to cache and render metadata from assets within the DAM....

Matthew Slim | Jun 2, 2023

Conversion Rate Optimization: Maximizing ROI through Data-Driven Decisions

In today's digital landscape, businesses are constantly looking for ways to improve their online presence and drive more conversions. One effective...

JessWade | Jun 1, 2023

Enhance Your Writing with Suggestions

Are you tired of staring at a blank screen, struggling to find the right words? The Epicweb.Optimizely.AIAssistant Addon is here to revolutionize...

Luc Gosso (MVP) | May 31, 2023 | Syndicated blog

Content Graph - Letting GraphQL do all the hard work for you

Background As we have seen before, setting up Content Graph on the CMS side is pretty easy. However, when it comes to the “head” part of the setup,...

Kunal Shetye | May 26, 2023 | Syndicated blog