Using BAServerHelper Class

Business Analyst Server SOAP samples use an optional BAServerHelper class for executing methods of the Business Analyst Server Web Services DefaultMap_BAServer endpoint. To download this class together with auxiliary files, click the link below or right click this link and choose "Save as..." in the pop-up menu.

Download BAServerHelper zip archive

This package contains the following files.

Filename	Description
BAServerHelper.chm	Microsoft HTML documentation help file for BAServerHelper class.
BAServerHelper.cs	C# helper class to the Business Analyst Server Web Services DefaultMap_BAServer endpoint.
HTTPTokenProvider.cs	C# token provider class using the HTTPS SSL connection.
HTTPTokenProviderDailog.cs HTTPTokenProviderForm.cs HTTPTokenProviderForm.Designer.cs HTTPTokenProviderForm.resx	C# token provider class using the HTTPS SSL connection and requesting user credentials in a dialog.
ITokenProvider.cs	C# token provider interface.
TokenProvider.cs	C# base token provider class.

The BAServerHelper class works with both secured and non-secured instances of the DefaultMap_BAServer endpoint. In the secured case, it provides an automatic update of the authentication token when the last one expires. It executes every method of the DefaultMap_BAServer endpoint within a try-catch block and catches the "Token Expired" exception. If this exception occurs, the BAServerHelper class requests a new token and executes the method with the new token.

The BAServerHelper class makes token management easier when used in conjunction with the Business Analyst Server SOAP methods. Token management functionality includes automatic association of a token with the Business Analyst Server Web Service URL and retrieval of a new token when the current token expires. To leverage the helper class, simply associate an authentication token provider object implementing the ITokenProvider interface with a BAServerHelper instance as demonstrated in the code snippets below.

Two implementations of the ITokenProvider interface are available in this package—HTTPTokenProvider and HTTPTokenProviderDialog.

• The HTTPTokenProvider class saves user credentials, the user name and password, in private instance members and requests the ArcGIS Token Service when the token update is necessary. Its requests a short-lived token from the ArcGIS Token Service, but you can change the HTTPTokenProvider.QueryFormat value in order to request a long-lived token.
• If you don't want to save the user credentials in private instance members, you can use the HTTPTokenProviderDialog class. When an instance of this class receives a request for a new token, it shows a dialog form and allows user to populate this form with user credentials, to select a type of token, short-lived or long-lived, and to specify a client ID and an expiration timeout for receiving a long-lived token. See Security/Authentication for more details on long-lived tokens.

Along with the automatic token management, the BAServerHelper class simplifies the work with the DefaultMap_BAServer endpoint by applying some pre-processing and post-processing actions:

• The common parameters of tasks, ActiveDatasetID and IsFullErrorMessage, are specified in the properties of this class and are automatically updated in the list of parameters before execution a method of the DefaultMap_BAServer endpoint.
• Server name in all URLs returned in the results of BAServerHelper proxy-methods is updated to the fully-addressable server name if the BAServerHelper.BAServerDomain property is specified, so people and machines outside the domain of the local Business Analyst Server instance can access these URLs.

The signature of many methods of the BAServerHelper class is shorter that the signature of corresponding methods of the DefaultMap_BAServer class:

• Deprecated parameters are removed.
• The ActiveDatasetID parameter is removed from parameters of the lookup utility methods, because it is specified in the properties of a BAServerHelper instance.
• The OutputType[] parameter is removed if a task produces only one output type. This is the usual case for reporting tasks and for the CreateStdGeographies method.
• The output array type returned by the StdGeographiesList method is changed to the IDNamePair[].

How to Install the BAServerHelper Class

1. Extract files from the bas_helper.zip archive.
2. Add all C# files from this archive to your project containing the web reference to the Business Analyst Server SOAP API Web Service proxy and value objects. See Add a reference to a Esri Business Analyst Server Web Map service for details on adding a web reference.
3. Replace the ESRI.BAServer.SOAP.BAServerProxy namespace in the using instruction of the BAServerHelper.cs file with the namespace of your web reference to the Business Analyst Server SOAP Web Service proxy and value objects.

