Skip to content

Commit a7870c1

Browse files
v-albemiv-albemi
authored
Merge pull request #98442 from diberry/diberry/1209-fresh-1
[Cogsvcs] LUIS - c# sdk prediction - fresh
2 parents dd523c0 + 5f128f4 commit a7870c1

File tree

1 file changed

+115
-111
lines changed

1 file changed

+115
-111
lines changed

‎articles/cognitive-services/LUIS/sdk-csharp-quickstart-query-prediction-endpoint.md

Lines changed: 115 additions & 111 deletions
Original file line numberDiff line numberDiff line change
@@ -1,182 +1,186 @@
11
---
22
title: "Quickstart: C# SDK query prediction endpoint - LUIS"
3-
titleSuffix: Azure Cognitive Services
4-
description: This article will show you how to use the C# SDK to send a user utterance to the Azure Cognitive Services LUIS application and receive a prediction.
3+
titleSuffix: Azure Cognitive Services
4+
description: This article will show you how to use the C# SDK to send a user utterance to the Azure Cognitive Services LUIS application and receive a prediction.
55
author: diberry
66
manager: nitinme
77
ms.service: cognitive-services
88
services: cognitive-services
99
ms.subservice: language-understanding
1010
ms.topic: quickstart
11-
ms.date: 09/27/2019
11+
ms.date: 12/09/2019
1212
ms.author: diberry
1313
---
1414

15-
# Quickstart: Query V2 prediction endpoint with C# .NET SDK
15+
# Quickstart: Query V3 prediction endpoint with C# .NET SDK
1616

17-
Use the .NET SDK, found on [NuGet](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Language.LUIS.Runtime/), to send a user utterance to Language Understanding (LUIS) and receive a prediction of the user's intention.
17+
Use the .NET SDK, found on [NuGet](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Language.LUIS.Runtime/), to send a user utterance to Language Understanding (LUIS) and receive a prediction of the user's intention.
1818

19-
This quickstart sends a user utterance, such as `turn on the bedroom light`, to a public Language Understanding application, then receives the prediction and displays the top-scoring intent `HomeAutomation.TurnOn` and the entity `HomeAutomation.Room` found within the utterance.
19+
Use the Language Understanding (LUIS) prediction client library for .NET to:
2020

