Quickstart: Recognize digital ink with the Ink Recognizer REST API and C#

Use this quickstart to begin sending digital ink strokes to the Ink Recognizer API. This C# application sends an API request containing JSON-formatted ink stroke data, and gets the response.

While this application is written in C#, the API is a RESTful web service compatible with most programming languages.

Typically you would call the API from a digital inking app. This quickstart sends ink stroke data for the following handwritten sample from a JSON file.

an image of handwritten text

The source code for this quickstart can be found on GitHub.

Prerequisites

  • Any edition of Visual Studio 2017.

  • Newtonsoft.Json

    • To install Newtonsoft.Json as a NuGet package in Visual studio:
      1. Right click on the Solution Manager
      2. Click Manage NuGet Packages...
      3. Search for Newtonsoft.Json and install the package
  • If you are using Linux/MacOS, this application can be ran using Mono.

  • The example ink stroke data for this quickstart can be found on GitHub.

You must have a Cognitive Services API account with access to the Ink Recognizer API. If you don't have an Azure subscription, you can create an account for free. You can get your subscription key from the Azure portal after creating your account, or Azure website after activating a free trial.

Create a new application

  1. In Visual Studio, create a new console solution and add the following packages.

    using System;
    using System.IO;
    using System.Net;
    using System.Net.Http;
    using System.Net.Http.Headers;
    using System.Text;
    using System.Threading.Tasks;
    using Newtonsoft.Json;
    using Newtonsoft.Json.Linq;
    
  2. Create variables for your subscription key and your endpoint. Below is the URI you can use for ink recognition. It will be appended to your service endpoint later to create the API request URl.

    // Replace the subscriptionKey string with your valid subscription key.
    const string subscriptionKey = "YOUR_SUBSCRIPTION_KEY";
    
    // Replace the dataPath string with a path to the JSON formatted ink stroke data.
    const string dataPath = @"PATH-TO-INK-STROKE-DATA"; 
    
    // URI information for ink recognition:
    const string endpoint = "https://api.cognitive.microsoft.com";
    const string inkRecognitionUrl = "/inkrecognizer/v1.0-preview/recognize";
    

Create a function to send requests

  1. Create a new async function called Request that takes the variables created above.

  2. Set the client's security protocol and header information using an HttpClient object. Be sure to add your subscription key to the Ocp-Apim-Subscription-Key header. Then create a StringContent object for the request.

  3. Send the request with PutAsync(). If the request is successful, return the response.

    static async Task<string> Request(string apiAddress, string endpoint, string subscriptionKey, string requestData){
    
        using (HttpClient client = new HttpClient { BaseAddress = new Uri(apiAddress) }){
            System.Net.ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12 | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls;
            client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
    
            var content = new StringContent(requestData, Encoding.UTF8, "application/json");
            var res = await client.PutAsync(endpoint, content);
            if (res.IsSuccessStatusCode){
                return await res.Content.ReadAsStringAsync();
            }
            else{
                return $"ErrorCode: {res.StatusCode}";
            }
        }
    }
    

Send an ink recognition request

  1. Create a new function called recognizeInk(). Construct the request and send it by calling the Request() function with your endpoint, subscription key, the URL for the API, and the digital ink stroke data.

  2. Deserialize the JSON object, and write it to the console.

    static void recognizeInk(string requestData){
    
        //construct the request
        var result = Request(
            endpoint,
            inkRecognitionUrl,
            subscriptionKey,
            requestData).Result;
    
        dynamic jsonObj = Newtonsoft.Json.JsonConvert.DeserializeObject(result);
        System.Console.WriteLine(jsonObj);
    }
    

Load your digital ink data

Create a function called LoadJson() to load the ink data JSON file. Use a StreamReader and JsonTextReader to create a JObject and return it.

public static JObject LoadJson(string fileLocation){

    var jsonObj = new JObject();

    using (StreamReader file = File.OpenText(fileLocation))
    using (JsonTextReader reader = new JsonTextReader(file)){
        jsonObj = (JObject)JToken.ReadFrom(reader);
    }
    return jsonObj;
}

Send the API request

  1. In the main method of your application, load your JSON data with the function created above.

  2. Call the recognizeInk() function created above. Use System.Console.ReadKey() to keep the console window open after running the application.

    static void Main(string[] args){
    
        var requestData = LoadJson(dataPath);
        string requestString = requestData.ToString(Newtonsoft.Json.Formatting.None);
        recognizeInk(requestString);
        System.Console.WriteLine("\nPress any key to exit ");
        System.Console.ReadKey();
        }
    

Run the application and view the response

Run the application. A successful response is returned in JSON format. You can also find the JSON response on GitHub.

Next steps

To see how the Ink Recognition API works in a digital inking app, take a look at the following sample applications on GitHub: