Using ImageUltimate in an ASP.NET Core project

To use ImageUltimate in an ASP.NET Core Project, do the following in Visual Studio:

Make sure you have added references to ImageUltimate assemblies as described here.

Open Startup.cs of your project.

Add GleamTech to the ASP.NET Core services container. Insert the marked lines into the ConfigureServices method of your Startup.cs,

and then register GleamTech to the ASP.NET Core HTTP request pipeline. Insert the marked lines into the Configure method of your Startup.cs:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }


    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllersWithViews();


        //----------------------
        //Add GleamTech to the ASP.NET Core services container.
        services.AddGleamTech();
        //----------------------
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Home/Error");
        }


        //----------------------
        //Register GleamTech to the ASP.NET Core HTTP request pipeline.
        app.UseGleamTech();
        //----------------------


        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllerRoute(
                name: "default",
                pattern: "{controller=Home}/{action=Index}/{id?}");
        });
    }

Caution

services.AddGleamTech calls services.AddDistributedMemoryCache and services.AddSession internally and if you need to set a custom cache like services.AddStackExchangeRedisCache or need to call services.AddSession with custom options then place them before services.AddGleamTech so that they become effective.

Caution

The order of app.UseXXX methods is important so app.UseGleamTech should be placed before app.UseStaticFiles, app.UseRouting and app.UseEndpoints (or before app.UseMvc for legacy ASP.NET Core 2.1).

If you are using the new .NET 6 minimal hosting model for ASP.NET Core apps, open Program.cs of your project and insert the marked lines there instead:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllersWithViews();


//----------------------
//Add GleamTech to the ASP.NET Core services container.
builder.Services.AddGleamTech();
//----------------------


var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
}


//----------------------
//Register GleamTech to the ASP.NET Core HTTP request pipeline.
app.UseGleamTech();
//----------------------


app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

Optionally set ImageUltimate's global configuration (if overriding a default value is required). For example, you may want to set the license key, the default path for finding source images and image cache location.

You can specify the configuration in appsettings.json file:

Json

{
  //Set this property only if you have a valid license key, otherwise do not
  //set it so ImageUltimate runs in trial mode.
  "ImageUltimate:LicenseKey": "QQJDJLJP34...",

  //The default SourcePath value is "~/App_Data/ImageSource"
  //Both virtual and physical paths are allowed.
  //Note that using a path under "~/App_Data" can have a benefit,
  //for instance if you want to protect your original source files, i.e.
  //prevent them from being downloaded directly, you can use this special 
  //folder which is restricted by ASP.NET runtime by default.
  "ImageUltimateWeb:SourcePath": "~/Content",

  //The default CacheLocation value is "~/App_Data/ImageCache"
  //Both virtual and physical paths are allowed (or a Location instance for one of the supported 
  //file systems like Amazon S3 and Azure Blob).
  //However it's recommended that you use a path inside your application folder 
  //(e.g. "~/SomeFolder", "/SomeFolder" or "C:\inetpub\wwwroot\MySite\SomeFolder")
  //so that ImageUltimate can use RewritePath to pass download requests directly
  //to IIS for higher throughput.

  "ImageUltimateWeb:CacheLocation": "~/App_Data/ImageCache",

  //The default CacheLocation value is "~/App_Data/DocumentCache"
  //Both virtual and physical paths are allowed (or a Location instance for one of the supported 
  //file systems like Amazon S3 and Azure Blob).
  "DocumentUltimateWeb:CacheLocation": "~/App_Data/DocumentCache"
}

As you would notice, ImageUltimate: prefix maps to ImageUltimateConfiguration.Current and ImageUltimateWeb: prefix maps to ImageUltimateWebConfiguration.Current.

Alternatively you can specify the configuration in code, in Configure method of your Startup.cs after app.UseGleamTech call:

//----------------------
//Register GleamTech to the ASP.NET Core HTTP request pipeline.
app.UseGleamTech(() =>
{
    //Set this property only if you have a valid license key, otherwise do not
    //set it so ImageUltimate runs in trial mode.
    ImageUltimateConfiguration.Current.LicenseKey = "QQJDJLJP34...";

    //The default SourcePath value is "~/App_Data/ImageSource"
    //Both virtual and physical paths are allowed.
    //Note that using a path under "~/App_Data" can have a benefit,
    //for instance if you want to protect your original source files, i.e.
    //prevent them from being downloaded directly, you can use this special 
    //folder which is restricted by ASP.NET runtime by default.
    ImageUltimateWebConfiguration.Current.SourcePath = "~/Content";

    //The default CacheLocation value is "~/App_Data/ImageCache"
    //Both virtual and physical paths are allowed (or a Location instance for one of the supported 
    //file systems like Amazon S3 and Azure Blob).
    //However it's recommended that you use a path inside your application folder 
    //(e.g. "~/SomeFolder", "/SomeFolder" or "C:\inetpub\wwwroot\MySite\SomeFolder")
    //so that ImageUltimate can use RewritePath to pass download requests directly
    //to IIS for higher throughput.
    ImageUltimateWebConfiguration.Current.CacheLocation = "~/App_Data/ImageCache";
});
//--------------------

Create a new View (eg. Index.cshtml) and insert these lines:
C#
```
@using GleamTech.ImageUltimate
@using GleamTech.ImageUltimate.AspNet
@using GleamTech.ImageUltimate.AspNet.Core

<!DOCTYPE html>
<html>
    <head>
        <title>Getting Started</title>
    </head>
    <body>

        @this.ImageTag("SomeImage.jpg", task => task.ResizeWidth(300))

    </body>
</html>
```
This will resize width of the source image ~/Content/SomeImage.jpg to 300 pixels (keeping aspect ratio), cache the resulting image and render a <img> tag in your page. For consecutive page views, the image will be served directly from the cache and no processing will be done. This is the reason the task (second parameter) is specified as a lambda function, it will be only called when necessary for maximum performance. Note that as we specified a non-rooted path for the image path (first parameter), the image is considered relative to ImageUltimateWebConfiguration.Current.SourcePath (as set in step 2). This allows you to write image commands as short lines and avoids parent path repetition.
Sometimes you may need to render a url instead of a <img> tag, then use:
C#
```
@this.ImageUrl("SomeImage.jpg", task => task.ResizeWidth(300))
```
For example, consider you want to add a background image to a CSS class:
C#
```
<style>
    .someCls
    {
        background-image: url(@this.ImageUrl("SomeImage.jpg", task => task.ResizeWidth(300)));
    }
</style>
```
Tip
Alternatively you can add the namespaces globally in Views/_ViewImports.cshtml to avoid adding namespaces in your pages every time.