Retrieve content from media libraries

Media libraries serve as one type of data storage for your application. They can store different types of audio, video, image, and document files. For a complete list of the file types supported by default, see Media library configuration.

This page covers how you can:

• Retrieve media library files
• Get media file URLs
• Display media files

Retrieve media library files

The following example demonstrates how to retrieve files from Xperience media libraries in MVC applications. The example uses a media library with the code name SampleMediaLibrary. For this example to function, substitute the code name with any media library from the platform.

1. Open Xperience project in Visual Studio.
2. Create a view model class representing media files. Define properties for storing the media file values that you wish to use in your views.
3. Create a new controller class or edit an existing one.
4. Implement a GET action method to retrieve media files. This example retrieves .jpg files from the SampleMediaLibrary media library.
5. Use the view model to pass media file data to your views.

using System.Collections.Generic;
using System.Linq;

using Microsoft.AspNetCore.Mvc;

using CMS.MediaLibrary;
using CMS.Base;

using Kentico.Content.Web.Mvc;

private readonly IMediaFileUrlRetriever mediaFileUrlRetriever;
private readonly IMediaLibraryInfoProvider mediaLibraryInfoProvider;
private readonly IMediaFileInfoProvider mediaFileInfoProvider;

// Initializes instances of required services using dependency injection
public MediaLibraryController(IMediaFileUrlRetriever mediaFileUrlRetriever,
                              IMediaLibraryInfoProvider mediaLibraryInfoProvider,
                              IMediaFileInfoProvider mediaFileInfoProvider)
{
    this.mediaFileUrlRetriever = mediaFileUrlRetriever;
    this.mediaLibraryInfoProvider = mediaLibraryInfoProvider;
    this.mediaFileInfoProvider = mediaFileInfoProvider;
}

/// <summary>
/// Retrieves media files with the .jpg extension from the 'SampleMediaLibrary'.
/// </summary>
public IActionResult ShowMediaFiles()
{
    // Gets an instance of the 'SampleMediaLibrary' media library
    MediaLibraryInfo mediaLibrary = mediaLibraryInfoProvider.Get("SampleMediaLibrary");

    // Gets a collection of media files with the .jpg extension from the media library
    IEnumerable<MediaFileInfo> mediaLibraryFiles = mediaFileInfoProvider.Get()
                                .WhereEquals("FileLibraryID", mediaLibrary.LibraryID)
                                .WhereEquals("FileExtension", ".jpg");

    // Prepares a collection of view models containing required data of the media files
    IEnumerable<MediaFileViewModel> model = mediaLibraryFiles.Select(
            mediaFile => {
                IMediaFileUrl fileUrl = mediaFileUrlRetriever.Retrieve(mediaFile);
                return new MediaFileViewModel
                {
                    FileTitle = mediaFile.FileTitle,
                    // Gets the relative path to the media file
                    RelativeUrl = fileUrl.RelativePath
                };
            }
    );

    // Passes the model to the view
    return View(model);
}

Get media file URLs

To resolve the URLs of retrieved media library files (MediaFileInfo objects), use the IMediaFileUrlRetriever service from the Kentico.Content.Web.Mvc namespace. The service exposes a Retrieve method that takes a MediaFileInfo object as its parameter and returns an IMediaFileUrl instance with the following properties:

• RelativePath – the application relative (starting with ’_{/’) permanent path to the file. For example:} /getmedia/0140bccc-9d47-41ea-94a9-ca5d35b2964c/sample_image.jpg. This format ensures that the image remains accessible if the file is renamed or moved to a different media library or directory on the file system.
• DirectPath– the direct path to the media file on the filesystem. For example: ~/MediaLibraryFolder/sample_image.jpg. These URLs change whenever the file is renamed or moved to a different media library (directory on the filesystem).
• QueryStringParameters – a collection of query string parameters appended to the URL. See Parameterize retrieved URLs.
• IsImage – a boolean flag indicating whether the URL leads to an image file. See Resize images.

Resize images

You can resize images via extension methods for the IMediaFileUrl object. The methods add query string parameters that change the URL behavior and allow you to customize the format of the files.

The following extensions are available:

• WithSizeConstraint – used to resize image media files. You can resize image files via the SizeConstraint parameter. Note, however, that this parameterization never upscales the image. The following image size constraints are available:

  • Empty –  leaves the image unchanged.

  • Height(100) – resizes the image to the specified height (maintains aspect ratio).

  • Width(100) – resizes the image to the specified width (maintains aspect ratio).

  • MaxWidthOrHeight(100) – resizes the image so that its width and height do not exceed the specified value (maintains aspect ratio).

  • Size(100, 120) – resizes the image to the specified width and height. Doesn’t maintain the aspect ratio.

    It’s not possible to resize image files via the SizeConstraint parameter when using direct URLs. Files accessed via direct URLs are processed directly by the server, skipping application processing entirely.

Set the encoding quality for resized images

You can configure the encoding quality of resized images via the EncodingQuality option of the ImageProcessingOptions class. The option accepts values from the range 0 - 100. Lower values indicate stronger compression that results in smaller, lower quality images. The default implementation sets the threshold to 80 and uses SKImage.Encode to perform the encoding, which skips the compression step for lossless and unsupported image formats.

Set the configuration during application startup:

using Kentico.Xperience.ImageProcessing;

var builder = WebApplication.CreateBuilder(args);

...

builder.Services.AddOptions<ImageProcessingOptions>()
    // Sets the quality level for resized images to 90%, resulting in a barely noticeable loss of image quality
    // (only the highest frequencies from the image are filtered) and a roughly 30-40% size reduction
    .Configure(o => o.EncodingQuality = 90);

Display media library files

To display media library files on your website, create views that work with the generated media file URLs. To convert relative URLs to their application absolute format, use methods from the framework’s UrlHelper class, such as Url.Content:

@model IEnumerable<MediaFileViewModel>

<h2>Media library file listing</h2>

@foreach (MediaFileViewModel mediaFile in Model)
{
    @* Gets an application absolute URL for the media file *@
    string url = Url.Content(mediaFile.RelativeUrl);

    <img src="@url" alt="@mediaFile.FileTitle" />
}