Licensing and deploying solutions  

Application development and license initialization

This topic is relevant for the following:
Product(s): ArcGIS Engine
Version(s): 9.2
Language(s): C#, C++, Java, VB6, VB.NET, VC++
Experience level(s): All



  1. Licensing concepts
  2. The initialization process
  3. Why does initialization fail?
  4. License configuration
  5. Example A: Minimum license is ArcGIS Engine with 3D and Spatial extensions
  6. Example B: Minimum license is ArcGIS Engine with Geodatabase Update and Spatial extensions
  7. Example C: Minimum license is ArcGIS Engine. Optional network functionality available

The licensing and deployment models for custom applications must be considered before application development begins, alongside the functional requirements of the application, because a number of end user software and license configurations are possible.

Licensing concepts

After you've determined which licensing options your application requires and which ones it will be able to run against, you must make sure that your application initializes those licenses correctly. This section describes the license initialization process, illustrates how a multiple license initialization would work, and provides a number of sample initialization processes.

Key concepts

Each standalone application developed using ArcObjects must initialize itself with a suitable ArcGIS license to ensure it runs successfully on any machine to which it is deployed. The license initialization must be performed by the application, at application start time, before any ArcObjects components are accessed. Failure to initialize will result in application errors.

While every standalone application must be initialized, the following examples illustrate situations that do not qualify as standalone and, therefore, don't need to be initialized as described:

1. The application is a DLL that will be incorporated into an application that will itself perform the license configuration.

2. The application is an extension to ArcMap or another third-party application. The extension is responsible for license management.

There are two types of licenses to consider when initializing an application: product licenses and, if an application uses any of the ArcGIS extension features, extension licenses. Each of these types of license are made available in certain license flavors: Engine Single Use; Desktop Concurrent Use; and Desktop Single Use.

Once an application has been initialized with a license, it cannot be reinitialized; an application is initialized with a license for the duration of its life. For example, you can't write an application that starts up with an ArcView license and later switches to ArcEditor.

When initializing an application with a license, the following must be considered:

When an application is initialized with a particular product license, a connection is made to a license server. All subsequent calls to check extensions in and out are made to the same license server. As such, you cannot use a combination of licenses from different license servers or Engine Single Use.

It is possible before initialization has been performed to query the license servers (Desktop Concurrent or Single Use) and Engine Single Use to see if the licenses you require are available. If all the licenses you require are available using Engine Single Use, then it is recommended you use it, instead of the Desktop Concurrent and Desktop Single Use licenses. This means you will not limit the Desktop Concurrent licenses available to any other users.


The initialization process

The initialization of an application with a license must be performed in the following order:

  1. Check whether the product license is available.

  2. Check whether extension licenses are available (if required).

  3. Initialize the application with the product license.

  4. As required, perform extension checkouts and check-ins.
  5. Shut down the application.

Applications built with any of the ArcGIS Engine Controls must also adhere to this license initialization process. MapControl, PageLayoutControl, SymbologyControl, TOCControl, and ToolbarControl applications require the ArcGIS Engine Runtime, ArcView, ArcEditor, or ArcInfo product licenses. Since the GlobeControl and SceneControl extend core ArcGIS Engine functionality, they require a corresponding 3D extension license in addition to the core product license.

Step 1: Check product license availability

The product license that is chosen determines the functionality the application will be able to access. Once the product license has been initialized, it cannot be changed for the duration of the application's life.

Step 2: Check extension license availability

If an application has been designed to use extension functionality, it may check for the availability of extension licenses before the application is initialized. Checking the availability of an extension license must be done in conjunction with the product license that the application will ultimately be initialized with, as not every extension license is available with every product license.

If an extension required by the application for it to run successfully is not available, the application should inform the user of the issue and exit the application.

Step 3: Initialize the application

Once it has been established that the appropriate product and extension licenses are available, the application should be initialized with the product license. Once initialized it is not possible to reinitialize the application.

