Ucommerce
  • Ucommerce Next Gen
    • Getting Started
      • Prerequisites
      • Licensing
      • Ucommerce Templates
      • Headless Template
      • MVC Template
    • Headless
      • Postman Collection
      • Headless API Authentication
        • Token endpoint - Authorization Header
        • Authorization Scopes
        • Refreshing the Access Token
      • Reference
        • Cart
        • Cart / Order Line Items
        • Shipment
        • Billing
        • Promotion Codes
        • Price Groups
        • Payment Methods
        • Countries
        • Shipping Methods
        • Catalogs
        • Cart Custom Properties
        • Line Item Custom Properties
        • Orders
        • Views for Cart modifying operations
      • Custom Headless APIs
      • Error Handling
      • Pagination
      • Deprecation
    • Backoffice Authentication
      • Microsoft Entra ID Example
      • Auth0 Authentication Example
    • Definitions
      • What is a Definition
    • Search and indexing
      • Configuration
      • Indexing
        • Index Definitions
        • Facets
        • Indexing Prices
        • Suggestions
        • Custom Data
      • Searching
    • Payment Providers
      • Stripe Provider Integration
      • Implementing a custom payment provider
    • Data Import
    • Miscellaneous
      • Media
      • Price Group Inheritance
      • Price Group Criteria
      • Soft Deletion Of Entities
      • Logging
      • OpenTelemetry
    • Extensions
      • Extending Pipelines
        • Order Processing Pipelines
        • Checkout Pipelines
      • Changing Service Behavior
        • Images
        • Content
      • Custom Headless APIs
      • Extend the Backoffice
        • Custom UI Components
      • Custom Editor UI
      • Custom Promotion Criteria
      • Custom Price Group Criteria
    • How-To
      • Migrate from Classic
        • Common database issues
      • Entities from code
        • Bootstrapping data on startup
        • Product Definitions & Fields
      • Discover pipelines and their tasks
      • Executing a pipeline
    • Integrations
      • Umbraco Media Delivery API
      • App Slices
        • Product Picker
  • Release Notes
  • Contact Us
Powered by GitBook
On this page
  • Prerequisites
  • Setup Projects
  • Umbraco
  • Ucommerce
  • Generate the Umbraco Client
  • Implementing UmbracoImageService.cs
  • Tying everything together
  • UmbracoSettings.cs
  • UmbracoModuleExtensions.cs
  • See it in action

Was this helpful?

  1. Ucommerce Next Gen
  2. Integrations

Umbraco Media Delivery API

Leverage Umbraco as your DAM

PreviousIntegrationsNextApp Slices

Last updated 5 months ago

Was this helpful?

In this guide, we'll use Umbraco as a Digital Asset Management system and integrate it with Ucommerce. We'll use the Umbraco Media Delivery API to retrieve the information we need.

Here's a look at the final result:

Prerequisites

Setup Projects

Umbraco

"DeliveryApi": {
  "Enabled": true,
  "PublicAccess": true,
  "Media": {
    "Enabled": true,
    "PublicAccess": true
  }
}

PublicAccess should not be true in a publicly available environment

When Umbraco is installed, take it for a spin and add some images to the Media library:

Ucommerce

Generate the Umbraco Client

Second, use Kiota to generate a client from the Umbraco Delivery API Specification using either the command line (see below) or the VS Code plugin UI.

kiota generate 
    --openapi "https://localhost:{yourUmbracoPortNumber}/umbraco/swagger/delivery/swagger.json" \
    --language CSharp \
    --additional-data false \
    --class-name UmbracoClient \
    --namespace-name UcommerceTest.Integrations.Umbraco \
    --output ./Umbraco

The Umbraco Delivery API Specification can be found on https://localhost:{yourUmbracoPortNumber}/umbraco/swagger/delivery/swagger.json

Third, add the needed Kiota dependencies to the Ucommerce project.

Run kiota info --language CSharp to get a list of dependencies needed.

The csproj file should look similar to this:

<ItemGroup>
    <PackageReference Include="Microsoft.Kiota.Abstractions" Version="1.14.0" />
    <PackageReference Include="Microsoft.Kiota.Http.HttpClientLibrary" Version="1.14.0" />
    <PackageReference Include="Microsoft.Kiota.Serialization.Form" Version="1.14.0" />
    <PackageReference Include="Microsoft.Kiota.Serialization.Json" Version="1.14.0" />
    <PackageReference Include="Microsoft.Kiota.Serialization.Multipart" Version="1.14.0" />
    <PackageReference Include="Microsoft.Kiota.Serialization.Text" Version="1.14.0" />
    <PackageReference Include="Ucommerce.Web.BackOffice" Version="10.8.0" />
    <PackageReference Include="Ucommerce.Web.WebSite" Version="10.8.0" />
    <PackageReference Include="Ucommerce.Search.Elastic" Version="10.8.0" />
</ItemGroup>

Implementing UmbracoImageService.cs

Below is a complete example:

using System.Collections.Immutable;
using Ucommerce.Web.Infrastructure;
using Ucommerce.Web.Infrastructure.Core;
using Ucommerce.Web.Infrastructure.Core.Models;
using UcommerceTest.Integrations.Umbraco;
using UcommerceTest.Integrations.Umbraco.Models;

namespace UcommerceTest;

public class UmbracoImageService(UmbracoClient kiotaClient, UmbracoSettings umbracoSettings) : IImageService
{
    public async Task<IImmutableList<Content>> Get(
        string? parentId = null, 
        int startAt = 0, 
        int limit = 30,
        CancellationToken? token = null)
    {
        parentId ??= "/";
        var items =
            await kiotaClient.Umbraco.Delivery.Api.V2.Media.GetAsync(
                request =>
                {
                    request.QueryParameters.Fetch = $"children:{parentId}";
                    request.QueryParameters.Skip = startAt;
                    request.QueryParameters.Take = limit;
                }, token.GetValueOrDefault());

        return items?.Items?
            .Select(item => MapMedia(parentId, item))
            .ToImmutableList() ?? ImmutableList<Content>.Empty;
    }

