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

Note

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().

Prerequisites

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 Main method, create variables for your resource's Azure endpoint and key. If you created the environment variable after you launched the application, you will need to close and reopen the editor, IDE, or shell running it to access the variable. You will define the methods later.

Tip

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.

Be sure to remove the /text/analytics/<version> suffix from your endpoint, if it contains one. This suffix isn't needed for use with the client libraries.

static void Main(string[] args)
{
    // replace this endpoint with the correct one for your Azure resource. 
    string endpoint = $"https://westus.api.cognitive.microsoft.com";
    //This sample assumes you have created an environment variable for your key
    string key = Environment.GetEnvironmentVariable("TEXT_ANALYTICS_SUBSCRIPTION_KEY");

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

    Console.OutputEncoding = System.Text.Encoding.UTF8;
    SentimentAnalysisExample(client);
    // languageDetectionExample(client);
    // RecognizeEntitiesExample(client);
    // KeyPhraseExtractionExample(client);
    Console.ReadLine();
}

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}");
}

Output

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.

Tip

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}");
}

Output

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.");
    Console.WriteLine("Entities:");
    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}");
        }
    }
}

Output

Entities:
    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.

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)
{
    Console.WriteLine($"\t{keyphrase}");
}

Output

Key phrases:
    cat
    veterinarian

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