Making a simple Consumer App v3.1

Overview

This page describes the process of creating a simple consumer app. This consists of connecting to a Manifest Service and implementing the single required method of IVariantProvider.

An ASP .NET Core application will be used as a server, overriding the default routing behaviour.

Prerequisites

1. Install Visual Studio 2022. Ensure all tools are installed for developing .Net Core 3.1.

2. From Visual Studio, create a new Solution, using the "ASP .NET Core Web App" template.

3. Name the solution mvc-sample.

   • If you use a different name, ensure you edit the namespaces in the sample code below to match the name you choose

   • Select the ".Net Core 3.1" framework

4. Install the latest versions of the Forrit.Consumers and Forrit.Consumers.Types Nuget packages in the solution

   • Note: You need to have access to the private Cortex Nuget repository in order to install this package

5. Obtain Shared Access Signatures for the Manifests Container and the Releases table in Azure Blob Storage, you will need these later.

6. You will need the URL for the Service Bus for Forrit CMS. This will be used to automatically update the release when a change is made.

7. You will need the GUID for the consumer app that will be deployed to.

Configuring a Variant Provider

First we will create a Mock Variant Provider that always returns the same hard-coded value. This value must match a variant that you have defined in the Forrit CMS.

1. Create a new folder in your solution named Providers

2. Right-click the Providers folder, and add a new class to the folder, called MockVariantProvider.cs

3. Paste the code below into the new class, replacing the entire class definition. Edit the placeholder in the declaration of variant with a variant ID from your CMS:

   CODE

   using Forrit.Consumers.Providers;
   using System;
   using System.Diagnostics;
   using System.Threading;
   using System.Threading.Tasks;
   
   namespace mvc_sample.Providers
   {
       public class MockVariantProvider : IVariantProvider
       {
           public ValueTask<Guid> GetVariantAsync(CancellationToken cancellationToken)
           {
               Guid variant = new Guid("{default-variant-UID}");
   
               Trace.WriteLine(string.Format("MockVariantProvider: GetVariantAsync: Returning variant '{0}'", variant));
               return new ValueTask<Guid>(variant);
           }
       }
   }

   The GetVariantAsync method will be called for every page request and in this implementation will always return the same mock value.
   Later, we will hook this Variant Provider up to the Manifest Service.

Configuring a Manifest Service

Next we will configure a Manifest Service in the application and ensure that it connects successfully to your Manifests Container in Azure Blob Storage.

1. In the application appSettings.json file, add the following settings:

   CODE

     "ConsumerKey": "{consumer-app-uid}",
     "ConnectionStrings": {
       "ManifestsContainer": "{SAS-to-access-manifests}",
       "Releases": "{SAS-to-access-releases}",
       "ServiceBus": "{Endpoint-for-service-bus}"
     }

   Update the placeholders with the GUID for the Consumer App, the Shared Access Signatures and the Service Bus URL that you saved earlier.

2. Replace the ConfigureServices function in Startup.cs with the code below.
   The interface classes within here can be found in the Forrit.Consumers library.

   CODE

   public void ConfigureServices(IServiceCollection services)
   {
       services.AddControllersWithViews();
       services.AddHostedService(provider => provider.GetRequiredService<IManifestsRefreshService>());
       services.AddHttpContextAccessor();
       services.AddSingleton<IManifestsRefreshService>(provider => new ManifestsRefreshSubscribingService(Configuration.GetConnectionString("ServiceBus"), "manifests", Guid.NewGuid().ToString(), Configuration.GetValue<Guid>("ConsumerKey"), provider.GetRequiredService<ILoggerFactory>().CreateLogger<ManifestsRefreshSubscribingService>()));
       services.AddSingleton<IManifestsRepository>(provider => new ManifestsRepository(Configuration.GetValue<Guid>("ConsumerKey"), Configuration.GetConnectionString("ManifestsContainer"), Configuration.GetConnectionString("Releases"), provider.GetRequiredService<ILoggerFactory>().CreateLogger<ManifestsRepository>()));
       services.AddSingleton<IManifestsService, ManifestsService>();
       services.AddSingleton<IVariantProvider, MockVariantProvider>();
   }

