Knowit.ImageToolbox.EPiServer 2.1.3

Knowit Image Toolbox

Installation

ImageToolbox supports EPiServer based projects only. Entry point for installation is Knowit.ImageToolbox.EPiServer package. In order to install it use following command:

> dotnet add package Knowit.ImageToolbox.EPiServer --source https://www.myget.org/F/creuna-nuget/api/v3/index.json

It will install all the required packages exept Knowit.ImageToolbox.Processing.MagickNet package that has to be installed manually using the following command:

> dotnet add package Knowit.ImageToolbox.Processing.MagickNet --source https://www.myget.org/F/creuna-nuget/api/v3/index.json

After installation:

• Open Startup.cs
• Register ImageTollbox services with extension method AddImageToolbox and Magick.NET services with method AddMagickNetForImageToolbox

example:

    public void ConfigureServices(IServiceCollection services)
    {
        if (_webHostingEnvironment.IsDevelopment())
        {
            AppDomain.CurrentDomain.SetData("DataDirectory", Path.Combine(_webHostingEnvironment.ContentRootPath, "App_Data"));

            services.Configure<SchedulerOptions>(options => options.Enabled = false);
        }

        services
            .AddCmsAspNetIdentity<ApplicationUser>()
            .AddCms()
            .AddAdminUserRegistration()
            .AddEmbeddedLocalization<Startup>();

        services
            .AddImageToolbox(options =>
            {
                options.HashSalt = "[d9145170-b92e-498c-bf27-ffbdeadfb4f6]";
            })
            .AddMagickNetForImageToolbox();
    }

Note: In above example HashSalt defined via options, it is hi recommended to define it unique for each site - it is used for image query hash generation to pass security check wich prevents DDOS attacks, see options properties hep hints for more information.

• Register ImageToolbox Middleware with method UseImageToolbox, it is important to have it called after UseAuthorization method to give ImageToolbox Middleware ability to check current user rights.

example:

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseStaticFiles();
        app.UseRouting();
        app.UseAuthentication();
        app.UseAuthorization();

        app.UseImageToolbox(); // Should be after app.UseAuthorization()

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapContent();
        });
    }

• Configure ImageToolbox via code implementing configuration action

example:

   services
       .AddImageToolbox(options =>
           {
              options.SkipHashCheck = true;
           });

or/and configure via appsettings.json (configuration in appSettings.json has highest proirty over in code configuration)

example:

"ImageToolbox": {
    "SkipHashCheck": true,
    "SkipHashCheckForRoles": [ "WebEditors" ],
    "Format": {
        "AutoConvertToModernFormat": true,
        "ConvertToAvifByDefault": false
    }
}

How to use

Resize

Query examples:

• ?width=100 or ?w=100
• ?Width=1024&height=768 or ?w=1024&h=768
• ?width=300&height=150&transform=downFill or ?w=300&h=150&mode=fill-down
• ?width=300&height=300&transform=crop or ?w=300&h=300&mode=crop
• ?width=1024&transform=scale or ?w=1024&mode=scale

width and height are pixels.

Supported transformations:

fill

• when both width and height are defined it scales image to requested size, then crops it to make the same aspect ratio with requested region, so image kind of fills requested region

• if only width or only height specified it just scales image to requested width or height without changing image aspect ratio (so in this case it works like fit described below)

fit

• scales image to requested size without changing image aspect ratio, so image kind of fits requested region.

crop

• crops image to requested size

stretch

• stretches image to requested size with changing image apsect ratio to requested region

down... transformations

• do resizing only if image is bigger then requested size. It is not required to define both width and height, not defined dimension is calculated automatically or just come form original image depended on requested transformation

center/focus-point

• can be defined as x,y where x and y is double from 0 to 1. It is useful for "fill" and "crop" transformations and defines the center of cropping, anyway it can be used with other kind of transformations without any errors.

Example: ?width=407&height=222&center=0.39,0.53&transform=DownFill

Default transformation is downFill.

According to experience mostly used transformation is downFill - it allows to get any image with needed size and aspect ratio, for images which usually predefined by designer (like logos) it is good to use "fit" transformation in order to sale image to requested size without changing ratio.

Auto rotate

Sometimes images are not properly oriented and have orientation data in EXIF information instead, unfortunately not all browsers support this kind EXIF information and images are shown rotated. Auto rotate - rotates image and cleans orientation instructions from EXIF Please note: Auto rotate is enabled by default (can be configured) so all images are auto-rotated if needed, in order to skip this for some image you need to add 'autoRotate=false' to the query.

Optimization

All requested images are optimized to be compressed as much as possible without loosing image quality. (Tested with Google PageSpeed Insights https://developers.google.com/speed/pagespeed/insights/) Please note: Optimization is enabled by default (can be configured) so all images are automatically optimized, in order to skip this for some image you need to add optimize=false to the query.

Format conversion

All requested images by default are converted to modern web formats, conversion is enabled by default(can be configured) and can be ajusted via format query parameter, possible options:

• auto - target format chosen automatically(default option if not specified). Toolbox chooses target conversion format automatically with checking if it supported by browser, for now avif is default for static images and webp for animated ones, can be updated in future releases.
• original - keep original image format without conversion (skip auto choose manually)
• avif - convert to avif
• webp - convert to webp

Service options

• report=true - returns image processing report instead image.
• ignore-cache=true - processes image skipping cache
• update-cache - processes image and updates it in the cache

Service commands

Url /--ImageToolbox?command=<command_name>&<param1=param1value>...

Commands:

• cleanup-cache - cleans caches

  parameters:

  • clean-processed-images=true - (true by default) - cleans cache for all resized images
  • clean-source-images=true - (false by default) - cleans cache for all source images

  usage examples:

  • short: /--ImageToolbox?command=cleanup-cache
  • full: /--ImageToolbox?command=cleanup-cache&clean-processed-images=true&clean-source-images=false