Scenario C - Minimum license is ArcGIS Engine with 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.
After you have determined the licensing options your application requires, and which ones it is able to run against, make sure that your application initializes those licenses correctly. This section describes the license initialization process, shows how a multiple license initialization works, and provides a number of sample initialization processes.
A license server is the machine providing the license.
- Extension licenses can be checked out for the life of the application, or they can be checked out and checked in when required by the application.
- Always attempt to consume the lowest level license.
Each stand-alone 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, and before any ArcObjects components are accessed. Failure to initialize, results in application errors.
Although every stand-alone application must be initialized, the following shows situations that do not qualify as stand-alone and therefore, do not need to be initialized as described:
- The application is a dynamic-link library (DLL) that will be incorporated into an application that performs the license configuration.
- The application is an extension to ArcMap or another third-party application. The extension is responsible for license management.
Explicit component license initialization is not required when working in the Visual Basic for Applications (VBA) environment in ArcGIS Desktop (ArcMap, ArcCatalog, ArcGlobe, ArcScene), as this is performed automatically when the application starts.
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 license types are made available in the following license combinations:
- Engine Concurrent Use - Flexible License Manager (FLEXlm) technology is used to provide concurrent access to ArcGIS Engine for Windows and its extensions. The licenses can be available to multiple machines, and are stored on a license manager and checked out when being used.
- Engine Single Use - Provides access to ArcGIS Engine and its extension licenses. Each Single Use license is only available to the machine on which it is installed.
- Desktop Concurrent Use - FLEXlm technology is used to provide concurrent access to the ArcGIS Desktop products (Basic, Standard, and Advanced) and extensions. The licenses can be available to multiple machines and are stored on a license manager and checked out when being used.
- Desktop Single Use - Provides access to Single Use ArcGIS Desktop Basic, Standard, and Advanced licenses. As with Engine Single Use licenses, each one is available only to the machine on which it is installed. Even though this is significantly different from the Desktop Concurrent Use licensing, it utilizes the same technology. This means that there is no mechanism for you as an ArcGIS Engine developer to differentiate between a Single Use and a Desktop Concurrent Use license; therefore, treat them the same.
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 cannot write an application that starts with a Basic license and later switches to Standard.
When initializing an application with a license, the following must be considered:
- The types of product licenses with which the application can run, for example, an enterprise geodatabase editing application does not run with an ArcGIS Engine license or an ArcGIS Desktop Basic license. However, it runs with an ArcGIS Engine license with a Geodatabase Update extension license, an ArcGIS Desktop Standard license, or an ArcGIS for Desktop Advanced license.
Using an ArcGIS Desktop Basic license with an ArcGIS Engine application gives you access to all the functionality available to a standard ArcGIS Engine license. Likewise, using an ArcGIS Desktop Standard license with an ArcGIS Engine application that performs multiuser geodatabase editing gives you access to all the functionality available to an ArcGIS Engine license with the Geodatabase Update extension.
- The types of product licenses available to the application, for example, an application that can run with an ArcGIS Engine license also runs with an ArcGIS Desktop Basic, Standard, and Advanced license. However, you might not want to consume an Advanced license with such an application.
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. Consequently, you cannot use a combination of licenses from different license servers or Engine Single Use.
- If an application is initialized with a Desktop Concurrent Use license, the application is only able to access that Desktop Concurrent Use license server and its extension licenses.
- If an application is initialized with a Desktop Single Use license, the application is only able to access that Single Use license server and its extension licenses.
- If an application is initialized with an ArcGIS Engine Concurrent Use license, the application is only able to access that ArcGIS Engine Concurrent Use license server and its extension licenses.
- If an application is initialized with an ArcGIS Engine Single Use license on your machine, the application is only able to access ArcGIS Engine Single Use extension licenses.
It is possible, before initialization has been performed, to query the license servers (Desktop Concurrent or Single Use) and Engine (Concurrent or Single Use) to see if the licenses you require are available. If all the licenses you require are available using Engine Single Use, use it instead of the Desktop Concurrent and Desktop Single Use licenses. This means you will not limit the Desktop Concurrent Use licenses available to any other users.
Complete the initialization process of an application with a license in the following order:
- Check product license availability
- Check extension license availability (if required)
- Initialize the application with the product license
- Perform extension checkouts and check-ins (as required)
- Shut down AoInitialize
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 an ArcGIS Engine for Windows, or an ArcGIS Desktop Basic, Standard, or Advanced product license. Since the GlobeControl and SceneControl extend core ArcGIS Engine functionality, they require a corresponding 3D extension license in addition to the core product license.
If an application has been designed to use extension functionality, it can 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 is ultimately initialized with, as not every extension license is available with every product license.
If the 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.
- If the extension functionality is not necessary for the application to function and the extension license is unavailable, the application should disable the functionality dependent on the extension so it's unavailable to the user.
Once it has been established that the appropriate product and extension licenses are available, initialize the application with the product license. Once initialized, it is not possible to reinitialize the application.
Extensions can be checked out when an application requires the extension functionality, 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 extensions are checked in and out depends on the type of product license with which the application was initialized.
- If the application was initialized with either of the Engine Single Use licenses, any extensions used by the application will also be Engine Single Use. Consequently, any extension can be checked out directly after the application is initialized, and checked back in before shutdown.
- If the application was initialized with a license server and the extensions are required by the application for it to run successfully, check out the extensions directly after the application is initialized, and check back in before shutdown.
- If the application was initialized with a license server and the extension functionality is not necessary for the application to function, the extensions can be checked out directly after the application is initialized, or checked out as the extension functionality is required. When the extension is checked in, the functionality should be disabled.
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.
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:
- A product is not licensed.
- A license is unavailable because it is already being used.
- There is an unexpected license failure due to system administration problems.
- The license is already initialized. An application is initialized with a product license for the duration of its life. It is possible to check the product license an application has been initialized with. For example, if an application containing some enterprise geodatabase editing has been initialized with an Engine Single Use license with a Geodatabase Update extension, an ArcGIS Desktop Standard or Advanced license, the editing functionality can be enabled. However, if the application has been initialized with an Engine Single Use or ArcGIS Desktop Basic license, the editing functionality must be disabled.
You can configure a custom application with a license in the following ways:
- Use the LicenseControl to automatically perform license initialization in graphical user interface (GUI) applications using the MapControl, PageLayoutControl, TOCControl, ToolbarControl, SymbologyControl, SceneControl, or GlobeControl. For detailed descriptions on how to use the LicenseControl, see the following:
- Use the ArcGIS Visual Studio Integration Framework license initializer. For a detailed description on how to use the License Initializer, see ArcGIS License Initializer dialog box.
- While binding to a particular runtime, if using the BindLicense method.
If greater control is required over license initialization, particularly when checking extension licenses in and out (the LicenseControl checks out extension licenses for the duration of an application's life), consider programmatically performing license initialization. To programmatically perform license initialization, use
AoInitialize, and the
IAoInitialize and
ILicenseInformation interfaces it implements. See the following illustration:
In this scenario, the application requires at minimum, an ArcGIS Engine license. In addition, it has been determined that if an ArcGIS Engine license is not available, the application can run with an ArcGIS Desktop Basic or Standard license instead. The application also requires 3D and Spatial extension functionality for it to run successfully; therefore, both extensions need to be checked out for the duration of the application run time.
In this example, even though ArcGIS Desktop Advanced also provides the required functionality, the developer has opted not to initialize with an Advanced license. It would be unnecessary to consume an Advanced license for this simple application.
In this case, the application first attempts to initialize against the ArcGIS Engine product license. If that fails, it attempts to initialize against a Basic license, and if still unsuccessful, the application finally attempts to initialize against the Standard product license. The following outlines the steps that must be taken to initialize the application with a license:
- Verify that 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.
- Determine if 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, verify that a Spatial 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.
- In this case, no other extension licenses are needed. Proceed to the next step in the initialization process.
- Check out the ArcGIS Engine product license by initializing the application. If the license checks out, proceed to the next step in the initialization process. If the license fails to check out, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.
- Check out the 3D extension for the ArcGIS Engine product license. If the license checks out, proceed with the checkout for any other needed extensions. If the license fails to check out, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.
- Check out the Spatial extension for the ArcGIS Engine product license. If the license checks out, proceed with the checkout for any other needed extensions. If the license fails to check out, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.
- In this case, no other extension licenses are needed. If the extension licenses are checked out, the application has been successfully configured with licenses.
- The final step in the initialization process is ensuring that the licenses are released when the application is shut down.
- Verify that a Basic 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.
- Determine if an ArcGIS 3D Analyst extension license is available with the Basic 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.
- Check whether an ArcGIS Spatial Analyst extension license is available with the Basic 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.
- Check out the Basic product license by initializing the application. If the license checks 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 might fail even though the availability check has been successful. This is particularly true in cases in which Desktop Concurrent Use licenses were initially available, but might have since been checked out by another application.
- Check out the ArcGIS 3D Analyst extension. If the license checks out, proceed with checkout for any other needed extensions. If the license fails to check out, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.
- 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.
- The final step in the initialization process is ensuring that the licenses are released when the application is shut down.
- Verify that a Standard 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.
- Determine if an ArcGIS 3D Analyst extension license is available with the Standard 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.
- Check whether an ArcGIS Spatial Analyst extension license is available with the Standard 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.
- Check out the Standard product license by initializing the application. If the license checks out, proceed to the next step in the initialization process. If the license fails to check out, discontinue this final attempt. The application cannot run successfully at this time.
- Check out the ArcGIS 3D Analyst extension. If the license checks out, proceed with checkout for any other needed extensions. If the license fails to check out, discontinue this final attempt. The application cannot run successfully at this time.
- 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.
- The final step in the initialization process is ensuring that the licenses are released when the application is shut down.
In this scenario, the application is an enterprise geodatabase editing application; therefore, it requires the minimum of an ArcGIS Engine with Geodatabase Update extension license. Additionally, it has been determined that if an ArcGIS Engine with Geodatabase Update extension license is not available, the application can run with an ArcGIS Desktop Standard or Advanced 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 run time. In this case, the application attempts to initialize against the ArcGIS Engine with Geodatabase Update extension product license. If that fails, it attempts to initialize against a Standard license, and if still unsuccessful, the application finally attempts to initialize against the Advanced product license. The following outlines the steps taken to initialize the application with a license:
- Verify that 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.
- Verify that 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.
- Check out the ArcGIS Engine with Geodatabase Update extension product license by initializing the application. If the license checks out, proceed to the next step in the initialization process. If the license fails to check out, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.
- Check out the Spatial extension. Since no other extension licenses are needed, if the license checks out, the application has been successfully configured with licenses. If the license fails to check out, discontinue this attempt and restart initialization with any secondary level of allowable product licensing.
- The final step in the initialization process is ensuring that the licenses are released when the application is shut down.
- Verify that a Standard 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.
- Verify that an ArcGIS Spatial Analyst extension license is available with the Standard 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.
- Check out the Standard product license by initializing the application. If the license checks out, proceed to the next step in the initialization process. If the license fails to check out, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.
The checkout of licenses might fail even though the availability check has been successful. This is particularly true in cases where Desktop Concurrent Use licenses were initially available but might have since been checked out by another application.
- Check out the ArcGIS Spatial Analyst extension. Since no other extension licenses are needed, if the license checks out, the application has been successfully configured with licenses. If the license fails to check out, discontinue this attempt and restart initialization with any tertiary level of allowable product licensing.
- The final step in the initialization process is ensuring that the licenses are released when the application is shut down.
- Verify that an Advanced 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.
- Verify that an ArcGIS Spatial Analyst extension license is available with the Advanced 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.
- Check out the Standard product license by initializing the application. If the license fails to check out, discontinue this final attempt. The application cannot run successfully at this time.
- 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 fails to check out, discontinue this final attempt. The application cannot run successfully at this time.
- The final step in the initialization process is ensuring that the licenses are released when the application is shut down.
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 ArcGIS Desktop Basic, Standard, or Advanced license instead. Similar to the previous examples, this application also includes the use of the Network extension functionality. However, in this case, the extension is not required simply to run the application. The application enables additional functionality to use the Network extension after it has started. As such, the Network extension will be checked out dynamically during the use of the application rather than at application startup.
Once again, the application attempts to initialize against the ArcGIS Engine product license. If that fails, it makes additional attempts to initialize against a Basic license, then a Standard license, and if still unsuccessful, the application attempts to initialize against the Advanced product license. The following outlines the steps taken to initialize the application with a license:
As previously indicated, 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 previously discussed:
- Verify that 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.
- Verify that a Network extension license is available with the ArcGIS Engine product license. If it is available or not, proceed to the next step in the initialization process.
- Check out the ArcGIS Engine product license by initializing the application. If the license checks out, proceed to the next step in the initialization process. If the license fails 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. For details on this process, see the Using network functionality section in this topic.
In this example, no licenses beyond the ArcGIS Engine product license need to be checked out; therefore, if that license checks out, the application has been successfully configured with licenses.
- The final step in the initialization process is ensuring that the licenses are released when the application is shut down.
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:
- Verify that a Basic 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.
- Verify that an ArcGIS Network Analyst extension license is available with the Basic 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.
- Check out the Basic product license by initializing the application. If the license checks out, proceed to the next step in the initialization process. If the license fails 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 Analyst extension, this step is not performed at this time. Instead, the license is checked out during usage of network functionality. For details on this process, see the previously mentioned "Using network functionality" section in this topic.
In this example, no licenses beyond the Basic product license need to be checked out; therefore, if that license checked out, the application has been successfully configured with licenses.
- The final step in the initialization process is ensuring that the licenses are released when the application is shut down.
- Verify that a Standard 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.
- Verify that an ArcGIS Network Analyst extension license is available with the Standard 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.
- Check out the Standard product license by initializing the application. If the license checks out, proceed to the next step in the initialization process. If the license fails 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 Analyst extension, this step is not performed at this time. Instead, the license is checked out during usage of network functionality. For details on this process, see the previously mentioned "Using network functionality" section in this topic.
In this example, no licenses beyond the Standard product license need to be checked out; therefore, if that license checks out, the application has been successfully configured with licenses.
- The final step in the initialization process is ensuring that the licenses are released when the application is shut down.
- Verify that an Advanced 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.
- Verify that an ArcGIS Network Analyst extension license is available with the Advanced 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.
- Check out the Advanced product license by initializing the application. If the license checks out, proceed to the next step in the initialization process. If the license fails 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 Analyst extension, this step is not performed at this time. Instead, the license is checked out during usage of network functionality. For details on this process, see the previously mentioned "Using network functionality" section in this topic.
In this scenario, no licenses beyond the Advanced product license need to be checked out; therefore, if that license checks out, the application has been successfully configured with licenses.
- The final step in the initialization process is ensuring that the licenses are released when the application is shut down.
- Verify that 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 out the license.
- Check out the Network extension. If the license fails 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 might fail even though the availability check has been successful. This is particularly true in cases where Desktop Concurrent Use licenses were initially available but might have since been checked out by another application.
After developing a custom stand-alone application, test it with ArcGIS Engine for Windows before it is deployed to end-user machines. As part of the ArcGIS Engine Developer Kit, a redistributable version of ArcGIS Engine for Windows and the registration numbers are supplied for the runtime testing of custom applications.
See Also:
Licensing and copy protection questions and answers
Deployment overview
Using an ArcGIS Desktop license to run an ArcGIS Engine application