    public async Task<Content> GetById(string? id, CancellationToken token)
    {
        if (string.IsNullOrEmpty(id))
        {
            return ImageNotFound();
        }

        var item = await kiotaClient.Umbraco.Delivery.Api.V2.Media.Item[Guid.Parse(id)]
            .GetAsync(cancellationToken: token);

        return item is null ? ImageNotFound() : MapMedia(null, item);
    }
    
    public async Task<IImmutableList<Content>> GetByIds(
        IImmutableList<string> ids, 
        CancellationToken? token = null)
    {
        var guids = ids.Select(Guid.Parse).Cast<Guid?>().ToArray();
        var items = await kiotaClient.Umbraco.Delivery.Api.V2.Media.Items.GetAsync(
            request => request.QueryParameters.Id = guids, token.GetValueOrDefault()) ?? [];

        return items
            .Select(item => MapMedia(null, item))
            .ToImmutableList();
    }

    /// <summary>
    /// Maps the response model to a Content object
    /// </summary>
    private Content MapMedia(
        string? parentId, 
        ApiMediaWithCropsResponseModel responseModel) => new()
    {
        Name = responseModel.Name ?? "No name",
        NodeType = responseModel.MediaType!.Equals("Folder") ? Constants.ImagePicker.Folder : Constants.ImagePicker.Image,
        Url = string.IsNullOrWhiteSpace(responseModel.Url) ? "No URL" : CombineUris(umbracoSettings.BaseUrl, responseModel.Url),
        Id = responseModel.Id?.ToString() ?? "No ID",
        ParentId = parentId,
        Icon = responseModel.MediaType!.Equals("Folder") ? "icon-folder" : "icon-picture",
        ChildrenCount = null
    };

    /// <summary>
    /// Gives a default image when the request image could not be found
    /// </summary>
    private static Content ImageNotFound()
    {
        return new Content
        {
            Id = "image-not-found",
            Name = "image-not-found.png",
            Url = "ImageNotFoundImageURL",
            NodeType = Constants.ImagePicker.Image
        };
    }
    
    /// <summary>
    /// Combines two URIs into one making sure there is only one '/' between them
    /// </summary>
    private static string CombineUris(string uri1, string uri2)
    {
        uri1 = uri1.TrimEnd('/');
        uri2 = uri2.TrimStart('/');
        return $"{uri1}/{uri2}";
    }
}

Each method is straightforward: Get the necessary data from Umbraco using the UmbracoClient, map the data to fit Ucommerce, and return the result.

Tying everything together

The last step needed is to set up UmbracoClient and UmbracoImageService in the Ucommerce project. Because the Umbraco Delivery API does not contain any information on the base URL, we'll have to set that up manually. As you might have noticed, we also need the base URL when mapping the URL as Umbraco returns only relative URLs.

UmbracoSettings.cs

The settings object is a single line of code:

public record UmbracoSettings(string BaseUrl);

UmbracoModuleExtensions.cs

To make the integration reusable, we suggest using an extension method for every module:

public static class UmbracoModuleExtensions
{
    public static IUcommerceBuilder AddUmbracoIntegration(
        this IUcommerceBuilder builder, 
        IConfiguration configuration)
    {
        
        var umbracoSettings = configuration.GetRequiredSection("Umbraco").Get<UmbracoSettings>();
        if(umbracoSettings is null)
        {
            throw new InvalidOperationException("Umbraco settings are missing");
        }
        builder.Services.AddSingleton(umbracoSettings);
        builder.Services.AddSingleton(new UmbracoClient(
            new HttpClientRequestAdapter(new AnonymousAuthenticationProvider())
            {
                BaseUrl = umbracoSettings.BaseUrl
            }));
        builder.Services.AddUnique<IImageService, UmbracoImageService>();
        return builder;
    }
}

Remember to use a different authentication provider when your Umbraco instance is not publicly accessible.

For the configuration to work, add the base URL to the following path in appsettings.json: Umbraco:BaseUrl:

"Umbraco":
{
  "BaseUrl": "https://localhost:{yourUmbracoPortNumber}"
}

The final step is to call AddUmbracoIntegration in Program.cs:

// Set up services
builder.Services.AddUcommerce(builder.Configuration)
    ...
    .AddUmbracoIntegration(builder.Configuration)
    .Build();

Congratulations! Ucommerce is now able to get images from Umbraco!

See it in action

Now, try taking the Ucommerce project for a spin and select an image for a product.

Before you get started, please make sure both and are installed.

Create a new project using the . Make sure both delivery API and media is enabled in appsettings.json:

Create a new project using the .

To make Ucommerce communicate with Umbraco, we need a client to handle the REST calls to the Umbraco Delivery API. You can either code this yourself or use a tool to generate it. For this guide, we're going to use to generate it for us.

First, install Microsoft Kiota as a or as a .

See for more details on the command

In the Ucommerce project, create a new class UmbracoImageService that inherits from IImageService. This class is responsible for mapping between the UmbracoClient created previously and Ucommerce. See for more details.

Note that the ChildrenCount is set to null. This is because the Umbraco Delivery API does not contain any information on the number of children for a given node. See for more details on what that means.

Umbraco templates
Ucommerce templates
Umbraco template
Ucommerce Headless template
Microsoft Kiota
.Net tool
VS Code extension
Optional parameters
Images
Media
A look at how Umbraco can be leveraged as a DAM system for Ucommerce
Media added to Umbraco