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

  • Article

Note

The Ink Recognizer API has ended its preview on August 26th, 2020. If you have existing Ink Recognizer resources, you can continue using them until the service is fully retired on January 31st, 2021.

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.

Create an Ink Recognizer resource

Note

Endpoints for resources created after July 1, 2019 use the custom subdomain format shown below. For more information and a complete list of regional endpoints, see Custom subdomain names for Cognitive Services.

Azure Cognitive Services are represented by Azure resources that you subscribe to. Create a resource for Ink Recognizer using the Azure portal.

After creating a resource, get your endpoint and key by opening your resource on the Azure portal, and clicking Quick start.

Create two environment variables:

  • INK_RECOGNITION_SUBSCRIPTION_KEY - The subscription key for authenticating your requests.

  • INK_RECOGNITION_ENDPOINT - The endpoint for your resource. It will look like this:
    https://<your-custom-subdomain>.api.cognitive.microsoft.com

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 endpoint, and the example JSON file. The endpoint will later be combined with inkRecognitionUrl to access the API.

    // Add your Ink Recognizer subscription key to your environment variables.
static readonly string subscriptionKey = Environment.GetEnvironmentVariable("INK_RECOGNIZER_SUBSCRIPTION_KEY");

// Add your Ink Recognizer endpoint to your environment variables.
// For example: <your-custom-subdomain>.cognitiveservices.azure.com
static readonly string endpoint = Environment.GetEnvironmentVariable("INK_RECOGNIZER_ENDPOINT");
static readonly string inkRecognitionUrl = "/inkrecognizer/v1.0-preview/recognize";

// Replace the dataPath string with a path to the JSON formatted ink stroke data.
// Optionally, use the example-ink-strokes.json file of this sample. Add to your bin\Debug\netcoreapp3.0 project folder.
static readonly string dataPath = @"PATH_TO_INK_STROKE_DATA";

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

REST API reference

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