Sitecore Rendering Engine
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:
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 currentHttpRequest
andSitecoreLayoutRequest
can be specified.The default mapping sets:
-
The
Language
on theSitecoreLayoutRequest
fromRequestCulture.Culture.Name
in theIRequestCultureFeature
, if present. -
The
Path
on theSitecoreLayoutRequest
from thesitecoreRoute
route value, if present. -
The
Path
from theHttpRequest.Path
value, if thesitecoreRoute
route value is not present.
NoteThe 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 theSitecore.AspNet.RenderingEngine.Extensions
namespace. The example below shows the usage of this method by mapping alang
query string value from the currentHttpRequest
to the language value in theSitecoreLayoutRequest
sent to the Layout Service.RequestResponsepublic 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 isnull
.You use the
AddDefaultComponentRenderer()
extension method to set theDefaultRenderer
in theRenderingEngineOptions
. The default renderer is aLoggingComponentRenderer
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:RequestResponsepublic 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:
app.UseEndpoints(endpoints =>
{
endpoints.MapSitecoreLocalizedRoute("Localized", "Index", "Default");
endpoints.MapFallbackToController("Index", "Default");
});
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:
public class DefaultController : Controller
{
[UseSitecoreRendering]
public IActionResult Index(Route route)
{
return View(route);
}
}
This attribute can also be applied on the Controller itself.