FRAMES | NO FRAMES
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.

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 signature of many methods of the BAServerHelper class is shorter that the signature of corresponding methods of the DefaultMap_BAServer class:

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