Currently, Sitecore is working on the new ASP.NET Core Starter Kit for Sitecore XM Cloud development. The GitHub repository is here https://github.com/Sitecore/xmcloud-starter-dotnet. This blog explains better some steps required for the configuration indicated in the GitHub repository with additional screenshots. Go through the code to inspect the new libraries created for this project. Finally, GraphQL examples are shown to retrieve the content.
- Pre-requisites
- Sitecore XM Cloud access/account
- Visual Studio 2022
2. Steps explanation to configure the ASP.NET Core Starter Kit
Step 1. Create a repository from this template.
Access to the URL https://github.com/Sitecore/xmcloud-starter-aspnetcore. Create a new fork
As a prerequisite, you have access to your GitHub account. Provide the owner with your GitHub account.
Step 3. Create a new project using the ‘bring your code’ option, and select the repository you created in step 1.
1. Create a new project
2. Connect to the GitHub option selected
3. Use your own code to connect to your account, repository, and branch
4. New environment name, production site, and auto-deploy options.
5. Summary and start the deployment
Step 4. When the deployment has finished click the “Go to XM Cloud” button to open the XM Cloud Environment.
Go to XM Cloud on deployment completed
Step 5. Click on the Sites link in the top menu
Step 6. Click the Create Site button
Step 7. Select the ‘Empty Site’ template
Step 8. Enter a name for the site and click the Create site button. Make a note of the chosen site name.
New site option to provide the name and language
Step 9-10. When completed click the Tools link in the top menu. Click the Content Editor button
Tools and Content Editor options
Step 12-13. Navigate to /sitecore/system/Settings/Services/API Keys. Right-click on the API Keys Folder Item and choose Insert -> API Key.
Insert- API Key.
Step 14. Give the API Key a name and click the OK button.
Step 15-16. Make a note of the generated Item ID (This is located in the Quick Info panel). Set the following Field values on the API Key item, and click Save to persist the changes.
CORS Origins–*Allowed Controllers–*
Set CORS Origins and Allowed Controllers fields
Step 18. Click on the developer settings button and take note of the JSS_EDITING_SECRET value.
Developer settings and environment variable values.
3. New page and components
I created the home page with a title, page content, rich text, and image components.
The content in the CMS looks like this for the home page.
4. Code and GraphQL example
4.1 Package references
The SDK solution has 3 package reference:
- Sitecore.AspNetCore.SDK.ExperienceEditor
- Sitecore.AspNetCore.SDK.LayoutService.Client
- Sitecore.AspNetCore.SDK.RenderingEngine
Decompiling 2 libraries, are similar to the following existing ones for a similar Sitecore product which is ASP.NET Rendering SDK:
- Sitecore.LayoutService.Client.dll. Here is the documentation https://doc.sitecore.com/xp/en/developers/hd/latest/sitecore-asp-dot-net-rendering-sdk/sitecore.layoutservice.client.html
- Sitecore.AspNet.RenderingEngine. Here is the documentation https://doc.sitecore.com/xp/en/developers/hd/latest/sitecore-asp-dot-net-rendering-sdk/sitecore.aspnet.renderingengine.html
4.2 Layout service example
According to the Sitecore layout service documentation (https://doc.sitecore.com/xp/en/developers/hd/latest/sitecore-headless-development/layout-service.html), it is known as an endpoint that exposes Sitecore information as JSON. For example, to get the output of the whole layout and item.
/sitecore/api/layout/render/[config]?item=[path]&sc_lang=[language]&sc_apikey=[key]&tracking=[true|false]&sc_site=[your-site-name]
The site demo created for this blog looks like this:
When it is executed in Postman the query to get the Layout service information for the home item.
The following JSON is returned grouped by placeholders. The Title component is indicated below.
Besides the Richtext component.
Bellow the Image component.
4.3 GraphQL example
First, I tested the GraphQL query through the API playground. The playground configuration is indicated in this link https://doc.sitecore.com/xmc/en/developers/xm-cloud/set-up-the-graphql-playgrounds-to-test-published-content.html#set-up-the-preview-api-playground
The following GraphQL query gets the root item of the site demo.
The same GraphQL query can be executed from the code through a new API service named graphql. Bellow the code.
[HttpGet("graphql")]
public GraphQLResponse<dynamic> ExecuteGraph()
{
try
{
using (var client = new GraphQLHttpClient(new Uri("https://<your host>/sitecore/api/graph/edge/"), new SystemTextJsonSerializer()))
{
client.HttpClient.DefaultRequestHeaders.Add("sc_apikey", "<your apiKey>");
var request = new GraphQLRequest()
{
Query = $@"query {{
layout(site: ""demo"", routePath: ""/"", language: ""en"") {{
item {{
homeItemPath: path
contentRoot: parent {{
id
path
}}
}}
}}
}}"
};
return client.SendQueryAsync<dynamic>(request).Result;
}
}
catch(Exception)
{
throw;
}
}Executing the new API service named “graphql” in Postman the results are returned. Similar results were returned on the GraphQL playground.
5. Conclusions
Although it is a pre-release version, this starter kit can be valuable for .NET developers with more expertise in this technology. This starter kit introduces the configuration of the dev tunnel which improves the development time with no docker dependency required to set up the environment. The developer can configure the initial solution easily and start working on the new functionalities in connected mode. Going through the code, the existing ASP.NET Rendering SDK released some years ago with Sitecore 10 has been taken as a base to create the new libraries included in this Starter Kit. GraphQL works appropriately to retrieve the content data. We expect to have new features incorporated/added to this Starter Kit in the coming months and count on a complete framework for XMCloud Sitecore development. Thanks and send me your comments/questions.