Image processing API
Sitefinity CMS offers an extensible API for image processing.
Image transformations are performed with the IImageProcessor interface and its default implementation ImageProcessor.
IImageProcessor
This interface describes the available processing operations that you can use in Sitefinity CMS. It contains two methods - Resize and ProcessImage that you need to implement.
ImageProcessor
This classis the default implementation of the IImageProcessor interface. It is registered in ObjectFactory (IoC) Container, and you can replace it with your implementation. It has three image processing methods, described below with their arguments.
Resize(Image sourceImage, FitToAreaArguments args)
Resizes the image by keeping the ratio between width and height and not overflowing the max limits specified. You use the FitToAreaArguments class to define the Resize method argument for specifying the desired resize options.
Resize(Image sourceImage, FitToSideArguments args)
Resizes the specified source image by changing one of the sides (width or height) to the desired size and the other side proportionally keeping the ratio. You use the FitToSideArguments class to define the Resize method argument for specifying the desired resize options.
Crop(Image sourceImage, CropArguments args)
It resizes the side with a smaller change keeping the ratio width/height, and cuts the other side from both sides (to preserve the center of the image) to satisfy the desired width and height. You use CropArguments class to define the Crop method argument for specifying the desired cropping options.
Image Processing Methods Metadata
You should mark each processing method with attributes that provide additional information to be used by Sitefinity CMS successfully. Below are the different types responsible for the image processing metadata.
ImageProcessingMethod
This class encapsulates the meta-data about an image processing method. It holds information about method arguments and gives the ability to create a new instance of the argument object, parse and serialize, and validate from/to string the image processing parameters.
ImageProcessingProperty
This class defines the metadata for the particular property used as a parameter for the image processing method.
ImageProcessingMethodAttribute
This attribute marks the image processing methods that can be used in Sitefinity CMS. If you extend the ImageProcessor class, you must mark your custom image processing methods with this attribute. All methods like this will be discovered and exposed automatically for thumbnail generation.
ImageProcessingPropertyAttribute
This attribute specifies the image processing argument for the transformation method. Each property that should be passed as an argument to the processing method should be marked with this attribute.
Image Processing Errors/Exceptions
When the image processing fails for some reason, you use the following types that store the information about the error.
ImageProcessingException
Represents the exception that is thrown when the image processing fails. It contains the processing error information.
ImageProcessingError
This enumeration contains the specific reason for the image processing error. There are two reasons specified:
MethodNotFound - The generation method could not be found.
MethodGenerationError - Internal image processing error. The generation method was executed and threw an error.
In the code snippet below you can see a demonstration of a class that extends the default ImageProcessor and adds a new image processing method:
IImageProcessorExtender
You implement this interface to extend the image processing capabilities, built into Sitefinity CMS, and write custom logic for image processing. It contains the following members:
TryGetImageFromStream method
You implement this method to get an image from an input stream. It accepts a stream and an image as an out parameter.
There is also optional options parameter, which is an object of type GetImageOptions, containing two boolean properties: UseEmbeddedColorManagement and ValidateImageData. The properties correspond to the parameters of the FromStream method.
For more information, see Image.FromStream method.
TrySaveImageToStream method
You implement this method to save an image to a stream. It accepts the image, the stream, and the required MIME type. The optional SaveImageOptions object consists of one property – IsThumbnail. You use it, if you need some custom logic for thumbnails.
In this method, you can transcode the image into another format. If you do this, you must also assign the new MIME type, using the mimeType parameter.
SupportedImageExtensions property
This property holds the file extensions which the extender supports. For example, you can implement it as new string[] { ".webp" };
When this property is set, all of the values will appear as options in the Convert image format to…dropdown in the thumbnail settings dialog.
For more information, see WebP images
NOTE: If two or more classes implement the extender interface with the same target formats, Sitefinity CMS uses one of them without any error or message, but it is not specified which one. Therefore, you should not register different implementations for the same target formats.
In the code sample below, you can see how to implement the IImageProcessorExtender interface and how to register your implementation in the Sitefinity IoC container: