Web API Correlator requires Correlator.dll on the .NET side, and jquery.ajax.correlator.min.js file on the javascript client-side, if applicable.

Index

Setup and Initialization

Javascript client-side (using jQuery)
The code within jquery.ajax.correlator.min.js initializes new Correlation Id and maintains this Id for the duration of a browser session using browser's sessionStorage.
Server-side (.NET)
The ClientCorrelationHandler is responsible for capturing and propagation of the Correlation Id over to the server-side Web API processing. Use the following code to add ClientCorrelationHandler to Web API processing pipeline:
public void Configuration(IAppBuilder appBuilder)
{
    HttpConfiguration config = new HttpConfiguration();
    //...configure application as necessary...

    Correlator.Handlers.ClientCorrelationHandler correlatorHnd = 
                         new Correlator.Handlers.ClientCorrelationHandler();
    //add correlation handler to the Web API pipeline
    config.MessageHandlers.Add(correlatorHnd);

    //...continue to configure application as necessary...
}

How do I enable or disable Correlation Id propagation from API client to the server process?

Assuming that client sends a Correlation Id, when the ClientCorrelationHandler is being created, the following setting assures propagation:
    Correlator.Handlers.ClientCorrelationHandler correlatorHnd = 
                         new Correlator.Handlers.ClientCorrelationHandler();
    //turn on propagation of correlation id received from the client 
    //to the server-side service context
    correlatorHnd.Propagate = true;

    //add correlation handler to the Web API pipeline
    config.MessageHandlers.Add(correlatorHnd);
The default value for this setting is true. Set the Propagate property to false to disable the propagation.

Are there any other configuration options available for ClientCorrelationHandler?

There are two more configuration options available for the ClientCorrelationHandler:
  • InitializeIfEmpty - ensures that current Web API Correlation Id is sent to the client with a response, if request lacks one; by default is false;
  • TraceCorrelation - enables the handler to record a trace message with related information; by default is false;
    Correlator.Handlers.ClientCorrelationHandler correlatorHnd = 
                          new Correlator.Handlers.ClientCorrelationHandler();
    correlatorHnd.InitializeIfEmpty = true;
    correlatorHnd.TraceCorrelation = true;

    //add correlation handler to the Web API pipeline
    config.MessageHandlers.Add(correlatorHnd);

How do I update the Correlation Id?

Javascript client-side (using jQuery)
In most cases it is beneficial to keep the same Correlation Id throughout the entire browser session to establish relations between all related activities. If new Correlation Id should be used, the following code will renew Correlation Id to an automatically generated value:
    //renew correlation Id
    $.correlator.renewCorrelationId();

This code updates Correlation Id to a custom value (should be GUID-like string; the hyphens are optional):
    //set custom correlation Id
    var customid = "a2b2b2ae-b6fb-4f06-9969-85e14965d422";
    $.correlator.setCorrelationId(customid);
Server-side (.NET)
The server-side automatically generates and propagates Correlation Id. Updating this value will defeat the purpose and therefore such functionality is not available nor from Web API framework implementation, nor from the Correlator.

How do I propagate the Correlation Id from Web API to another interconnected service?

If the service call is being issued from within a Web API call, the following code would propagate Correlation Id from current context to interconnected service:
using Correlator.Extensions;
...
using (HttpClient client = new HttpClient())
{
    //ensure correlation id for the HTTP client
    client.EnsureCorrelationId(this.Request.GetCorrelationId());
    //from now on all request being made by the HTTP client 
    //would have the same correlation id as current context
    response = await client.GetAsync("http://localhost:9090/api/...");
}

How do I add custom Correlation Id to HttpClient or WebClient when making call to remote service?

Review the example above if you need to propagate Correlation Id from Web API to another interconnected service. In other cases the following code would ensure a custom Correlation Id is being sent with the service request:
using Correlator.Extensions;
...
using (HttpClient client = new HttpClient())
{
    //ensure correlation id for the HTTP client
    Guid correlationId = ...obtain custom Guid within the application...
    client.EnsureCorrelationId(correlationId);
    //from now on all request being made by the HTTP client 
    //would have the same correlation id
    response = await client.GetAsync("http://localhost:9090/api/...");
}

How do I obtain current Correlation Id?

Javascript client-side (using jQuery)
    //obtain current correlation Id
    var cid = $.correlator.getCorrelationId();
Server-side (.NET)
Assuming that Request is current HttpRequestMessage, the following code would provide the Correlation Id:
using Correlator.Extensions;
...
    //obtain current server-side correlation id 
    //(would be the same as client-side if propagate=true)
    Guid srvCorrId = Request.GetCorrelationId();

    //obtain current client-side correlation id 
    //(would be the same as server-side if propagate=true)
    Guid clientCorrId = Request.GetClientCorrelationId();

Can I use this project if my client is written in a language other than .NET or javascript?

You may use the Correlator with the server-side Web API as long as your client provides X-CorrelationId HTTP header with every HTTP request.


Last edited Jul 9, 2014 at 11:56 PM by lennygran, version 3