Step 4: Check extensions in and out

Extensions can either be checked out when an application requires the extension functionality and checked in once the application has finished with the functionality or checked out directly after the application is initialized and checked back in before shutdown. The way that the extensions are checked in and out will depend on the type of product license with which the application was initialized.

Step 5: Shutdown

Before an application is shut down, the AoInitialize object used to perform license initialization must be shut down. This ensures that any ESRI libraries that have been used are unloaded.


Why does initialization fail?

If a product or extension fails to check out, the license status indicates the reason for the failure. Licenses can fail to check out for the following reasons:


License configuration

There are several ways to configure a custom application with a license:


Example A: Minimum license is ArcGIS Engine with 3D and Spatial extensions

In this example, the application requires at minimum an ArcGIS Engine license. In addition, this developer has decided that if an ArcGIS Engine license is not available, the application could run with an ArcView or ArcEditor license instead. The application also requires 3D and Spatial extension functionality for it to run successfully, so both of these extensions need to be checked out for the duration of the application.

In this example, even though ArcInfo would also provide the functionality required, the developer has opted not to initialize with an ArcInfo license. It would be unnecessary to consume an ArcInfo license for this simple application.

In this case, the application will first attempt to initialize against the ArcGIS Engine product license. If that fails, it will attempt to initialize against an ArcView license, and if still unsuccessful, the application will finally attempt to initialize against the ArcEditor product license. The following sections outline the steps that must be taken to initialize the application with a license.

Attempting initialization with the ArcGIS Engine product license

As noted above, to run successfully the application requires at minimum an ArcGIS Engine product license along with the corresponding 3D and Spatial extension licenses. The application's first attempt at initialization should be against this minimal level of product licensing. The application's attempts at initialization follow the process discussed earlier.

  1. Check whether an ArcGIS Engine product license is available.

    If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.

  2. Determine whether a 3D extension license is available for the ArcGIS Engine product license.

    If yes, proceed with checks for any other needed extensions. If not, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.

    Since Spatial extension functionality is also required for this application, check whether a Spatial extension license is available for the ArcGIS Engine product license.

  3. If yes, proceed with checks for any other needed extensions. If not, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.

  4. In this case, no other extension licenses are needed. Proceed to the next step in the initialization process.

  5. Check out the ArcGIS Engine product license by initializing the application.

    If the license checked out, proceed to the next step in the initialization process. If the license failed to check out, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.

  6. Check out the 3D extension for the ArcGIS Engine product license. If the license checked out, proceed with checkout for any other needed extensions. If the license failed to check out, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.

  7. Check out the Spatial extension for the ArcGIS Engine product license. If the license checked out, proceed with checkout for any other needed extensions.

    If the license failed to check out, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.

  8. In this case, no other extension licenses are needed. If the extension licenses are checked out, the application has been successfully configured with licenses.

  9. The final step in the initialization process is ensuring that the licenses are released when the application is shut down.

Attempting initialization with the ArcView product license

In this example, a secondary level of licensing is available if the first ArcGIS Engine product level fails to initialize correctly. The application once again attempts to initialize by following the defined process.

  1. Check whether an ArcView product license is available. If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.

  2. Determine whether a 3D Analyst extension license is available with the ArcView product license. If yes, proceed with checks for any other needed extensions. If not, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.>

  3. Check whether an ArcGIS Spatial Analyst extension license is available with the ArcView product license. If yes, since no other extensions are needed, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.

  4. Check out the ArcView product license by initializing the application. If the license checked out, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.

    The checkout of licenses may fail even though the availability check was successful. This is particularly possible in cases in which Desktop Concurrent licenses were initially available but may have since been checked out by another application.

  5. Check out the 3D Analyst extension. If the license checked out, proceed with checkout for any other needed extensions. If the license failed to check out, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.

  6. Check out the ArcGIS Spatial Analyst extension. Since no other extension licenses are needed, if the licenses are checked out, the application has been successfully configured with licenses. If not, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.

  7. The final step in the initialization process is ensuring that the licenses are released when the application is shut down.

