Skip to main content

JavaScript Client for CoreService

This blog post shows a way to connect to CoreService directly from a JavaScript client. The CoreService is a WCF web-service, which by default uses SOAP to communicate with its clients. However, it is quite simple to convert it into a REST service that accepts plain POST requests with parameters sent in the request body.

To keep things simple, I secured the REST endpoint with Basic auth, and thus made use of the Basic Authenticator handler over an HTTPS connection.

The Server

The WCF framework allows us to easily expose any web-service as a REST service. For this, I had to modify the file [SDLWebHome]\webservices\Web.config, and add an endpoint behavior under node <system.serviceModel> / <behaviors>. The new behavior enables endpoint to be accessible as REST service:

  <endpointBehaviors>
    <behavior name="MyJS">
      <enableWebScript />
    </behavior>
  </endpointBehaviors>

Next, because we want to use HTTPS, we define a web HTTP binding with security mode Transport, under node <system.serviceModel> / <bindings>:

  <webHttpBinding>
    <binding name="MyHttps">
      <security mode="Transport"/>
    </binding>
  </webHttpBinding>

Next, under our CoreService service definition, we add a new endpoint based on the new MyJS behavior and using the MyHttps binding. Add the following node under <system.serviceModel> / <services>:

  <service behaviorConfiguration="Tridion.ContentManager.ServiceHost.IISHost.CoreServiceBehavior"
    name="Tridion.ContentManager.ServiceHost.IISHost.CoreService201603">

    <endpoint binding="webHttpBinding" bindingConfiguration="MyHttps" behaviorConfiguration="MyJS"
      bindingNamespace="http://www.sdltridion.com/ContentManager/CoreService/201603"
      contract="Tridion.ContentManager.CoreService.ICoreService201603" address="rest" />

This configuration enables a new endpoint rest under the service CoreService201603.svc that accepts HTTPS POST requests to interact with the CoreService. Namely, the endpoint is https://web85.playground/webservices/CoreService201603.svc/rest

Even more so, the endpoint automatically generates JavaScript proxy classes based on the contract interface defined (i.e. Tridion.ContentManager.CoreService.ICoreService201603). These proxies can be used directly from the server, by loading the following script URL directly in the client web page: https://web85.playground/webservices/CoreService201603.svc/rest/js



We need to configure one last thing – we must allow cross site scripting. The client JavaScript that will consume our CoreService REST endpoint will most likely make calls to the REST endpoint from a different machine than our Content Manager. This means, we need to configure the remote IPs and the headers that are accepted to make REST calls. For example, a simple way to configure this is to add Access-Control response headers in file [SDLWebHome]\webservices\Web.config, under node <system.webServer>:

  <httpProtocol>
    <customHeaders>
      <add name="Access-Control-Allow-Methods" value="POST,OPTIONS" />
      <add name="Access-Control-Allow-Origin" value="*" />
      <add name="Access-Control-Allow-Headers" value="Authorization, Content-Type, X-Requested-With" />
    </customHeaders>
  </httpProtocol>

The Client

The JS proxies generated by the REST endpoint are readily usable, if we use the MicrosoftAjax framework. This is the easiest and quickest way to get the client application going. However, there is one big drawback – the MicrosoftAjax framework doesn’t accept any kind of security configuration when making the AJAX calls to the service (or at least I couldn’t figure it out). Our service requires Basic auth, and it seems there is no way to specify that in the MicrosoftAjax framework. Of course, one can always modify the JS source of the framework, but that would be a hack :)

In Microsoft Visual Studio (I used 2015), create a new project of type Visual C# / Web / ASP.NET Web Application. This creates all the skeleton code that is needed, including the MicrosoftAjax JS classes.

The following sample page makes a call to CoreService using the automatically generated proxy classes and MicrosoftAjax framework. Note that this code does not work OOTB in our case, because we are not sending a Basic auth request header:

<html>
<head>
    <script src="/Scripts/jquery-1.10.2.js"></script>
    <script src="/Scripts/WebForms/MSAjax/MicrosoftAjax.js"></script>
    <script src="https://web85.playground/webservices/CoreService201603.svc/rest/js"></script>
</head>
<body>
    <script>
        var service = new www.sdltridion.com.ContentManager.CoreService._201603.ICoreService();
        service.GetApiVersion(function (result) {
            alert(result);
        });
    </script>
</body>
</html>

The parameter method to GetApiVersion is a callback function that is called if the GetApiVersion invocation is a success. The response from the service is inside variable result.

Conclusion

This is a quick and elegant way of exposing a WCF service as a RESTful API without having to rewrite any server code.

The client however is not very configurable, because we can’t set an authentication method, unless we change the actual framework.

In a follow-up post, I will show a purely JQuery client that doesn’t depend or use MicrosoftAjax framework, it is much more configurable, and overall smaller in size, but we must write our skeleton proxy classes ourselves.



Comments

Popular posts from this blog

A DD4T.net Implementation - Custom Binary Publisher

The default way to publish binaries in DD4T is implemented in class DD4T.Templates.Base.Utils.BinaryPublisher and uses method RenderedItem.AddBinary(Component) . This produces binaries that have their TCM URI as suffix in their filename. In my recent project, we had a requirement that binary file names should be clean (without the TCM URI suffix). Therefore, it was time to modify the way DD4T was publishing binaries. The method in charge with publishing binaries is called PublishItem and is defined in class BinaryPublisher . I therefore extended the BinaryPublisher and overrode method PublishItem. public class CustomBinaryPublisher : BinaryPublisher { private Template currentTemplate; private TcmUri structureGroupUri; In its simplest form, method PublishItem just takes the item and passes it to the AddBinary. In order to accomplish the requirement, we must specify a filename while publishing. This is the file name part of the binary path of Component.BinaryConten

Toolkit - Dynamic Content Queries

This post if part of a series about the  File System Toolkit  - a custom content delivery API for SDL Tridion. This post presents the Dynamic Content Query capability. The requirements for the Toolkit API are that it should be able to provide CustomMeta queries, pagination, and sorting -- all on the file system, without the use third party tools (database, search engines, indexers, etc). Therefore I had to implement a simple database engine and indexer -- which is described in more detail in post Writing My Own Database Engine . The querying logic does not make use of cache. This means the query logic is executed every time. When models are requested, the models are however retrieved using the ModelFactory and those are cached. Query Class This is the main class for dynamic content queries. It is the entry point into the execution logic of a query. The class takes as parameter a Criterion (presented below) which triggers the execution of query in all sub-criteria of a Criterio

Event System to Create Mapped Structure Groups for Binary Publish

As a continuation of last week's Publish Binaries to Mapped Structure Group , this week's TBB is in fact the Event System part of that solution. Make sure you do check out the previous post first, which explains why and what this Event System does. To reiterate, the Event System intercepts a Multimedia Component save, take its Folder path and create a 1-to-1 mapping of Structure Groups. The original code was written, again, by my colleague Eric Huiza : [ TcmExtension ( "MyEvents" )] public class EventsManager  : TcmExtension {     private Configuration configuration;     private readonly Regex SAFE_DIRNAME_REGEX = new Regex ( @"[\W_]+" );     public EventsManager() {         ExeConfigurationFileMap fileMap = new ExeConfigurationFileMap ();         fileMap.ExeConfigFilename = Path .GetDirectoryName( Assembly .GetExecutingAssembly().Location) + "\\EventSystem.config" ;         configuration = ConfigurationManager