ASP.NET Core Rendering Engine

Current version: 19.x

The Sitecore Rendering Engine renders content fetched from a Sitecore instance using the Sitecore Layout Service. You must perform some configuration to use the Rendering Engine in your application. Most of this configuration is done in the Startup class. See the Microsoft documentation on App startup in ASP.NET Core.

The Rendering Engine libraries are available as NuGet packages, and their name is prefixed with Sitecore.AspNet.RenderingEngine.

Rendering Engine services registration

To add the required Sitecore Rendering Engine services to the Dependency Injection container, you use the AddSitecoreRenderingEngine() extension method from the Sitecore.AspNet.RenderingEngine.Extensions namespace in the ConfigureServices() method of your ASP.NET Startup class.

The method returns an ISitecoreRenderingEngineBuilder instance to allow further configuration of the Rendering Engine using other extension methods, for example:

RequestResponse

public void ConfigureServices(IServiceCollection services)
{
    var renderingEngineBuilder = services.AddSitecoreRenderingEngine();
}

The AddSitecoreRenderingEngine() method accepts an Action<RenderingEngineOptions> parameter which allows for the Rendering Engine options configuration.

The RenderingEngineOptions parameter allows the following configurations to be exposed as class properties:

ICollection<Action<HttpRequest, SitecoreLayoutRequest>> RequestMappings - a list of mappings between the current HttpRequest and SitecoreLayoutRequest can be specified.

The default mapping sets:
- The Language on the SitecoreLayoutRequest from RequestCulture.Culture.Name in the IRequestCultureFeature, if present.
- The Path on the SitecoreLayoutRequest from the sitecoreRoute route value, if present.
- The Path from the HttpRequest.Path value, if the sitecoreRoute route value is not present.
Note

The default mappings are supported by the MapSitecoreLocalizedRoute extension and available when configuring your MVC endpoints (app.UseEndpoints).

To add additional mappings to the list, you use the MapToRequest() extension method available in the Sitecore.AspNet.RenderingEngine.Extensions namespace. The example below shows the usage of this method by mapping a lang query string value from the current HttpRequest to the language value in the SitecoreLayoutRequest sent to the Layout Service.
RequestResponse
```
public void ConfigureServices(IServiceCollection services)
{
    var renderingEngineBuilder = services.AddSitecoreRenderingEngine(
        options => options.MapToRequest(
            (httpRequest, sitecoreLayoutRequest) => sitecoreLayoutRequest.Language(httpRequest.Query["lang"]))
    );
}
```
SortedList<int, ComponentRendererDescriptor> RendererRegistry - a sorted list of component renderers. By default, this list is empty.

The Rendering Engine provides several component renderers by default. For example, there are view component and partial view renderers.

The following extension methods are available in the Rendering Engine that can help with configuring component renderers:
- AddViewComponent() - maps a Sitecore layout component name to a view component rendering. The mapping process is case-insensitive.
- AddModelBoundView<TModel>() - maps a Sitecore layout component name to the default view component rendering using the default Sitecore view component to model bind it. The mapping process is case-insensitive.
- AddPartialView() - maps a Sitecore layout component name to a partial view rendering.
- AddDefaultPartialView() - maps any unmatched Sitecore layout component to a default partial view.
See view types for more information on use of view components, model bound views, and partial views.

ComponentRendererDescriptor? DefaultRenderer - this is the default component renderer descriptor object for handling Sitecore component rendering. By default, this is null.

You use the AddDefaultComponentRenderer() extension method to set the DefaultRenderer in the RenderingEngineOptions. The default renderer is a LoggingComponentRenderer that writes the Sitecore component content to a specified log instead of generating HTML output. This can be useful for testing an application, for example:

RequestResponse

public void ConfigureServices(IServiceCollection services)
{
    var renderingEngineBuilder = services.AddSitecoreRenderingEngine(options =>
          options

            // Map Partials
            .AddPartialView("HeaderBlock", "_HeaderBlock")
            .AddPartialView(name => name.StartsWith("sc"), "_OtherBlock")

            // Map View Components
            .AddModelBoundView<BoundContentBlock>("ContentBlock")
            .AddViewComponent("Styleguide-Layout", "StyleguideLayout")
            .AddViewComponent(name => name.StartsWith("sc"), "Other")

            // Add fallback for any other component
            .AddDefaultPartialView("_ComponentNotFound");
    );
}

Using Endpoints and Controllers with the Rendering Engine

When creating content-driven Sitecore sites, the Sitecore content tree typically owns routing – that is, Sitecore URLs are driven by the structure of its content tree. A Sitecore URL takes one of the following forms out of the box:

With Language - /[language ISO]/path/to/the/page
Without Language - /path/to/the/page

If your site is multilingual, you must also configure request localization. You can then use the MapSitecoreLocalizedRoute extension to configure a route which supports Sitecore-style language embedding and content paths. To support paths without language, you can use the built-in ASP.NET MapFallbackToController as a catch all to handle Sitecore content paths.

Multilingual sites typically handle both language embedding and content paths, unless your Sitecore link provider is explicitly configured to always embed language.

Example of Sitecore routes mapped to the Index action in the Default controller:

RequestResponse

app.UseEndpoints(endpoints => 
{ 
  endpoints.MapSitecoreLocalizedRoute("Localized", "Index", "Default"); 
  endpoints.MapFallbackToController("Index", "Default"); 
});

Note

You can add additional endpoints for non-Sitecore routes before the Sitecore endpoints.

Be sure to tag the Index action with the [UseSitecoreRendering] attribute (available in the Sitecore.AspNet.RenderingEngine.Filters namespace) to enable the Sitecore rendering middleware and the corresponding request to the Layout Service:

RequestResponse

public class DefaultController : Controller 
{ 
  [UseSitecoreRendering] 
  public IActionResult Index(Route route) 
  { 
    return View(route); 
  } 
}

Note

This attribute can also be applied on the Controller itself.

Do you have some feedback for us?

If you have suggestions for improving this article,