21-
## Prerequisites
21+
* Get prediction by slot
22+
23+
[Reference documentation](https://docs.microsoft.com/dotnet/api/overview/azure/cognitiveservices/client/languageunderstanding?view=azure-dotnet) | [Library source code](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/cognitiveservices/Language.LUIS.Runtime) | [Prediction runtime Package (NuGet)](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Language.LUIS.Runtime/) | [C# Samples](https://github.com/Azure-Samples/cognitive-services-quickstart-code/tree/master/dotnet/LanguageUnderstanding/predict-with-sdk-3x)
2224

23-
* [Visual Studio Community 2017 edition](https://visualstudio.microsoft.com/vs/community/)
24-
* C# programming language (included with VS Community 2017)
25-
* Public app ID: df67dcdb-c37d-46af-88e1-8b97951ca1c2
25+
## Prerequisites
2626

27-
> [!Note]
28-
> The complete solution is available from the [cognitive-services-language-understanding](https://github.com/Azure-Samples/cognitive-services-language-understanding/tree/master/documentation-samples/sdk-quickstarts/c%23/UsePredictionRuntime) GitHub repository.
27+
* Language Understanding (LUIS) portal account - [Create one for free](https://www.luis.ai)
28+
* The current version of [.NET Core](https://dotnet.microsoft.com/download/dotnet-core).
2929

3030
Looking for more documentation?
3131

3232
* [SDK reference documentation](https://docs.microsoft.com/dotnet/api/overview/azure/cognitiveservices/client/languageunderstanding?view=azure-dotnet)
3333

34+
## Setting up
35+
36+
### Create an environment variable
3437

35-
## Get Cognitive Services or Language Understanding key
38+
Using your key, and the name of your resource, create two environment variables for authentication:
3639

37-
In order to use the public app for home automation, you need a valid key for endpoint predictions. You can use either a Cognitive Services key (created below with the Azure CLI), which is valid for many cognitive services, or a `Language Understanding` key.
40+
* `LUIS_PREDICTION_KEY` - The resource key for authenticating your requests.
41+
* `LUIS_ENDPOINT_NAME` - The resource name associated with your key.
3842

39-
Use the following [Azure CLI command to create a Cognitive Service key](https://docs.microsoft.com/cli/azure/cognitiveservices/account?view=azure-cli-latest#az-cognitiveservices-account-create):
43+
Use the instructions for your operating system.
4044

41-
```azurecli-interactive
42-
az cognitiveservices account create \
43-
-n my-cog-serv-resource \
44-
-g my-cog-serv-resource-group \
45-
--kind CognitiveServices \
46-
--sku S0 \
47-
-l WestEurope \
48-
--yes
45+
#### [Windows](#tab/windows)
46+
47+
```console
48+
setx LUIS_PREDICTION_KEY <replace-with-your-resource-key>
49+
setx LUIS_ENDPOINT_NAME <replace-with-your-resource-name>
4950
```
5051

51-
## Create .NET Core project
52+
After you add the environment variable, restart the console window.
5253

53-
Create a .NET Core console project in Visual Studio Community 2017.
54+
#### [Linux](#tab/linux)
55+
56+
```bash
57+
export LUIS_PREDICTION_KEY=<replace-with-your-resource-key>
58+
export LUIS_ENDPOINT_NAME=<replace-with-your-resource-name>
59+
```
5460

55-
1. Open Visual Studio Community 2017.
56-
1. Create a new project, from the **Visual C#** section, choose **Console App (.NET Core)**.
57-
1. Enter the project name `QueryPrediction`, leave the remaining default values, and select **OK**.
58-
This creates a simple project with the primary code file named **Program.cs**.
61+
After you add the environment variable, run `source ~/.bashrc` from your console window to make the changes effective.
5962

60-
## Add SDK with NuGet
63+
#### [macOS](#tab/unix)
6164

62-
1. In the **Solution Explorer**, select the Project in the tree view named **QueryPrediction**, then right-click. From the menu, select **Manage NuGet Packages...**.
63-
1. Select **Browse** then enter `Microsoft.Azure.CognitiveServices.Language.LUIS.Runtime`. When the package information displays, select **Install** to install the package into the project.
64-
1. Add the following _using_ statements to the top of **Program.cs**. Do not remove the existing _using_ statement for `System`.
65+
Edit your `.bash_profile`, and add the environment variable:
6566

66-
```csharp
67-
using System.Threading;
68-
using System.Threading.Tasks;
69-
using Microsoft.Azure.CognitiveServices.Language.LUIS.Runtime;
70-
using Microsoft.Azure.CognitiveServices.Language.LUIS.Runtime.Models;
67+
```bash
68+
export LUIS_PREDICTION_KEY=<replace-with-your-resource-key>
69+
export LUIS_ENDPOINT_NAME=<replace-with-your-resource-name>
7170
```
7271

73-
## Create a new method for the prediction
72+
After you add the environment variable, run `source .bash_profile` from your console window to make the changes effective.
73+
***
7474

75-
Create a new method, `GetPrediction` to send the query to the query prediction endpoint. The method will create and configure all necessary objects then return a `Task` with the [`LuisResult`](/python/api/azure-cognitiveservices-language-luis/azure.cognitiveservices.language.luis.runtime.models.luisresult) prediction results.
75+
### Create a new C# application
7676

77-
```csharp
78-
static async Task<LuisResult> GetPrediction() {
79-
}
80-
```
77+
Create a new .NET Core application in your preferred editor or IDE.
8178

82-
## Create credentials object
79+
1. In a console window (such as cmd, PowerShell, or Bash), use the dotnet `new` command to create a new console app with the name `language-understanding-quickstart`. This command creates a simple "Hello World" C# project with a single source file: `Program.cs`.
8380

84-
Add the following code to the `GetPrediction` method to create the client credentials with your Cognitive Service key.
81+
```dotnetcli
82+
dotnet new console -n language-understanding-quickstart
83+
```
8584
86-
Replace `<REPLACE-WITH-YOUR-KEY>` with your Cognitive Service key's region. The key is in the [Azure portal](https://portal.azure.com) on the Keys page for that resource.
85+
1. Change your directory to the newly created app folder.
8786
88-
```csharp
89-
// Use Language Understanding or Cognitive Services key
90-
// to create authentication credentials
91-
var endpointPredictionkey = "<REPLACE-WITH-YOUR-KEY>";
92-
var credentials = new ApiKeyServiceClientCredentials(endpointPredictionkey);
93-
```
87+
1. You can build the application with:
88+
89+
```dotnetcli
90+
dotnet build
91+
```
92+
93+
The build output should contain no warnings or errors.
9494
95-
## Create Language Understanding client
95+
```console
96+
...
97+
Build succeeded.
98+
0 Warning(s)
99+
0 Error(s)
100+
...
101+
```
96102
97-
In the `GetPrediction` method, after the preceding code, add the following code to use the new credentials, creating a [`LUISRuntimeClient`](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.language.luis.runtime.luisruntimeclient.-ctor?view=azure-dotnet#Microsoft_Azure_CognitiveServices_Language_LUIS_Runtime_LUISRuntimeClient__ctor_Microsoft_Rest_ServiceClientCredentials_System_Net_Http_DelegatingHandler___) client object.
103+
### Install the SDK
98104
99-
Replace `<REPLACE-WITH-YOUR-KEY-REGION>` with your key's region, such as `westus`. The key region is in the [Azure portal](https://portal.azure.com) on the Overview page for that resource.
105+
Within the application directory, install the Language Understanding (LUIS) prediction runtime client library for .NET with the following command:
100106
101-
```csharp
102-
// Create Luis client and set endpoint
103-
// region of endpoint must match key's region, for example `westus`
104-
var luisClient = new LUISRuntimeClient(credentials, new System.Net.Http.DelegatingHandler[] { });
105-
luisClient.Endpoint = "https://<REPLACE-WITH-YOUR-KEY-REGION>.api.cognitive.microsoft.com";
107+
```dotnetcli
108+
dotnet add package Microsoft.Azure.CognitiveServices.Language.LUIS.Runtime --version 3.0.0
106109
```
107110

108-
## Set query parameters
111+
If you're using the Visual Studio IDE, the client library is available as a downloadable NuGet package.
109112

110-
In the `GetPrediction` method, after the preceding code, add the following code to set the query parameters.
113+
## Object model
111114

112-
```csharp
113-
// public Language Understanding Home Automation app
114-
var appId = "df67dcdb-c37d-46af-88e1-8b97951ca1c2";
115+
The Language Understanding (LUIS) prediction runtime client is a [LUISRuntimeClient](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.language.luis.runtime.luisruntimeclient?view=azure-dotnet) object that authenticates to Azure, which contains your resource key.
115116

116-
// query specific to home automation app
117-
var query = "turn on the bedroom light";
117+
Once the client is created, use this client to access functionality including:
118118

119-
// common settings for remaining parameters
120-
Double? timezoneOffset = null;
121-
var verbose = true;
122-
var staging = false;
123-
var spellCheck = false;
124-
String bingSpellCheckKey = null;
125-
var log = false;
126-
```
119+
* Prediction by [staging or product slot]((https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.language.luis.runtime.predictionoperationsextensions.getslotpredictionasync?view=azure-dotnet))
120+
* Prediction by [version](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.language.luis.runtime.predictionoperationsextensions.getversionpredictionasync?view=azure-dotnet)
127121

128-
## Query prediction endpoint
129122

130-
In the `GetPrediction` method, after the preceding code, add the following code to set the query parameters:
123+
## Code examples
131124

132-
```csharp
133-
// Create prediction client
134-
var prediction = new Prediction(luisClient);
125+
These code snippets show you how to do the following with the Language Understanding (LUIS) prediction runtime client library for .NET:
135126

136-
// get prediction
137-
return await prediction.ResolveAsync(appId, query, timezoneOffset, verbose, staging, spellCheck, bingSpellCheckKey, log, CancellationToken.None);
138-
```
127+
* [Prediction by slot](#get-prediction-from-runtime)
139128

140-
## Display prediction results
129+
## Add the dependencies
141130

142-
Change the **Main** method to call the new `GetPrediction` method and return the prediction results:
131+
From the project directory, open the *Program.cs* file in your preferred editor or IDE. Replace the existing `using` code with the following `using` directives:
143132

144-
```csharp
145-
static void Main(string[] args)
146-
{
133+
[!code-csharp[Using statements](~/cognitive-services-quickstart-code/dotnet/LanguageUnderstanding/predict-with-sdk-3x/Program.cs?name=snippet_using)]
147134

148-
var luisResult = GetPrediction().Result;
135+
## Authenticate the client
149136

150-
// Display query
151-
Console.WriteLine("Query:'{0}'", luisResult.Query);
137+
1. Create variables for the key, name and app ID:
152138

153-
// Display most common properties of query result
154-
Console.WriteLine("Top intent is '{0}' with score {1}", luisResult.TopScoringIntent.Intent,luisResult.TopScoringIntent.Score);
139+
A variables to manage your prediction key pulled from an environment variable named `LUIS_PREDICTION_KEY`. If you created the environment variable after the application is launched, the editor, IDE, or shell running it will need to be closed and reloaded to access the variable. The methods will be created later.
155140

156-
// Display all entities detected in query utterance
157-
foreach (var entity in luisResult.Entities)
158-
{
159-
Console.WriteLine("{0}:'{1}' begins at position {2} and ends at position {3}", entity.Type, entity.Entity, entity.StartIndex, entity.EndIndex);
160-
}
141+
Create a variable to hold your resource name `LUIS_ENDPOINT_NAME`.
161142

162-
Console.Write("done");
143+
Create a variable for the app ID as an environment variable named `LUIS_APP_ID`. Set the environment variable to the public IoT app:
163144

164-
}
165-
```
145+
**`df67dcdb-c37d-46af-88e1-8b97951ca1c2`**
166146

167-
## Run the project
147+
[!code-csharp[Create variables](~/cognitive-services-quickstart-code/dotnet/LanguageUnderstanding/predict-with-sdk-3x/Program.cs?name=snippet_variables)]
168148

169-
Build the project in Studio and run the project to the see the output of the query:
149+
1. Create an [ApiKeyServiceClientCredentials](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.language.luis.runtime.apikeyserviceclientcredentials?view=azure-dotnet) object with your key, and use it with your endpoint to create an [LUISRuntimeClient](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.language.luis.runtime.luisruntimeclient?view=azure-dotnet) object.
170150

171-
```console
172-
Query:'turn on the bedroom light'
173-
Top intent is 'HomeAutomation.TurnOn' with score 0.809439957
174-
HomeAutomation.Room:'bedroom' begins at position 12 and ends at position 18
151+
[!code-csharp[Create LUIS client object](~/cognitive-services-quickstart-code/dotnet/LanguageUnderstanding/predict-with-sdk-3x/Program.cs?name=snippet_create_client)]
152+
153+
## Get prediction from runtime
154+
155+
Add the following method to create the request to the prediction runtime.
156+
157+
The user utterance is part of the [PredictionRequest](https://docs.microsoft.com/dotnet/api/microsoft.azure.cognitiveservices.language.luis.runtime.models.predictionrequest?view=azure-dotnet) object.
158+
159+
The **GetSlotPredictionAsync** method needs several parameters such as the app ID, the slot name, the prediction request object to fulfill the request. The other options such as verbose, show all intents, and log are optional.
160+
161+
[!code-csharp[Create method to get prediction runtime](~/cognitive-services-quickstart-code/dotnet/LanguageUnderstanding/predict-with-sdk-3x/Program.cs?name=snippet_maintask)]
162+
163+
## Main code for the prediction
164+
165+
Use the following main method to tie the variables and methods together to get the prediction.
166+
167+
[!code-csharp[Create method to get prediction runtime](~/cognitive-services-quickstart-code/dotnet/LanguageUnderstanding/predict-with-sdk-3x/Program.cs?name=snippet_main)]
168+
169+
## Run the application
170+
171+
Run the application with the `dotnet run` command from your application directory.
172+
173+
```dotnetcli
174+
dotnet run
175175
```
176176

177+
## Clean up resources
178+
179+
When you are done with your predictions, clean up the work from this quickstart by deleting the program.cs file and its subdirectories.
180+
177181
## Next steps
178182

179-
Learn more about the [.NET SDK](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Language.LUIS.Runtime/) and the [.NET reference documentation](https://docs.microsoft.com/dotnet/api/overview/azure/cognitiveservices/client/languageunderstanding?view=azure-dotnet).
183+
Learn more about the [.NET SDK](https://www.nuget.org/packages/Microsoft.Azure.CognitiveServices.Language.LUIS.Runtime/) and the [.NET reference documentation](https://docs.microsoft.com/dotnet/api/overview/azure/cognitiveservices/client/languageunderstanding?view=azure-dotnet).
180184

181-
> [!div class="nextstepaction"]
182-
> [Tutorial: Build LUIS app to determine user intentions](luis-quickstart-intents-only.md)
185+
> [!div class="nextstepaction"]
186+
> [Tutorial: Build LUIS app to determine user intentions](luis-quickstart-intents-only.md)

0 commit comments

Comments
 (0)