Merge pull request #103909 from assafi/assafi/cs_sdk_preview_2

[Cog Svcs] Update Text Analytics C# Quickstart to SDK v1.0.0-preview.2

Author: tiburd

articles/cognitive-services/text-analytics/includes/quickstarts/csharp-sdk.md

@@ -38,7 +38,7 @@ Using the Visual Studio IDE, create a new .NET Core console app. This will creat
 
 #### [Version 3.0-preview](#tab/version-3)
 
-Install the client library by right-clicking on the solution in the **Solution Explorer** and selecting **Manage NuGet Packages**. In the package manager that opens select **Browse**, check **Include prerelease**, and search for `Azure.AI.TextAnalytics`. Click on it, and then **Install**. You can also use the [Package Manager Console](https://docs.microsoft.com/nuget/consume-packages/install-use-packages-powershell#find-and-install-a-package).
+Install the client library by right-clicking on the solution in the **Solution Explorer** and selecting **Manage NuGet Packages**. In the package manager that opens select **Browse**, check **Include prerelease**, and search for `Azure.AI.TextAnalytics`. Select version `1.0.0-preview.2`, and then **Install**. You can also use the [Package Manager Console](https://docs.microsoft.com/nuget/consume-packages/install-use-packages-powershell#find-and-install-a-package).
 
 Open the *program.cs* file and add the following `using` directives:
 
@@ -52,7 +52,7 @@ In the application's `Program` class, create variables for your resource's key a
 [!INCLUDE [text-analytics-find-resource-information](../find-azure-resource-info.md)]
 
 ```csharp
-private static readonly string key = "<replace-with-your-text-analytics-key-here>";
+private static readonly TextAnalyticsApiKeyCredential credentials = new TextAnalyticsApiKeyCredential("<replace-with-your-text-analytics-key-here>");
 private static readonly Uri endpoint = new Uri("<replace-with-your-text-analytics-endpoint-here>");
 ```
 
@@ -61,7 +61,7 @@ Replace the application's `Main` method. You will define the methods called here
 ```csharp
 static void Main(string[] args)
 {
-    var client = new TextAnalyticsClient(endpoint, key);
+    var client = new TextAnalyticsClient(endpoint, credentials);
     // You will implement these methods later in the quickstart.
     SentimentAnalysisExample(client);
     LanguageDetectionExample(client);
@@ -109,17 +109,18 @@ If you're using version `3.0-preview`, you can use an optional `TextAnalyticsCli
 * [Sentiment analysis](#sentiment-analysis)
 * [Language detection](#language-detection)
 * [Named Entity Recognition](#named-entity-recognition-ner)
+* [Detect personal information](#detect-personal-information)
 * [Entity linking](#entity-linking)
 * [Key phrase extraction](#key-phrase-extraction)
 
 ## Authenticate the client
 
 #### [Version 3.0-preview](#tab/version-3)
 
-Make sure your main method from earlier creates a new client object with your endpoint and key. 
+Make sure your main method from earlier creates a new client object with your endpoint and credentials.
 
 ```csharp
-var client = new TextAnalyticsClient(endpoint, key);
+var client = new TextAnalyticsClient(endpoint, credentials);
 ```
 
 #### [Version 2.1](#tab/version-2)
@@ -138,20 +139,24 @@ Create a method to instantiate the [TextAnalyticsClient](https://docs.microsoft.
 
 #### [Version 3.0-preview](#tab/version-3)
 
-Create a new function called `SentimentAnalysisExample()` that takes the client that you created earlier, and call its `AnalyzeSentiment()` function. The returned `Response<AnalyzeSentimentResult>` object will contain the sentiment label and score of the entire input document, as well as a sentiment analysis for each sentence if successful, and a `Value.ErrorMessage` if not.
+Create a new function called `SentimentAnalysisExample()` that takes the client that you created earlier, and call its `AnalyzeSentiment()` function. The returned `Response<DocumentSentiment>` object will contain the sentiment label and score of the entire input document, as well as a sentiment analysis for each sentence if successful. If there was an error, it will throw a `RequestFailedException`.
 
 ```csharp
 static void SentimentAnalysisExample(TextAnalyticsClient client)
 {
-    var response = client.AnalyzeSentiment("I had the best day of my life. I wish you were there with me.");
-    Console.WriteLine($"Document sentiment: {response.Value.DocumentSentiment.SentimentClass}\n");
-    foreach (var sentence in response.Value.SentenceSentiments)
+    string inputText = "I had the best day of my life. I wish you were there with me.";
+    DocumentSentiment documentSentiment = client.AnalyzeSentiment(inputText);
+    Console.WriteLine($"Document sentiment: {documentSentiment.Sentiment}\n");
+
+    var si = new StringInfo(inputText);
+    foreach (var sentence in documentSentiment.Sentences)
     {
         Console.WriteLine($"\tSentence [offset {sentence.Offset}, length {sentence.Length}]");
-        Console.WriteLine($"\tSentence sentiment: {sentence.SentimentClass}");
-        Console.WriteLine($"\tPositive score: {sentence.PositiveScore:0.00}");
-        Console.WriteLine($"\tNegative score: {sentence.NegativeScore:0.00}");
-        Console.WriteLine($"\tNeutral score: {sentence.NeutralScore:0.00}\n");
+        Console.WriteLine($"\tText: \"{si.SubstringByTextElements(sentence.Offset, sentence.Length)}\"");
+        Console.WriteLine($"\tSentence sentiment: {sentence.Sentiment}");
+        Console.WriteLine($"\tPositive score: {sentence.SentimentScores.Positive:0.00}");
+        Console.WriteLine($"\tNegative score: {sentence.SentimentScores.Negative:0.00}");
+        Console.WriteLine($"\tNeutral score: {sentence.SentimentScores.Neutral:0.00}\n");
     }
 }
 ```
@@ -162,12 +167,14 @@ static void SentimentAnalysisExample(TextAnalyticsClient client)
 Document sentiment: Positive
 
         Sentence [offset 0, length 30]
+        Text: "I had the best day of my life."
         Sentence sentiment: Positive
         Positive score: 1.00
         Negative score: 0.00
         Neutral score: 0.00
 
         Sentence [offset 31, length 30]
+        Text: "I wish you were there with me."
         Sentence sentiment: Neutral
         Positive score: 0.21
         Negative score: 0.02
@@ -193,16 +200,15 @@ Sentiment Score: 0.87
 #### [Version 3.0-preview](#tab/version-3)
 
 
-Create a new function called `LanguageDetectionExample()` that takes the client that you created earlier, and call its  `DetectLanguage()` function. The returned `Response<DetectLanguageResult>` object will contain the detected language in `Value.PrimaryLanguage` if successful, and a `Value.ErrorMessage` if not.
+Create a new function called `LanguageDetectionExample()` that takes the client that you created earlier, and call its  `DetectLanguage()` function. The returned `Response<DetectedLanguage>` object will contain the detected language along with its name and ISO-6391 code. If there was an error, it will throw a `RequestFailedException`.
 
 > [!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 = ""`. To set a different default, set the `TextAnalyticsClientOptions.DefaultCountryHint` property and pass it during the client's initialization.
 
 ```csharp
 static void LanguageDetectionExample(TextAnalyticsClient client)
 {
-    var response = client.DetectLanguage("Ce document est rédigé en Français.");
-    var detectedLanguage = response.Value.PrimaryLanguage;
+    DetectedLanguage detectedLanguage = client.DetectLanguage("Ce document est rédigé en Français.");
     Console.WriteLine("Language:");
     Console.WriteLine($"\t{detectedLanguage.Name},\tISO-6391: {detectedLanguage.Iso6391Name}\n");
 }
@@ -217,7 +223,7 @@ Language:
 
 #### [Version 2.1](#tab/version-2)
 
-Create a new function called `languageDetectionExample()` that takes the client that you created earlier, and call its  [DetectLanguage()](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.language.textanalytics.textanalyticsclientextensions.detectlanguage?view=azure-dotnet#Microsoft_Azure_CognitiveServices_Language_TextAnalytics_TextAnalyticsClientExtensions_DetectLanguage_Microsoft_Azure_CognitiveServices_Language_TextAnalytics_ITextAnalyticsClient_System_String_System_String_System_Nullable_System_Boolean__System_Threading_CancellationToken_) function. The returned [LanguageResult](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.language.textanalytics.models.languageresult?view=azure-dotnet) object will contain the list of detected languages in `DetectedLanguages` if successful, and an `errorMessage` if not.  Print the first returned language.
+Create a new function called `languageDetectionExample()` that takes the client that you created earlier, and call its  [DetectLanguage()](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.language.textanalytics.textanalyticsclientextensions.detectlanguage?view=azure-dotnet#Microsoft_Azure_CognitiveServices_Language_TextAnalytics_TextAnalyticsClientExtensions_DetectLanguage_Microsoft_Azure_CognitiveServices_Language_TextAnalytics_ITextAnalyticsClient_System_String_System_String_System_Nullable_System_Boolean__System_Threading_CancellationToken_) function. The returned [LanguageResult](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.language.textanalytics.models.languageresult?view=azure-dotnet) 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 = ""` .
@@ -232,29 +238,27 @@ Language: English
 
 ---
 
-## Named Entity recognition (NER)
+## Named Entity Recognition (NER)
 
 #### [Version 3.0-preview](#tab/version-3)
 
 
 > [!NOTE]
-> In version `3.0-preview`:
-> * NER includes separate methods for detecting personal information. 
-> * Entity linking is a separate request than NER.
+> New in version `3.0-preview`:
+> * Entity recognition now includes the ability to detect personal information in text.
+> * Entity linking is now a separated from entity recognition.
 
-The below code is for detecting personal information using NER v3, which is in public preview.
 
-
-Create a new function called `EntityRecognitionExample()` that takes the client that you created earlier, call its `RecognizeEntities()` function and iterate through the results. The returned `Response<RecognizeEntitiesResult>` object will contain the list of detected entities in `Value.NamedEntities` if successful, and a `Value.ErrorMessage` if not. For each detected entity, print its Type and Sub-Type if exists.
+Create a new function called `EntityRecognitionExample()` that takes the client that you created earlier, call its `RecognizeEntities()` function and iterate through the results. The returned `Response<IReadOnlyCollection<CategorizedEntity>>` object will contain the list of detected entities. If there was an error, it will throw a `RequestFailedException`.
 
 ```csharp
 static void EntityRecognitionExample(TextAnalyticsClient client)
 {
     var response = client.RecognizeEntities("I had a wonderful trip to Seattle last week.");
     Console.WriteLine("Named Entities:");
-    foreach(var entity in response.Value.NamedEntities)
+    foreach(var entity in response.Value)
     {
-        Console.WriteLine($"\tText: {entity.Text},\tType: {entity.Type},\tSub-Type: {entity.SubType ?? "N/A"}");
+        Console.WriteLine($"\tText: {entity.Text},\tCategory: {entity.Category},\tSub-Category: {entity.SubCategory}");
         Console.WriteLine($"\t\tOffset: {entity.Offset},\tLength: {entity.Length},\tScore: {entity.Score:F3}\n");
     }
 }
@@ -264,25 +268,26 @@ static void EntityRecognitionExample(TextAnalyticsClient client)
 
 ```console
 Named Entities:
-        Text: Seattle,  Type: Location, Sub-Type: N/A
-                Offset: 26,     Length: 7,      Score: 0.806
+        Text: Seattle,  Category: Location,     Sub-Category: GPE
+                Offset: 26,     Length: 7,      Score: 0.920
 
-        Text: last week,        Type: DateTime, Sub-Type: N/A
+        Text: last week,        Category: DateTime,     Sub-Category: DateRange
                 Offset: 34,     Length: 9,      Score: 0.800
 ```
 
-## Using NER to detect personal information
+## Detect personal information
 
-Create a new function called `EntityPIIExample()` that takes the client that you created earlier, call its `RecognizePiiEntities()` function and iterate through the results. Similar to the previous function the returned `Response<RecognizeEntitiesResult>` object will contain the list of detected entities in `Value.NamedEntities` if successful, and a `Value.ErrorMessage` if not.
+Create a new function called `EntityPIIExample()` that takes the client that you created earlier, call its `RecognizePiiEntities()` function and iterate through the results. Similar to the previous function the returned `Response<IReadOnlyCollection<CategorizedEntity>>` object will contain the list of detected entities. If there was an error, it will throw a `RequestFailedException`.
 
 ```csharp
 static void EntityPIIExample(TextAnalyticsClient client)
 {
-    var response = client.RecognizePiiEntities("Insurance policy for SSN on file 123-12-1234 is here by approved.");
+    string inputText = "Insurance policy for SSN on file 123-12-1234 is here by approved.";
+    var response = client.RecognizePiiEntities(inputText);
     Console.WriteLine("Personally Identifiable Information Entities:");
-    foreach(var entity in response.Value.NamedEntities)
+    foreach(var entity in response.Value)
     {
-        Console.WriteLine($"\tText: {entity.Text},\tType: {entity.Type},\tSub-Type: {entity.SubType ?? "N/A"}");
+        Console.WriteLine($"\tText: {entity.Text},\tCategory: {entity.Category},\tSub-Category: {entity.SubCategory}");
         Console.WriteLine($"\t\tOffset: {entity.Offset},\tLength: {entity.Length},\tScore: {entity.Score:F3}\n");
     }
 }
@@ -292,14 +297,14 @@ static void EntityPIIExample(TextAnalyticsClient client)
 
 ```console
 Personally Identifiable Information Entities:
-        Text: 123-12-1234,      Type: U.S. Social Security Number (SSN),        Sub-Type: N/A
+        Text: 123-12-1234,      Category: U.S. Social Security Number (SSN),    Sub-Category: None
                 Offset: 33,     Length: 11,     Score: 0.850
 ```
 
 
 ## Entity linking
 
-Create a new function called `EntityLinkingExample()` that takes the client that you created earlier, call its `RecognizeLinkedEntities()` function and iterate through the results. The returned `Response<RecognizeLinkedEntitiesResult>` object will contain the list of detected entities in `Value.LinkedEntities` if successful, and a `Value.ErrorMessage` if not. Since linked entities are uniquely identified, occurrences of the same entity are grouped under a `LinkedEntity` object as a list of `LinkedEntityMatch` objects.
+Create a new function called `EntityLinkingExample()` that takes the client that you created earlier, call its `RecognizeLinkedEntities()` function and iterate through the results. The returned `Response<IReadOnlyCollection<LinkedEntity>>` represents the list of detected entities. If there was an error, it will throw a `RequestFailedException`. Since linked entities are uniquely identified, occurrences of the same entity are grouped under a `LinkedEntity` object as a list of `LinkedEntityMatch` objects.
 
 ```csharp
 static void EntityLinkingExample(TextAnalyticsClient client)
@@ -311,9 +316,9 @@ static void EntityLinkingExample(TextAnalyticsClient client)
         "chief executive officer, president and chief software architect, " +
         "while also being the largest individual shareholder until May 2014.");
     Console.WriteLine("Linked Entities:");
-    foreach (var entity in response.Value.LinkedEntities)
+    foreach (var entity in response.Value)
     {
-        Console.WriteLine($"\tName: {entity.Name},\tID: {entity.Id},\tURL: {entity.Uri}\tData Source: {entity.DataSource}");
+        Console.WriteLine($"\tName: {entity.Name},\tID: {entity.Id},\tURL: {entity.Url}\tData Source: {entity.DataSource}");
         Console.WriteLine("\tMatches:");
         foreach (var match in entity.Matches)
         {
@@ -381,7 +386,7 @@ Create a new function called `RecognizeEntitiesExample()` that takes the client
 
 #### [Version 3.0-preview](#tab/version-3)
 
-Create a new function called `KeyPhraseExtractionExample()` that takes the client that you created earlier, and call its `ExtractKeyPhrases()` function. The result will contain the list of detected key phrases in `Value.KeyPhrases` if successful, and a `Value.ErrorMessage` if not. Print any detected key phrases.
+Create a new function called `KeyPhraseExtractionExample()` that takes the client that you created earlier, and call its `ExtractKeyPhrases()` function. The returned `<Response<IReadOnlyCollection<string>>` object will contain the list of detected key phrases. If there was an error, it will throw a `RequestFailedException`.
 
 ```csharp
 static void KeyPhraseExtractionExample(TextAnalyticsClient client)
@@ -391,7 +396,7 @@ static void KeyPhraseExtractionExample(TextAnalyticsClient client)
     // Printing key phrases
     Console.WriteLine("Key phrases:");
 
-    foreach (string keyphrase in response.Value.KeyPhrases)
+    foreach (string keyphrase in response.Value)
     {
         Console.WriteLine($"\t{keyphrase}");
     }
@@ -421,4 +426,4 @@ Key phrases:
     veterinarian
 ```
 
----
+---