Attempting initialization with the ArcEditor product license

In this example, if both the first (ArcGIS Engine) and second (ArcView) product levels fail to initialize correctly, a third level of licensingArcEditoris available. The application makes a final attempt to initialize by following the defined process.

  1. Check whether an ArcEditor product license is available. If yes, proceed to the next step in the initialization process. If not, discontinue this final attempt. The application cannot run successfully at this time.
  2. Determine whether a 3D Analyst extension license is available with the ArcEditor product license. If yes, proceed with checks for any other needed extensions. If not, discontinue this final attempt. The application cannot run successfully at this time.

  3. Check whether an ArcGIS Spatial Analyst extension license is available with the ArcEditor product license. If yes, since no other extensions are needed, proceed to the next step in the initialization process. If not, discontinue this final attempt. The application cannot run successfully at this time.
  4. Check out the ArcEditor product license by initializing the application. If the license checked out, proceed to the next step in the initialization process. If the license failed to check out, discontinue this final attempt. The application cannot run successfully at this time.

  5. Check out the 3D Analyst extension. If the license checked out, proceed with checkout for any other needed extensions. If the license failed to check out, discontinue this final attempt. The application cannot run successfully at this time.

  6. Check out the ArcGIS Spatial Analyst extension. Since no other extension licenses are needed, if the licenses are checked out, the application has been successfully configured with licenses. If not, discontinue this final attempt. The application cannot run successfully at this time.

  7. The final step in the initialization process is ensuring that the licenses are released when the application is shut down.


Example B: Minimum license is ArcGIS Engine with Geodatabase Update and Spatial Extensions

In the next example, the application is an enterprise geodatabase editing application and, therefore, requires the minimum of an ArcGIS Engine with Geodatabase Update extension license. Additionally, this developer has decided that if an ArcGIS Engine with Geodatabase Update extension license is not available, the application could run with an ArcEditor or ArcInfo license instead. The application also requires Spatial extension functionality for it to run successfully, so the extension needs to be checked out for the duration of the application. In this case, the application will first attempt to initialize against the ArcGIS Engine with Geodatabase Update extension product license. If that fails, it will attempt to initialize against an ArcEditor license, and if still unsuccessful, the application will finally attempt to initialize against the ArcInfo product license. The following sections outline the steps taken to initialize the application with a license.

Attempting initialization with the ArcGIS Engine with Geodatabase Update product license

As noted above, to run successfully the application requires at minimum an ArcGIS Engine with Geodatabase Update extension product license along with the corresponding Spatial extension license. The application's first attempt at initialization should be against this minimal level of product licensing.

The application's attempts at initialization follow the process discussed earlier:

  1. Check whether an ArcGIS Engine with Geodatabase Update extension product license is available. If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.

  2. Check whether a Spatial extension license is available with the ArcGIS Engine with Geodatabase Update extension product license. If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.

  3. Check out the ArcGIS Engine with Geodatabase Update extension product license by initializing the application. If the license checked out, proceed to the next step in the initialization process. If the license failed to check out, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.

  4. Check out the Spatial extension. Since no other extension licenses are needed, if the license checked out, the application has been successfully configured with licenses. If the license failed to check out, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.

  5. The final step in the initialization process is ensuring that the licenses are released when the application is shut down.

Attempting initialization with the ArcEditor product license

In this example, a secondary level of licensing is available if the first ArcGIS Engine product level fails to initialize correctly. The application once again attempts to initialize by following the defined process.

  1. Check whether an ArcEditor product license is available. If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.

  2. Check whether an ArcGIS Spatial Analyst extension license is available with the ArcEditor product license. If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.

  3. Check out the ArcEditor product license by initializing the application. If the license checked out, proceed to the next step in the initialization process. If the license failed to check out, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.

    The checkout of licenses may fail even though the availability check was successful. This is particularly possible in cases where Desktop Concurrent licenses were initially available but may have since been checked out by another application.

  4. Check out the ArcGIS Spatial Analyst extension. Since no other extension licenses are needed, if the license checked out, the application has been successfully configured with licenses. If the license failed to check out, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.

  5. The final step in the initialization process is ensuring that the licenses are released when the application is shut down.

Attempting initialization with the ArcInfo product license

In this example, if both the first (ArcGIS Engine) and second (ArcEditor) product levels fail to initialize correctly, a third level of licensing is available, ArcInfo. The application makes a final attempt to initialize by following the defined process.

  1. Check whether an ArcInfo product license is available. If yes, proceed to the next step in the initialization process. If not, discontinue this final attempt. The application cannot run successfully at this time.

  2. Check whether an ArcGIS Spatial Analyst extension license is available with the ArcInfo product license. If yes, proceed to the next step in the initialization process. If not, discontinue this final attempt. The application cannot run successfully at this time.

  3. Check out the ArcInfo product license by initializing the application. If the license failed to check out, discontinue this final attempt. The application cannot run successfully at this time.

  4. Check out the ArcGIS Spatial Analyst extension. Since no other extension licenses are needed, if the licenses are checked out, the application has been successfully configured with licenses. If the license failed to check out, discontinue this final attempt. The application cannot run successfully at this time.

  5. The final step in the initialization process is ensuring that the licenses are released when the application is shut down.


Example C: Minimum license is ArcGIS Engine. Optional network functionality available

Once again the example application requires a minimum of an ArcGIS Engine license. The developer has decided that if an ArcGIS Engine license is not available, the application could run with an ArcView, ArcEditor, or ArcInfo license instead. Similar to the previous examples, this application also includes extension functionalityNetworkbut, in this case, the extension is not required simply to run the application; instead, it enables additional functionality. As such the Network extension will be checked out dynamically during the use of the application rather than at application start-up.

Once again the application will first attempt to initialize against the ArcGIS Engine product license. If that fails, it will make additional attempts to initialize against an ArcView license, an ArcEditor license, and if still unsuccessful, the application will finally attempt to initialize against the ArcInfo product license. The following sections outline the steps taken to initialize the application with a license.

Attempting initialization with the ArcGIS Engine product license

As indicated above, to run successfully the application requires at minimum an ArcGIS Engine product license. While Network functionality is available within the application, its extension license can be checked out when needed rather than for the duration of the session. The application's first attempt at initialization should be against this minimal level of product licensing. The application's attempts at initialization follow the process discussed earlier.

  1. Check whether an ArcGIS Engine product license is available. If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.
  2. Check whether a Network extension license is available with the ArcGIS Engine product license. If yes, proceed to the next step in the initialization process. If not, proceed to the next step in the initialization process.

  3. Check out the ArcGIS Engine product license by initializing the application. If the license checked out, proceed to the next step in the initialization process. If the license failed to check out, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.

    Since this application dynamically checks out the Network extension, this step is not performed at this time. Instead, the license will be checked out during usage of Network functionality. See the section 'Using Network functionality' below for details on this process.

    In this example, no licenses beyond the ArcGIS Engine product license need to be checked out, so if that license checked out, the application has been successfully configured with licenses.

  4. The final step in the initialization process is ensuring that the licenses are released when the application is shut down.

Attempting initialization with the ArcView product license

