Upgrade from ASP.NET Core Rendering SDK version 22 to the latest ASP.NET Core SDK

Version: 0.x (alpha public release)

If you integrated your ASP.NET Core app before September 2024, it's using the legacy Sitecore 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 Sitecore ASP.NET Core SDK.

This topic describes how to upgrade from version 22 of the ASP.NET Core Rendering SDK to the latest version of the new ASP.NET Core SDK.

The majority of the upgrade work involves uninstalling old packages and installing new ones in your solution, and finding and replacing old namespaces, tag helpers, and models with new ones. We recommend that you perform the upgrade using Visual Studio.

This walkthrough was tested on the MyProject solution created from the Getting Started template.Walkthrough: Using the Getting Started template

Before you begin

  • Install the .NET Core 8.0 SDK. Check your installed version by using the dotnet --version command.

To upgrade your solution to the latest ASP.NET Core SDK:

  1. Upgrade your solution to use .NET Core 8.0.

  2. In the root folder of your ASP.NET Core app, in init.ps1, update the .NET Core SDK version from 6.0 to 8.0:

    Old

    New

    Set-EnvFileVariable "DOTNET_VERSION" -Value "6.0"

    Set-EnvFileVariable "DOTNET_VERSION" -Value "8.0"

  3. In nuget.config, inside <packageSources>, remove all Sitecore-related sources, then add the following:

    RequestResponse
    <add key="Sitecore" value="https://nuget.sitecore.com/resources/v3/index.json" />
<add key="SitecoreGallery" value="https://nuget.sitecore.com/resources/v2/" />

  4. Using a terminal or Visual Studio, uninstall the following old packages from all projects in your solution:

    • Sitecore.AspNet.ExperienceEditor

    • Sitecore.AspNet.GraphQL

    • Sitecore.AspNet.MetaPackage

    • Sitecore.AspNet.RenderingEngine

    • Sitecore.AspNet.RenderingEngine.Abstractions

    • Sitecore.AspNet.SearchOptimization

    • Sitecore.AspNet.Tracking

    • Sitecore.AspNet.Tracking.VisitorIdentification

    • Sitecore.LayoutService.Client

    • Sitecore.LayoutService.Client.Abstractions

    • Sitecore.LayoutService.Client.Json

    • Sitecore.LayoutService.Client.Newtonsoft

  5. Depending on your application requirements, install the following packages as needed:

    • Sitecore.AspNetCore.SDK.ExperienceEditor - lets you edit and preview content in XM Cloud Pages while developing your app with the ASP.NET Core SDK.

    • Sitecore.AspNetCore.SDK.LayoutService.Client - lets you retrieve layout data from Sitecore Experience Edge.

    • Sitecore.AspNetCore.SDK.RenderingEngine - enables your ASP.NET Core app to display XM Cloud content.

  6. In Visual Studio, across the entire solution, replace the following old namespaces, tag helpers, and models with new ones:

    Old

    New

    using Sitecore.AspNet.ExperienceEditor

    using Sitecore.AspNetCore.SDK.ExperienceEditor.Extensions

    using Sitecore.LayoutService.Client.Exceptions

    using Sitecore.AspNetCore.SDK.LayoutService.Client.Exceptions

    using Sitecore.LayoutService.Client.Extensions

    using Sitecore.AspNetCore.SDK.LayoutService.Client.Extensions

    using Sitecore.LayoutService.Client.Response.Model

    using Sitecore.AspNetCore.SDK.LayoutService.Client.Response.Model

    using Sitecore.LayoutService.Client.Response.Model.Fields

    using Sitecore.AspNetCore.SDK.LayoutService.Client.Response.Model.Fields

    using Sitecore.AspNet.RenderingEngine

    using Sitecore.AspNetCore.SDK.RenderingEngine

    using Sitecore.AspNet.RenderingEngine.Binding

    using Sitecore.AspNetCore.SDK.RenderingEngine.Binding

    using Sitecore.AspNet.RenderingEngine.Binding.Attributes

    using Sitecore.AspNetCore.SDK.RenderingEngine.Binding.Attributes

    using Sitecore.AspNet.RenderingEngine.Configuration

    using Sitecore.AspNetCore.SDK.RenderingEngine.Configuration

    using Sitecore.AspNet.RenderingEngine.Extensions

    using Sitecore.AspNetCore.SDK.RenderingEngine.Extensions

    using Sitecore.AspNet.RenderingEngine.Middleware

    using Sitecore.AspNetCore.SDK.RenderingEngine.Middleware

    @addTagHelper *, Sitecore.AspNet.RenderingEngine

    @addTagHelper *, Sitecore.AspNetCore.SDK.RenderingEngine

    @model Sitecore.LayoutService.Client.Response.Model.Component

    @model Sitecore.AspNetCore.SDK.LayoutService.Client.Response.Model.Component

  7. Across your solution, find and remove the following:

    • using Sitecore.LayoutService.Client.Newtonsoft.Extensions

    • AddNewtonsoftJson

  8. Optionally, we recommend that you enable nullable reference types in all projects in your solution.

  9. In Visual Studio, click Build > Build solution.

    The build will initially fail because of compilation errors. This is expected because you updated the namespaces.

    If you enabled nullable references types, the error list might also contain nullability warnings.

  10. For each compilation error, confirm that you want to use the new namespaces suggested by Visual Studio.

  11. For each nullability warning, choose your new nullability strategy according your application needs and fix your code accordingly.

  12. Click Build > Build solution again. When the solution finishes building, it will use the new Sitecore ASP.NET Core SDK.

Experience Edge is a service where XM Cloud content, such as webpages, site layout, navigation, and other elements, are published. Experience Edge delivers this content to various channels, such as web apps, mobile apps, airport check-in kiosks, email, SMS, wearables, AI-enabled voice assistants, VR headsets, IoT devices, and more.

Do you have some feedback for us?

If you have suggestions for improving this article,