---
title: "ASP.NET Core Rendering Engine"
slug: "asp-net-core-rendering-engine"
abstract: "Overview of the Sitecore Rendering Engine services and middleware registration procedures."
---
# ASP.NET Core Rendering Engine

> [!important]
> If you integrated your app before , it's using the legacy ASP.NET Core Rendering SDK, version 22 or earlier. This SDK is no longer receiving updates, so we recommend that you [upgrade to the latest version of the new](https://doc.sitecore.com/xmc/en/developers/asp-net/latest/asp-net-core-sdk/upgrade-from-v22.html) .

The Sitecore Rendering Engine renders content fetched from a Sitecore instance using the [Sitecore Layout Service](https://doc.sitecore.com/xp/en/developers/hd/21/sitecore-headless-development/sitecore-layout-service.html "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](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/startup?view=aspnetcore-3.1).

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:

```csharp
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.

    ```csharp
    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](https://doc.sitecore.com/xp/en/developers/hd/21/sitecore-headless-development/view-types.html "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:

    ```csharp
    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:

```csharp
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:

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

```

> [!note]
> This attribute can also be applied on the Controller itself.