3. Create a new folder called Controllers. Add a new class called HomeController.cs with this code:

   CODE

   using Forrit.Consumers.Services;
   using Microsoft.AspNetCore.Mvc;
   using System.Threading;
   using System.Threading.Tasks;
   
   namespace mvc_sample.Controllers
   {
       public class HomeController : Controller
       {
           private readonly IManifestsService _manifestsService;
   
           public HomeController(IManifestsService manifestsService)
           {
               _manifestsService = manifestsService;
           }
   
           public async Task<IActionResult> IndexAsync(CancellationToken cancellationToken)
           {
               var route = GetPageRoute(HttpContext.Request.Path.Value.TrimStart('/'));
   
               ViewData["Body"] = await _manifestsService.GetPageBodyHtmlAsync(route, cancellationToken: cancellationToken);
               ViewData["Head"] = await _manifestsService.GetPageHeadHtmlAsync(route, cancellationToken: cancellationToken);
   
               return View();
           }
   
           private string GetPageRoute(string path) => path == string.Empty ? "{default-page-route}" : path;
       }
   }
   

4. Configure the default page route near the end of this file.

This implementation is the simplest possible configuration, but is adequate for our purposes here.

Change MVC Routing

Any page defined in Forrit should be displayed by providing the page route as a path parameter from the root of our ASP .NET website; so if there is a page reference called 'product1', it should be possible to display this by navigating to http://example.com/product1 (where 'example.com' is the name of your website - or localhost if running locally).

To do this, we will replace the default routing of our ASP .NET website with a route of our own design.

In the Configure function in Startup.cs, modify the UseEndpoints call to use the HomeController:

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllerRoute("default", "{*url}", new { controller = "Home", action = "Index" });
        });

This route passes all requests to the action Index in the Home controller, and passes any path parameters in the property named url.

The HomeController already contains a function to handle the requests which will come from our new route.

Finally, create a new folder called Views in the project and unzip this within it:

Views.zip

Build and run the application. Provided that you have a page defined with a route matching the default route, and a variant defined with the same UID as the hard-coded variable  variant  in MockVariantProvier.cs, you should see content from Forrit. You should be able to enter any route that has been published as a parameter as a URL.

Note that the page includes a set of simple CSS and JavaScript files. The contents of the CSHTML files in the Views folder can be modified to make these more relevant for your site.

Set up Routing Manager

In v3.0 the Routing manager provides routing as part of the CMS. The SDK includes its own routing manager that can handle URL redirects, as well as static URLs for media items. Alternatively the Consumer App can implement its own routing manager using the routing APIs in the SDK.

To configure the SDK routing manager, make the following changes to the code:

1. Add these lines to ConfigureServices in Startup.cs:

   CODE

               services.AddSingleton<IRoutingService, RoutingService>();
               services.AddSingleton<IStaticUrlService, StaticUrlService>();

2. Add this line to Configure Startup.cs:

   CODE

               app.UseForritRoutingMiddleware(Configuration.GetValue<bool>("Production"));

3. Add this line to appsettings.json to specify whether the app is a production app or not:

   CODE

     "Production": false,

If the Consumer App is to use its own routing manager, then don’t call UseForritRoutingMiddleware and use the IRoutingService and IStaticUrlService APIs to fetch the data for the routes defined in the CMS.

How it works

The Manifest Service maintains an up-to date local cache of all of the published pages of your site.

The Index Action method is called each time a new route is matched. It expects the url parameter to contain a valid page route from Forrit. If no URL parameter is passed, it uses a hard coded route as a default page.

If the Routing Manager has been configured, then it intercepts the request before it reaches the Index Action method and checks for any redirects or rewrites that have been defined in the CMS.

Once a page has been found, the getPage function is called on the Manifest Service, which returns strings containing the Head and Body elements of the requested page. If a URL parameter is passed which does not match a page route which has been published to the manifest, then the getPage call fails.

Finally, the Body element is passed into the Razor view as a ViewData object, and is rendered by the Razor View, using the @Html.Raw() helper function, because the returned value is raw HTML to be rendered.

Writing production Consumer Apps

This is a simple "Hello World" example that implements a minimal, non-production Consumer App. There are a few considerations worth emphasising when designing a production Consumer App.

• Performance The call to your variant provider - mockVariantProvider() in our example - is called on every page request. You should ensure an optimal implementation of your variant selection logic. If you call an external REST service in order to determine the variant, then ensure that you optimise this for performance (perhaps caching the results in order to reduce load on the server for future requests); otherwise, even though this is an asynchronous call, the overall performance and scalability of the server could be impacted.

• Secrets In the sample app a Secret (the Blob Storage Connection String) is stored within web.config. For production, in the case of configuration values, it is recommended to use App Settings on the Azure App Service, which can be easily retrieved at runtime, and can be managed from the portal. For true production Secrets (keys, certificates) use Azure KeyVault.