This Quick Start guide describes the steps you must complete to begin writing an application that uses the Microsoft Web N-Gram Service.
The data currently made available through the service, as part of the private Beta is as follows:
- Content types: Document Body, Document Title, Anchor Texts
- Model types: Smoothed models
- N-grams: unigram, bigram, trigram, N-gram with N=4 (for Title and Anchor Texts).
About Web Services and Applications that Use the N-Gram Service
You will use standard Web service protocols to access the Web N-Gram Service.
To start programming if you are familiar with development for Web services:
- Download the WSDL service reference for the N-Gram Service from the LookupService Service page on the Web-Ngram site.
- Obtain the user token that must be included in most of the service calls: Request a user token from Microsoft.
To learn more if you are unfamiliar with development for Web services:
- Read background information on Web Services Description Language and Web services on Wikipedia or other basic reference sources.
- Find in-depth content and resources about Web services on MSDN.
- Follow the simple steps in this guide to learn how to create a simple application that uses the N-Gram Service.
This Quick Start guide describes the basic processes for creating a simple application:
- Create a new project, using a simple command-line application as an example.
- Import the service reference for the Microsoft Web N-Gram Service.
- Modify the project configuration to store specific service arguments in the application configuration.
- Modify sample code to make a service call in an example application.
- Test a simple application.
The simple example in this guide creates program that reads a string from the command line and calls the N-Gram Service to compute the log-likelihood of the string using the tri-gram model of the document body.
Developer Tools for Web Services
We recommend that you use one of the popular development platforms for Web services, such as Microsoft Visual Studio, Eclipse, or Java 2.
In this guide, the examples assume that you will use Visual Studio and the C# language to develop applications that use the N-Gram Service. You do not have to use Visual Studio, but it can simplify your development work.
- Download Visual Studio Express at no charge from the Visual Studio Express Editions web site.
During installation, you can also choose to install SQL Express, but SQL is not required for the Web N-gram Service.
- If you are unfamiliar with Visual Studio, see Learning Visual Studio.
Create a Project for Application Development
To get started, you must first create a new project for developing an application that uses Web services. The example here shows how to create a project in Visual Studio, using a Visual Studio template to create a simple command-line application.
To create a new application project in Visual Studio:
- Run Visual Studio, click New Project, and then select Template.
- To follow the example in this guide, click Console Application.
- Type a name for the project in the Name box. You can enter any name.
In this example, "NGramTest" is the project name, as shown in Figure 1.
- Click OK.
Figure 1. Creating a new project in Visual Studio
Note: If you are using a different development tool, follow the steps in that tool for creating a new development project for an application that uses Web services.
Import the Service Reference
Visual Studio has a convenient user interface for importing and auto-generating code to access Web services. These steps show how to incorporate the service reference for the N-Gram Service in your project, which you will do for each application you create that uses the N-Gram Service.
To import the service reference for the N-Gram Service:
- From the Project menu in Visual Studio, click Add Service Reference, and then enter the following string in the Address field, as shown in Figure 2:
- Click Go to import the Web N-Gram service reference from the Microsoft site.
- "Lookup Service" should now appear under Services in the Add Service Reference dialog box.
- To define a less generic name than ServiceReference1, enter the name you want in the Namespace box.
In this example, "NGramService" is the Namespace name.
- Click OK.
Figure 2. Adding a service reference for the N-Gram Service
Note: If you are using a different development tool, follow the steps in that tool for importing the service reference from the address shown in Step 1.
Modify the Project Configuration
In Visual Studio, some Web service method arguments can be stored in the application configuration, which makes for easy development. The following steps describe how to store some specific arguments related to the N-Gram Service in your application's configuration settings. You want to do this for each application you create that uses the N-Gram Service.
To store specific Web service arguments in the application configuration:
- If the Solution Explorer pane is not visible, open it from the View menu in Visual Studio.
- Under the node for your project, double-click app.config to open the file in the editor.
Figure 3. Selecting the application configuration file in Solution Explorer
- Add the following XML snippet as a child to the <configuration> node in app.config:
- For the value attributes in the snippet, substitute the following:
- For "YOUR-GUID-FROM-MICROSOFT" substitute the token you received from Microsoft.
- Leave "urn:ngram:bing-body:jun09:3" unchanged if you want to use the trigrams for the whole Web dataset.
- Save the file.
- From the Project menu, click Add Reference.
- In the .NET pane of the Add Reference dialog box, click System.Configuration, and then click OK.
Figure 4. Add Reference dialog box
Note: The information in this section is specific to Visual Studio. If you are using another tool, consult the related documentation for any similar capabilities for simplifying development.
Create the Application Code
In this example, the steps show basic activities for modifying code in a template to create a new application that uses the N-Gram Service. The command-line application created in this example will call the N-Gram Service and look up the joint probability of the phrase expressed in the command line.
To create the code for the example application:
- Double-click the icon in the Solution Explorer to open Program.cs.
Figure 5. Opening the program file in Solution Explorer
- Modify the code as follows:
In this example, your code needs only to:
- Instantiate the service object "client" as shown in the line:
NGramService.LookupServiceClient client = new NGramTest.NGramService,LookupServiceClient();
- Make the service call GetProbability as shown in the line:
Float probability = client.GetProbability(userToken, ngramModel, phrase);
This example makes only one service call. In your applications, you might make multiple service calls after the service object is instantiated.
Note: The user interface described in this section is specific to Visual Studio. If you are using another tool, follow the steps in that tool to open your program file and modify the code in the same way as described here.
Test the Application Code
After you create your first application that uses the N-Gram Service, follow standard debugging processes to test your program. The steps here show how to test the simple example created in the previous section.
To test the example command-line program from within Visual Studio:
- From the Project menu, select NGramTest Properties, and then click the Debug tab in the left column, as shown in Figure 6.
- Enter an appropriate phrase in the Command line arguments edit box. Click OK.
Figure 6. Setting Debug Options
- Press F5.
- Or- Select Start Debugging in the Debug menu in Visual Studio. A Debug window will appear, similar to the window shown in Figure 7.
Figure 7. Debug window
- To end the application, press any key.
Important: Depending on your security settings, your firewall might block this new application from making outbound network requests. If so, modify your firewall configuration so that your application is not blocked.
Note: If you are not familiar with debugging Web applications in Visual Studio, learn more at How to Debug Web Applications and Script on MSDN.
If you are using another tool, follow the steps in that tool to debug your sample application.