In this example, a secondary level of licensing is available if the first ArcGIS Engine product level fails to initialize correctly. The application once again attempts to initialize by following the defined process:

  1. Check whether an ArcView product license is available. If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.

  2. Check whether an ArcGIS Network extension license is available with the ArcView product license. If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.

  3. Check out the ArcView product license by initializing the application. If the license checked out, proceed to the next step in the initialization process. If the license failed to check out, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.

    Since this application dynamically checks out the ArcGIS Network extension, this step is not performed at this time. Instead, the license will be checked out during usage of Network functionality. See the section 'Using Network functionality' below for details on this process.

    In this example, no licenses beyond the ArcGIS Engine product license need to be checked out, so if that license checked out, the application has been successfully configured with licenses.

  4. The final step in the initialization process is ensuring that the licenses are released when the application is shut down.

Attempting initialization with the ArcEditor product license

In this example, if both the first (ArcGIS Engine) and second (ArcView) product levels fail to initialize correctly, a third level of licensingArcEditoris available. The application makes another attempt to initialize by following the defined process:

  1. Check whether an ArcEditor product license is available. If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any fourth level of allowable product licensing.

  2. Check whether an ArcGIS Network extension license is available with the ArcEditor product license. If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any fourth level of allowable product licensing.

  3. Check out the ArcEditor product license by initializing the application. If the license checked out, proceed to the next step in the initialization process. If the license failed to check out, discontinue this attempt and restart initialization with any fourth level of allowable product licensing.

    Since this application dynamically checks out the ArcGIS Network extension, this step is not performed at this time. Instead, the license will be checked out during usage of Network functionality. See the section `Using Network functionality' below for details on this process.

    In this example, no licenses beyond the ArcGIS Engine product license need to be checked out, so if that license checked out, the application has been successfully configured with licenses.

  4. The final step in the initialization process is ensuring that the licenses are released when the application is shut down.

Attempting initialization with the ArcInfo product license

If the first (ArcGIS Engine), second (ArcView), and third (ArcEditor) product levels fail to initialize correctly, one final level of licensingArcInfois available.

The application makes a final attempt to initialize by following the defined process.

  1. Check whether an ArcInfo product license is available. If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any fourth level of allowable product licensing.

  2. Check whether an ArcGIS Network extension license is available with the ArcInfo product license. If yes, proceed to the next step in the initialization process. If not, discontinue this attempt and restart initialization with any fourth level of allowable product licensing.

  3. Check out the ArcInfo product license by initializing the application. If the license checked out, proceed to the next step in the initialization process. If the license failed to check out, discontinue this attempt and restart initialization with any fourth level of allowable product licensing.

    Since this application dynamically checks out the ArcGIS Network extension, this step is not performed at this time. Instead, the license will be checked out during usage of Network functionality. See the section `Using Network functionality' below for details on this process.

    In this example, no licenses beyond the ArcGIS Engine product license need to be checked out, so if that license checked out, the application has been successfully configured with licenses.

  4. The final step in the initialization process is ensuring that the licenses are released when the application is shut down.

Using Network functionality

During each of the initialization attempts in this example, the checkout of the Network extension did not occur during application start-up. Instead, the checkout occurs dynamically when the Network functions are accessed within the application. This means that the Network license continues to be available to other users when not in use by this application.

As discussed earlier in the chapter, the extension license must be of the same product type as the base license. If the application initialized with an ArcGIS Engine product license, then the Network functionality cannot be initialized unless an ArcGIS Engine extension license for Network is available. When the application user attempts to perform any Network functions, the application performs the following steps to activate the needed functions:

  1. Check whether the Network extension is already checked out. If the license is checked out, the application can use the Network functionality. If the license is not checked out, check the license out.

  2. Check out the Network extension. If the license failed to check out, then the application cannot use the Network functionality. If the license is checked out, the application can use the Network extension.

    The checkout of licenses may fail even though the availability check was successful. This is particularly possible in cases where Desktop Concurrent licenses were initially available but may have since been checked out by another application.

After developing a custom standalone application, it should be tested with ArcGIS Engine Runtime before it is deployed to end user machines. Supplied as part of the ArcGIS Engine Developer Kit is a redistributable version of the ArcGIS Engine Runtime and registration numbers for the runtime testing of custom applications.