English

How To: Authorize ArcGIS Engine 10.0 using ASR files

Summary

ArcGIS Engine 10.0 can be authorized using an offline license file called an ASR file. This is used to authorize ArcGIS Engine version 10.0, Service Pack 1 (SP1) through Service Pack 4 (SP4). There are several steps that must be followed to successfully license Engine 10.0 using ASR files.

Note that ASR files are precursors to ESRI Secure License Files (ESLF). ASR files have an *.asr extension, while ESLFs have an *.eslf extension. The difference between the two is that ASR files were created for ArcGIS 10.0 SP1 through SP4; ESLF files replaced ASR files at 10.0 SP5, and can be used to license Engine at version 10.1 through to the current version.

Procedure

Contents of the ASR File package supplied by ESRI Customer Service

The ASR License file package includes a set of files and folders supplied by ESRI customer service.
  • Two Word document files:
    • Authorizing ArcGIS 10 Using ASR Files.docx explains how to write the ArcObjects licensing code using the either .NET or C++ API calls
    • QFE-E-10SP1-163786.doc explains that this Quick Fix (QFE) was created to enable the authorization of ArcGIS Engine 10.0 SP1 using ASR files.
  • A folder (QFE-10SP1-163786) containing three binary files:
    • AoAuthorizer.dll
    • Esri.ArcGIS.AoAuthorizer.dll
    • aoauthorize.jar
  • The actual ASR license file; this has an .asr extension.

Authorize Engine with the ASR license file

  1. Register the two dlls above, AoAuthorizer.dll and Esri.ArcGIS.AoAuthorizer.dll. These are identical dlls, however, they both must be registered using EsriRegAsm.exe, in sequence. This can be done from the command line using the the EsriRegAsm syntax (see the ArcObjects documentation on registration from the command line in the Related Information section below), or from the folder in which they are contained; simply right-click the dlls, and click Register. The product against which the two dlls must be registered is Engine.

    The licensing source code in Visual Studio should look similar to the code snippet shown below (this can be a console application).
ESRI.ArcGIS.AoAuthorizer.IAuthorizeLicense aoAuthorizeLicense = new ESRI.ArcGIS.AoAuthorizer.AoAuthorizeLicenseClass();
bool bound = ESRI.ArcGIS.RuntimeManager.Bind(ProductCode.Engine); // Bind to the ArcGIS Engine product
string pathToASRLicenseFile = @"C:\temp\SomeASRFile.asr"; 
string password = "somePassword";
aoAuthorizeLicense.AuthorizeASRFromFile(pathToASRLicenseFile, password); // Authorize using the ASR File
//aoAuthorizeLicense.DeauthorizeASRFromFile(pathToASRLicenseFile, password); // Uncomment this to de-authorize 
string featuresAdded = aoAuthorizeLicense.FeaturesAdded;
System.Diagnostics.Debug.WriteLine("Features Added: " + featuresAdded); // check if licensing was successfully done

// Check if the Engine Product Code is available
ESRI.ArcGIS.esriSystem.IAoInitialize aoInitialize = new ESRI.ArcGIS.esriSystem.AoInitialize();
ESRI.ArcGIS.esriSystem.esriLicenseStatus esriLicense_Status = aoInitialize.IsProductCodeAvailable(esriLicenseProductCode.esriLicenseProductCodeEngine);
System.Diagnostics.Debug.WriteLine("esriLicenseStatus: " + esriLicense_Status); // either "available" or "unavailable

The above API calls are explained in the Word document: Authorizing ArcGIS 10 Using ASR Files.docx.

In the code above, it can be seen that binding to an ESRI product (ArcGIS Engine) has been done before ArcObjects code is called.

Make sure to add an assembly reference to either Esri.ArcGIS.AoAuthorizer.dll, or AoAuthorizer.dll (these are equivalent dlls), and include a using statement at the top of the class: using Esri.ArcGIS.AoAuthorizer.

Note that if the step to register the two dll files is skipped, an error occurs on the following line of code:

IAuthorizeLicense aoAuthorizeLicense = new AoAuthorizeLicenseClass();
The error message returned reads as follows:
Error:
COM Exception was unhandled:

Retrieving the COM class factory for component with CLSID {6DBE8BF8-6000-4734-B1A8-C81C69651C06} failed due to the following error: 80040154.
  1. Compile and run the code.
    The license authorization occurs on this line of code:
IAoAuthorizeLicense.AuthorizeASRFromFile(pathToASRLicenseFile, password);
Deauthorization occurs on this line of code:
IAoAuthorizeLicense.DeauthorizeASRFromFile(pathToASRLicenseFile, password);
Authorization is done for either an encrypted (password-protected) or unencrypted (without a password) file.

For an unencrypted file, simply pass in an empty string, while for the encrypted, pass in the password as a string.

Deauthorization can only be performed after a successful authorization.

Deauthorize Engine if it is no longer necessary to authorize it on a given machine. An error is returned if any of the following is true:
  • the path to the ASR authorization file is incorrect
  • the password to the encrypted ASR file is incorrect
  • you try to deauthorize an ASR file before authorizing it (perhaps by mistake during testing)
  • the ASR file has expired, or is faulty
Error:
COM Exception was unhandled.

HRESULT E_FAIL has been returned from a call to COM component.
  1. Open ArcGIS Administrator, and select the ArcGIS Engine Single Use radio button. This is not part of the authorization process, but allows verification that the license has been correctly authorized, and also displays the expiry date.

    If the Engine folder is selected, you should see that the license has correctly been authorized, and the expiry date clearly indicated. Usually the expiry date is 20 years from the date the license was issued (the default setting for OEM customers).

    If Engine is deauthorized using the ASR file, you should be able to see that the license is no longer available in ArcGIS Administrator. This is evident as the Expires date field that was previously populated with a value, such as 17-Oct-2037, is replaced by a blank space, and the Authorized field is populated with the string, No. This is also an indication that the code works correctly to authorize/deauthorize Engine 10.0 SP4 against ASR files.
Note:
ASR files work on Windows 7, 8, and 10, on both 32-bit and 64-bit platforms.
Note:
Support for ArcGIS Engine 10.0 expired on 01/01/2016 for standard customers. Support for Premium customers expires on 01/01/2018. ESRI recommends that customers move away from ASR files to the new framework, ESRI Secure License Files (ESLF), for ArcGIS Engine versions 10.1 and above.

Related Information