Quickstart: Text analytics client library for .NET

Get started with the Text Analytics client library for .NET. Follow these steps to install the package and try out the example code for basic tasks.

Use the Text Analytics client library for .NET to perform:

  • Sentiment analysis
  • Language detection
  • Entity recognition
  • Key phrase extraction

Reference documentation | Library source code | Package (NuGet) | Samples


The demo code in this article uses the synchronous methods of the Text Analytics .NET SDK for simplicity. However, for production scenarios, we recommend using the batched asynchronous methods in your own applications to keep them scalable and responsive. For example, calling SentimentBatchAsync() instead of Sentiment().


Setting up

Create a Text Analytics Azure resource

Get a key to authenticate your applications by Azure Cognitive Services are represented by Azure resources that you subscribe to. Create a resource for Text Analytics using the Azure portal or Azure CLI on your local machine. You can also:

After you get a key from your trial subscription or resource, create an environment variable for the key, named TEXT_ANALYTICS_SUBSCRIPTION_KEY.

Create a new C# application

Create a new .NET Core application in your preferred editor or IDE.

In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name text-analytics quickstart. This command creates a simple "Hello World" C# project with a single source file: program.cs.

dotnet new console -n text-analytics-quickstart

Change your directory to the newly created app folder. You can build the application with:

dotnet build

The build output should contain no warnings or errors.

Build succeeded.
 0 Warning(s)
 0 Error(s)

From the project directory, open the program.cs file in your preferred editor or IDE. Add the following using directives:

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Azure.CognitiveServices.Language.TextAnalytics;
using Microsoft.Azure.CognitiveServices.Language.TextAnalytics.Models;
using Microsoft.Rest;

In the application's Program class, create variables for your resource's Azure endpoint and subscription key. In a static constructor, obtain these values from the environment variables TEXT_ANALYTICS_SUBSCRIPTION_KEY and TEXT_ANALYTICS_ENDPOINT. If you created these environment variables after you began editing the application, you will need to close and reopen the editor, IDE, or shell you are using to access the variables.

private const string key_var = "TEXT_ANALYTICS_SUBSCRIPTION_KEY";
private static readonly string subscriptionKey = Environment.GetEnvironmentVariable(key_var);

private const string endpoint_var = "TEXT_ANALYTICS_ENDPOINT";
private static readonly string endpoint = Environment.GetEnvironmentVariable(endpoint_var);

static Program()
    if (null == subscriptionKey)
        throw new Exception("Please set/export the environment variable: " + key_var);
    if (null == endpoint)
        throw new Exception("Please set/export the environment variable: " + endpoint_var);

In the application's Main method, create credentials to access the Text Analytics endpoint. You will define the methods called by the Main method later.


To find your key and endpoint on the Azure portal:

  1. Navigate to your azure resource at https://portal.azure.com/.
  2. Click on Quick start, located under Resource Management.
static void Main(string[] args)
    var credentials = new ApiKeyServiceClientCredentials(subscriptionKey);
    TextAnalyticsClient client = new TextAnalyticsClient(credentials)
        Endpoint = endpoint

    Console.OutputEncoding = System.Text.Encoding.UTF8;
    // languageDetectionExample(client);
    // entityRecognitionExample(client);
    // KeyPhraseExtractionExample(client);
    Console.Write("Press any key to exit.");

Install the client library

Within the application directory, install the Text Analytics client library for .NET with the following command:

dotnet add package Microsoft.Azure.CognitiveServices.Language.TextAnalytics --version 4.0.0

If you're using the Visual Studio IDE, the client library is available as a downloadable NuGet package.

Object model

The Text Analytics client is a TextAnalyticsClient object that authenticates to Azure using your key, and provides functions to accept text as single strings or as a batch. You can send text to the API synchronously, or asynchronously. The response object will contain the analysis information for each document you send.

Code examples

Authenticate the client

Create a new ApiKeyServiceClientCredentials class to store the credentials and add them to the client's requests. Within it, create an override for ProcessHttpRequestAsync() that adds your key to the Ocp-Apim-Subscription-Key header.

