The Sitecore ASP.NET Core SDK is a flexible and developer-friendly way to build apps using ASP.NET Core technology.
In this post, I’ll help you through getting started with the ASP.NET Core SDK for Sitecore, including explaining why you’d use it, and how to spin up your first project using the Starter Kit.
Preface
If you haven’t already checked out Rob Earlam’s excellent introductory videos, please look:
· Getting started with ASP.NET Core and XM Cloud by Rob Earlam
· Building XM Cloud sites using ASP.NET
Rob is leading the charge on the SDK development and his videos will give you all the background information you need. I won’t be going over the introductory aspects in this post – I am assuming you have some familiarity with XM Cloud and that you already have an environment provisioned. Instead, I want to show you the steps required to get the Starter Kit up and running using the ASP.NET Core SDK and discuss a few architectural concerns should you come across them when starting a new project.
I will reference the ASP.NET Core SDK and Starter Kit repositories too:
· Sitecore/xmcloud-starter-dotnet
Why Use It?
The main reason you would consider the ASP.NET Core SDK is because your organization is already heavily invested in the Microsoft stack and continues to see Azure as an important part of your technology roadmap.
Your headless technology stack options are exploding right now and sticking with what you already know is a perfectly valid reason to stay on the .NET stack. I also believe that the .NET stack continues to offer the best performance and flexibility when building modern web apps.
Here are a few more reasons why you might choose the ASP.NET Core SDK:
- Native .NET Core experience – Leverages all the performance and flexibility of ASP.NET Core application.
- Azure benefits – Hosts your site on Azure using App Services or Containers running Windows OR Linux.
- Scale with Azure – Uses Azure Front Door to scale globally and serve both static and dynamic content.
- Composable architecture – Not limited to any front-end technology. You can still use your favorite JS and CSS libraries, just be aware that all the server-side rendering is done using ASP.NET Core and Razor views.
What is missing?
The ASP.NET Core SDK is still missing a few features, such as Personalization, Forms and Components. Metadata editing is also missing from the main branch, but I have been able to successfully get it working. I share the steps with you below because metadata editing is a critical feature that allows multiple developers to work at the same time using a shared XM Cloud environment and I couldn’t recommend the SDK without it.
In Rob’s videos above, he quickly covers the remaining effort to get metadata editing working, but some important details are missing. Here is what I have done to get it working with the Starter Kit:
· The Metadata editing feature is currently in a feature branch in the SDK repository waiting to be completed (Pages MetaData Editing Mode Support by robearlam · Pull Request #29 · Sitecore/ASP.NET-Core-SDK). Clone the repo and merge the feature branch into main.
· The Starter Kit references the published ASP.NET Core SDK NuGet packages by default. Because you’re working with a merged feature branch and a pre-release version of the SDK, you’ll also want to change the Starter Kit to reference the SDK projects locally. You could also build the SDK .sln separately and reference the DLLs directly in your project, just remember to reference all the dependent assemblies (GraphQL, HtmlAgilityPack, etc). Once the SDK officially support metadata editing you can go back to referencing the NuGet packages directly. Having the SDK projects as part of your own solution means you can easily resolve any issues you might come across in the SDK at this early stage.
The rest of the changes need to be done in the Starter Kit:
· _ViewImports.cshtml needs the Pages TagHelper reference added:
· Program.cs requires multiple changes to add Metadata editing support to Page Builder. Most of these changes you can infer from the tests included in Rob’s feature branch:
a. Add the Pages handler to the Layout Service:
b. Make the Rendering Engine aware:
c. When in editing mode, enable Pages support:
d. Add a route to support Pages:
e. Add the <sc_editingscript /> tag to your _layout.cshtml file:
Almost there…
The final few steps relate to infrastructure and deployment and will depend on your own specific project needs.
Sitecore XM Cloud does not yet support built-in ASP.NET Core authoring environment, so you must provide an external exiting host. Best to use an Azure App Service for this, so go ahead and create an Azure App Service using .NET 8 (LTS).
Deploy your modified starter kit solution to your App Service. Be sure to exclude your appsettings.Development.json file from the publish profile or you might wonder why things aren’t working.
I suggest adding your XM Cloud environment’s editing secret to an Azure config variable (Sitecore:EditingSecret) or use KeyVault to avoid including it in your appsettings.json file.
Lastly, let Sitecore know about your new external editing host under Settings > Services > Rendering Hosts > Default:
Provide your App Service endpoint details here and you’re good to go.
You should now be able to pull up the Starter Kit in your XM Cloud environment using Page Builder. You should also be able to seamlessly switch between your external editing host and your local machine using the editing host switcher:
Final thoughts
After some experimentation, the SDK seemed to do exactly what is described on the tin. I can create pages, add components to placeholders, edit data sources and styles. I can see Experience Edge returning layout data and can attach a debugger to a locally running app to walk through the SDK and Starter Kit code to see exactly how the rendering happens.
Before you jump to using the SDK in production, be aware that the SDK is still described as being ‘prerelease’ or ‘alpha’. In addition to the missing features, this may mean there a some undiscovered showstopping bugs lurking in the SDK. You should review the commit history of the SDK in GitHub and the issues that have been created to get additional insight as to what lies ahead.
For high performance production scenarios, you will want an additional rendering host just for content delivery, likely another App Service fronted by Azure Front Door with a custom domain. Azure Front Door gives you some of the additional features that you get with the likes of Netlify and Vercel, such as routing, caching, SSL offloading, compression and extra security features. Optionally, you could add a route specifically for APIs and point that to an Azure Function App. You could also create a cookie-less subdomain and have Azure Front Door cache all your static assets. These are wonderful topics for a future post.