NOTE: In Visual Studio 2008, you can add a service reference to the Business Analyst Server SOAP Web Service instead of a web reference. In this case, the DefaultMap_BAServerClient class is generated instead of DefaultMap_BAServer class. In order to use the BAServerHelper class with the service reference, rename all occurrences of the DefaultMap_BAServer class name within the BAServerHelper.cs file with the DefaultMap_BAServerClient name.

How to Use the BAServerHelper Class

Classes of this package belong to the ESRI.BAServer.SOAP namespace. To simplify work with these classes, insert the using instruction below in the header of your C# files:

C#

using ESRI.BAServer.SOAP;

Non-secured instance of the BAServerHelper class is created simply:

C#

BAServerHelper baServerHelper = new BAServerHelper();

Using a token provider

Before creating an instance of the BAServerHelper class, you need to create a token provider. The code below shows how to create an instance of the HTTPTokenProvider class.

C#

string tokenServiceUrl = "https://localhost/arcgis/tokens"; string username = "My name";     // Insert user name here string password = "My password"; // Insert password here   ITokenProvider tokenProvider =     new HTTPTokenProvider(tokenServiceUrl, username, password);

Alternatively, you can create an instance of the HTTPTokenProviderDialog class:

C#

string tokenServiceUrl = "https://localhost/arcgis/tokens";   ITokenProvider tokenProvider =     new HTTPTokenProviderDialog(tokenServiceUrl);

If you already have a non-expired token, you can assign the ITokenProvider.CurrentToken property:

C#

tokenProvider.CurrentToken = nonExpiredToken;

Now you can create an instance of the BAServerHelper class.

C#

BAServerHelper BAServerHelper = new BAServerHelper(tokenProvider);

Executing methods of the BAServerHelper class

The example below executes the GetReportTemplates method.

C#

BAServerHelper baServerHelper = new BAServerHelper(tokenProvider);   ReportTemplateInfo[] templates = baServerHelper.GetReportTemplates();

The code snippet below demonstrates how the GetReportTemplates method is implemented in the BAServerHelper class.

C#

ReportTemplateInfo[] templates; try {     templates = baServerHelper.Client.GetReportTemplates(baServerHelper.ActiveDatasetID); } catch (System.Net.WebException ex) {     if (!baServerHelper.IsTokenExpired(ex)) throw;     baServerHelper.UpdateToken();     templates = baServerHelper.Client.GetReportTemplates(baServerHelper.ActiveDatasetID); }

DefaultMap_BAServer vs BAServerHelper

In the code snippets below the DefaultMap_BAServer and BAServerHelper class are compared in the case of a secured Business Analyst Server instance. The difference in using these classes is marked with the red color.

DefaultMap_BAServer

BAServerHelper

string token; // Get token here...   string webServiceUrl; // Specify DefaultMap_BAServer Web Service URL here...   DefaultMap_BAServer baServer = new DefaultMap_BAServer(); baServer.Url = webServiceUrl + "?token=" + token;     SimpleRingsParameters parameters = new SimpleRingsParameters(); parameters.ActiveDatasetID = "USA_ESRI"; // Specify other properties of SimpleRingsParameters here...   // Specify other parameters RenderingParameters imageOptions = null; TaskOutputType[] outputOptions =     new TaskOutputType[] { TaskOutputType.GetFeatureClass }; esriFolderItem outputLayer = null; esriFolderItem outputReport = null;   // Execute the task TaskResultOutput result = baServer.SimpleRings(parameters, null, imageOptions, outputOptions, outputLayer, outputReport);

ITokenProvider tokenProvider; // Specify token provider here...   string webServiceUrl; // Specify DefaultMap_BAServer Web Service URL here...   BAServerHelper baServerHelper = new BAServerHelper(tokenProvider); baServerHelper.Url = webServiceUrl; baServerHelper.ActiveDatasetID = "USA_ESRI";   SimpleRingsParameters parameters = new SimpleRingsParameters(); // Assignment of the active dataset ID is useless here // Specify other properties of SimpleRingsParameters here...   // Specify other parameters RenderingParameters imageOptions = null; TaskOutputType[] outputOptions =     new TaskOutputType[] { TaskOutputType.GetFeatureClass }; esriFolderItem outputLayer = null; esriFolderItem outputReport = null;   // Execute the task TaskResultOutput result = baServerHelper.SimpleRings(parameters, imageOptions, outputOptions, outputLayer, outputReport);