class ApiKeyServiceClientCredentials : ServiceClientCredentials
    private readonly string apiKey;

    public ApiKeyServiceClientCredentials(string apiKey)
        this.apiKey = apiKey;

    public override Task ProcessHttpRequestAsync(HttpRequestMessage request, CancellationToken cancellationToken)
        if (request == null)
            throw new ArgumentNullException("request");
        request.Headers.Add("Ocp-Apim-Subscription-Key", this.apiKey);
        return base.ProcessHttpRequestAsync(request, cancellationToken);

In the main() method, instantiate the client with your key and endpoint.

var credentials = new ApiKeyServiceClientCredentials(key);
TextAnalyticsClient client = new TextAnalyticsClient(credentials)
    Endpoint = endpoint

Sentiment analysis

Create a new function called SentimentAnalysisExample() that takes the client that you created earlier, and call its Sentiment() function. The returned SentimentResult object will contain the sentiment Score if successful, and an errorMessage if not.

A score that's close to 0 indicates a negative sentiment, while a score that's closer to 1 indicates a positive sentiment.

static void SentimentAnalysisExample(TextAnalyticsClient client){
    var result = client.Sentiment("I had the best day of my life.", "en");
    Console.WriteLine($"Sentiment Score: {result.Score:0.00}");


Sentiment Score: 0.87

Language detection

Create a new function called languageDetectionExample() that takes the client that you created earlier, and call its DetectLanguage() function. The returned LanguageResult object will contain the list of detected languages in DetectedLanguages if successful, and an errorMessage if not. Print the first returned language.


In some cases it may be hard to disambiguate languages based on the input. You can use the countryHint parameter to specify a 2-letter country code. By default the API is using the "US" as the default countryHint, to remove this behavior you can reset this parameter by setting this value to empty string countryHint = "" .

static void languageDetectionExample(TextAnalyticsClient client){
    var result = client.DetectLanguage("This is a document written in English.");
    Console.WriteLine($"Language: {result.DetectedLanguages[0].Name}");


Language: English

Entity recognition

Create a new function called RecognizeEntitiesExample() that takes the client that you created earlier, and call its Entities() function. Iterate through the results. The returned EntitiesResult object will contain the list of detected entities in Entities if successful, and an errorMessage if not. For each detected entity, print its Type, Sub-Type, Wikipedia name (if they exist) as well as the locations in the original text.

static void entityRecognitionExample(TextAnalyticsClient client){

    var result = client.Entities("Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975, to develop and sell BASIC interpreters for the Altair 8800.");
    foreach (var entity in result.Entities){
        Console.WriteLine($"\tName: {entity.Name},\tType: {entity.Type ?? "N/A"},\tSub-Type: {entity.SubType ?? "N/A"}");
        foreach (var match in entity.Matches){
            Console.WriteLine($"\t\tOffset: {match.Offset},\tLength: {match.Length},\tScore: {match.EntityTypeScore:F3}");


    Name: Microsoft,        Type: Organization,     Sub-Type: N/A
        Offset: 0,      Length: 9,      Score: 1.000
    Name: Bill Gates,       Type: Person,   Sub-Type: N/A
        Offset: 25,     Length: 10,     Score: 1.000
    Name: Paul Allen,       Type: Person,   Sub-Type: N/A
        Offset: 40,     Length: 10,     Score: 0.999
    Name: April 4,  Type: Other,    Sub-Type: N/A
        Offset: 54,     Length: 7,      Score: 0.800
    Name: April 4, 1975,    Type: DateTime, Sub-Type: Date
        Offset: 54,     Length: 13,     Score: 0.800
    Name: BASIC,    Type: Other,    Sub-Type: N/A
        Offset: 89,     Length: 5,      Score: 0.800
    Name: Altair 8800,      Type: Other,    Sub-Type: N/A
        Offset: 116,    Length: 11,     Score: 0.800

Key phrase extraction

Create a new function called KeyPhraseExtractionExample() that takes the client that you created earlier and call its KeyPhrases() function. The result will contain the list of detected key phrases in KeyPhrases if successful, and an errorMessage if not. Print any detected key phrases.

static void KeyPhraseExtractionExample(TextAnalyticsClient client)
    var result = client.KeyPhrases("My cat might need to see a veterinarian.");

    // Printing key phrases
    Console.WriteLine("Key phrases:");

    foreach (string keyphrase in result.KeyPhrases)


Key phrases:

Clean up resources

If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. Deleting the resource group also deletes any other resources associated with the resource group.

Next steps