There are many situations where you may want to use data stored in Sitecore XM or XP on an external site, and this step-by-step guide explains how to add a customized Web API on Sitecore XM/XP 10.2.
System Requirements
- Visual Studio 2019 or higher (The author's environment is Visual Studio 2022)
- NET Framework 4.8
- Windows 10
- Sitecore XM/XP 10.2
Target audience
- Sitecore Developers
Preparation
Add Sitecore to NuGet package sources
Open Visual Studio configuration.
- select Package Sources
- click on +
- Select the added Package srouces
- Enter
Sitecorefor Name andhttps://sitecore.myget.org/F/sc-packages/api/v3/index.jsonfor Source - Click
Update - Click
OK.
That's all.
Complete Repository
Here is the completed source so you can build and try it out right away.
https://github.com/nnasaki/SimpleWebApi
Steps to create a new solution
Create new solution
Select ASP.NET Web Application(.NET Framework), note that it is not ASP.NET Core.
Enter the Project name. Make sure again that the Framework is .NET Framework 4.8.
Select Empty as the Project Type. Uncheck all the checkboxes on the right side.
Press Create to finish creating a new solution and project.
Add a NuGet package
From Visual Studio Tools, click Package Manager Console under Nuget Package Manager.
When the Package Manager Console appears at the bottom of the screen, type Install-Package Sitecore.Services.Infrastructure !
If you see Successfully installed like this, it is successful. It took about 2 minutes in my environment.
Add controllers
Add a folder of Controllers and add a class
Enter SimpleWebApiController and click Add
Enter the following code
using Sitecore.Services.Infrastructure.Web.Http;
using System.Web.Http;
using System.Web.Http.Cors;
namespace SimpleWebApi.Controllers
{
// TODO Be sure to narrow down the CORS settings in the production environment. This is all allowed.
[EnableCors(origins: "*", headers: "*", methods: "*")]
public class SimpleWebApiController : ServicesApiController
{
public SimpleWebApiController()
{
}
[HttpGet]
public string Stats()
{
return "ok SimpleWebApi";
}
}
}
Add route definition
Same procedure as for the controller. Add the Pipelines folder and add the RegisterHttpRoutes class.
Enter the following code
using System.Web.Http;
using Sitecore.Pipelines;
namespace SimpleWebApi.Pipelines
{
public class RegisterHttpRoutes
{
public void Process(PipelineArgs args)
{
GlobalConfiguration.Configure(Configure);
}
protected void Configure(HttpConfiguration configuration)
{
var routes = configuration.Routes;
routes.MapHttpRoute("SimpleWebApi.stats", "api/simplewebapi/stats", new
{
controller = "SimpleWebApi",
action = "Stats"
});
}
}
}
Add config.
Create a hierarchical folder App_Config\Include\ZZZZZ_CustomConfigs and add SimpleWebApi.config.
Enter the following settings
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"
xmlns:set="http://www.sitecore.net/xmlconfig/set/"
xmlns:role="http://www.sitecore.net/xmlconfig/role/">
<sitecore>
<pipelines>
<initialize>
<processor
type="SimpleWebApi.Pipelines.RegisterHttpRoutes, SimpleWebApi" />
</initialize>
</pipelines>
</sitecore>
</configuration>
Deploy
Deploy the built module
Add dll to bin
Copy the SimpleWebApi.dll created in the project bin to C:\inetpub\wwwroot\sitecoresc.dev.local\bin in IIS. Rewrite the sitecoresc.dev.local part in your environment.
!
Add configurations to include
Copy SimpleWebApi.config added to the project to C:\inetpub\wwwroot\sitecoresc.dev.local\App_Config\Include\ZZZZZ_CustomConfigs.
Check the operation
Access the API
Access the site where Sitecore is deployed using a browser.
In this example, access https://sitecoresc.dev.local/api/simplewebapi/stats and check it.
If the deployment is successful, you will see a simple "ok SimpleWebApi" as shown below.
If you encounter errors, please see Troubleshooting.
Summary
As shown in this article, Sitecore can be easily customized, so please try it out.
Troubleshooting
Here is a summary of the errors I encountered while trying it out and how I handled them.
No type was found that matches the controller named 'MinimumTest4'
Error details.
{"Message": "No HTTP resource was found that matches the request URI 'https://sitecoresc.dev.local/api/minimumtest4/stats'." , "MessageDetail": "No type was found that matches the controller named 'MinimumTest4'"}
Solution.
There are two patterns.
1. Controller name is incorrectly set in MapHttpRoute.
Please check if the controller name is correct. If MinimumTest4Controller is the controller name, specify up to MinimumTest4 without Controller.
2. optimizeCompilations="true" is enabled in Web.config
In Web.config, set <compilation defaultLanguage="c#" debug="true" targetFramework="4.8" optimizeCompilations="true"> like this If optimizeCompilations is true, set optimizeCompilations="false".
optimizeCompilations is a feature that can speed up reloading when updating modules, but new pipeline processors may not be recognized. It is usually better to set it to false.
A route named 'MinimumTestApi.stats' is already in the route collection. Route names must be unique.
Error details.
Server Error in '/' Application.
A route named 'MinimumTestApi.stats' is already in the route collection.
Parameter name: name
Description: An unhandled exception occurred during the execution of the current web request. Please review the stack trace for more information about the error and where it originated in the code.
Exception Details: System.ArgumentException: A route named 'MinimumTestApi.stats' is already in the route collection.
Parameter name: name
Source Error:
An unhandled exception was generated during the execution of the current web request. Information regarding the origin and location of the exception can be identified using the exception stack trace below.
Solution
The definition name of MapHttpRoute is shared by another module. Change the definition name of MapHttpRoute in RegisterHttpRoutes.cs.
"Multiple types were found that match the controller named 'MinimumTestApi'
Error Details.
{"Message": "An error has occurred.", "ExceptionMessage": "Multiple types were found that match the controller named 'MinimumTestApi'. This can happen if the route that services this request ('api/minimumtest3/stats') found multiple controllers defined with the same name but differing namespaces, which is not supported. \r\n\r\nThe request for 'MinimumTestApi' has found the following matching Controllers:\r\nMinimumTest.Controllers.MinimumTestApiController\r\nMinimumTest.Controllers.MinimumTestApiController", "ExceptionType": "System.InvalidOperationException", "StackTrace":"" at System.Web.Http.Dispatcher.DefaultHttpControllerSelector.SelectController(HttpRequestMessage request)\r\n at System.Web.Http.Dispatcher.HttpControllerDispatcher.<SendAsync>d__15.MoveNext()"}
Solution.
Name resolution is not working because there is a duplicate controller class name with another module. Change the controller class name to something else.
Top comments (0)