IAoInitialize Interface

Provides access to members that initialize licensing for ArcGIS Desktop, Engine, and Server.

Description

The IAoInitialize Interface is the starting point for developers to initialize each application with a suitable license(s) in order for it to run successfully on any machine it is deployed on to. License configuration must be undertaken at application start time, before any ArcObjects are accessed. Failure to do so will result in application errors.

Members

	Name	Description
	CheckInExtension	Check in an extension.
	CheckOutExtension	Check out an extension.
	Initialize	This must be called before any other ArcObjects are created to initialize product Code. If called a second time during the life time of an executable with a new product code, it will return esriLicenseAlreadyInitialized.
	InitializedProduct	Retrieve's the product code at which the application has been initialized.
	IsExtensionCheckedOut	Is the Extension checked out.
	IsExtensionCodeAvailable	Check if the Product Code is available and then the Extension Code for that product.
	IsProductCodeAvailable	Check if the Product Code is available.
	Shutdown	Shutdown method. This should be the last call to ArcObjects in an application.

IAoInitialize.CheckInExtension Method

Check in an extension.

Public Function CheckInExtension ( _
    ByVal extensionCode As esriLicenseExtensionCode _
) As esriLicenseStatus

public esriLicenseStatus CheckInExtension (
    esriLicenseExtensionCode extensionCode
);

Description

Checks in the specified extension license once it has been checked out with the CheckOutExtension method.

The way that the extensions are checked in and out will depend on the type of product license passed to the Initialize method.

• 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. As such any extensions 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, the extensions should 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 extension functionality is not necessary for the application to function, the extensions can either be checked out directly after the application is initialized or checked out as and when the extension functionality is required. When the extension is checked in the functionality should be disabled. Use the IsExtensionCheckedOut method determines whether the extension is already checked out.

IAoInitialize.CheckOutExtension Method

Check out an extension.

Public Function CheckOutExtension ( _
    ByVal extensionCode As esriLicenseExtensionCode _
) As esriLicenseStatus

public esriLicenseStatus CheckOutExtension (
    esriLicenseExtensionCode extensionCode
);

Description

Checks out the specified extension license. Extensions can either be checked out as and when an application requires the extension functionality, and checked in once the application has finished with the functionality; or the extension can be checked out directly after the application is initialized and checked back in before Shutdown. Use the CheckInExtension method to check extensions back in. The way that the extensions are checked in and out will depend on the type of product license passed to the Initialize method.

• 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. As such, any extensions 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, the extensions should 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 extension functionality is not necessary for the application to function, the extensions can either be checked out directly after the application is initialized or checked out as and when the extension functionality is required. When the extension is checked in, the functionality should be disabled. Use the IsExtensionCheckedOut method to determine whether the extension is already checked out.

Using the CheckOutExtension method to check out an extension in an ArcGIS for Desktop application will not enable the user interface objects in the extension. Use the IExtension object to access the extension functionality and limit the use of the AoInitialize object to testing the availability of extension licenses and determining the extensions already checked out.

Remarks

If an application using extension functionality is initialized with an Engine single use license (ArcGIS Engine or ArcGIS Engine with Enterprise GeoDatabase) the extension license may automatically get checked out. This is because Engine single use licenses are not reference counted. It is highly recommended that extension licenses are always explicitly checked out using the CheckOutExtension method to support deployment of the application in both an environment that uses an Engine single use license and an environment that uses a license server (desktop single use or desktop concurrent licenses).

The CheckOutExtension method will fail to check out the specified extension license if:

• the extension is not licensed.
• the license is unavailable because it is already being used. An extension may fail to check out because it may have been checked out by another application since the IsExtensionCodeAvailable method checked its availability. (Desktop Concurrent licenses only).
• an unexpected license failure occurs due to system administration problems.
• the license is already checked out. Use the IsExtensionCheckedOut method to determine this.

IAoInitialize.Initialize Method

This must be called before any other ArcObjects are created to initialize product Code. If called a second time during the life time of an executable with a new product code, it will return esriLicenseAlreadyInitialized.

Public Function Initialize ( _
    ByVal ProductCode As esriLicenseProductCode _
) As esriLicenseStatus

public esriLicenseStatus Initialize (
    esriLicenseProductCode ProductCode
);

Description

Initializes the appliction with the specified product license. The product license 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 applications life, as it is not possible to re-initialize the applicaiton.

Before initializing the application use the IsProductCodeAvailable and IsExtensionCodeAvailable methods to ensure the appropriate license(s) is available to Initialize the application with. If all the licenses you require are available using Engine Single Use then we recommend you use it in preference to the Desktop Concurrent and Desktop Single Use licenses. This means you will not limit the Desktop Concurrent licenses available to any other users.

Remarks

The Initialize method will fail to check out the specified product license if:

• the license is unavailable because it is already being used (Desktop Concurrent licenses only).
• an unexpected license failure occurs due to system administration problems.
• the license is already initialized. An application is initialized with a product license for the duration of it life. Use the InitializedProduct method to determine what license an application is initialized with.

Note that loading data into the MapControl or PageLayoutControl through the property pages will automatically initialize the application with a product license. To ensure that the application is initialized with the product license specified by the Initialize method load data into the MapControl and PageLayoutControl programmatically after license initialization.

IAoInitialize.InitializedProduct Method

Retrieve's the product code at which the application has been initialized.

Public Function InitializedProduct ( _
) As esriLicenseProductCode

public esriLicenseProductCode InitializedProduct (
);

Description

The InitializedProduct method returns the product license that was passed to the Initialize method.

Checking what product license an application has been initialized with is useful for setting the enabled state of an applications functionality. For example, if an application containing some enterprise geodatabase editing has been initialized with an Engine Single Use with geodatabase editing or an ArcGIS for Desktop Standard or an ArcGIS for Desktop Advanced license, the editing functionality can be enabled. If, however, the application has been initialized with an Engine Single Use or ArcGIS for Desktop Basic license, the editing functionality must be disabled

IAoInitialize.IsExtensionCheckedOut Method

Is the Extension checked out.

Public Function IsExtensionCheckedOut ( _
    ByVal extensionCode As esriLicenseExtensionCode _
) As Boolean

public bool IsExtensionCheckedOut (
    esriLicenseExtensionCode extensionCode
);

Description

Indicates whether the specified extension license is currently checked out. Extension licensess are checked out and in using CheckOutExtension and CheckInExtension methods.

IAoInitialize.IsExtensionCodeAvailable Method

Check if the Product Code is available and then the Extension Code for that product.

Public Function IsExtensionCodeAvailable ( _
    ByVal ProductCode As esriLicenseProductCode, _
    ByVal extensionCode As esriLicenseExtensionCode _
) As esriLicenseStatus

public esriLicenseStatus IsExtensionCodeAvailable (
    esriLicenseProductCode ProductCode,
    esriLicenseExtensionCode extensionCode
);

Description

The IsExtensionCodeAvailable method returns whether the specified extension license is available with the specified product license that will be used to Initialize the application (not every extension license is available with every product license). The method firstly checks the availability of the product license and secondly checks the availability of the extension license with the product license.

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

• If an application is initialized with a Desktop Concurrent license, the application will subsequently only be able to access that Desktop Concurrent license server and its extension licenses.
• If an application is initialized with a Desktop Single Use license, the application will subsequently only be able to access that single use license server and its extension licenses.
• If an application is initialized with the Engine Single Use license on your machine, the application will subsequently only be able to access the Engine Single Use extension licenses.

If the licenses you require are available using Engine Single Use then we recommend you use it in preference to the Desktop Concurrent and Desktop Single Use licenses. This means you will not limit the Desktop Concurrent licenses available to any other users.

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. If the extension functionality is not necessary for the application to function, and the extension license is unavailable, the application should disable to the user the functionality dependant upon the extension.

IAoInitialize.IsProductCodeAvailable Method

Check if the Product Code is available.

Public Function IsProductCodeAvailable ( _
    ByVal ProductCode As esriLicenseProductCode _
) As esriLicenseStatus

public esriLicenseStatus IsProductCodeAvailable (
    esriLicenseProductCode ProductCode
);

Description

The IsProductCodeAvailable method returns whether the specified license is available. If the license is available it can be used to Initialize the application.

If the product you require is not available you may want to check whether a higher product license is available to Initialize the application with. If the license you require is available using Engine Single Use then we recommend you use it in preference to the Desktop Concurrent and Desktop Single Use licenses. This means you will not limit the Desktop Concurrent licenses available to any other users. If there are no appropriate product licenses available the application should inform the user of the issue, and either allow the user to resolve the issue or exit the application.

IAoInitialize.Shutdown Method

Shutdown method. This should be the last call to ArcObjects in an application.

Public Sub Shutdown ( _
)

public void Shutdown (
);

Description

Before an application is shut down the AOInitialize object must be shut down. This ensures that any ESRI libraries that have been used are unloaded in the correct order. Failure to do this may result in random crashes on exit due to the operating system unloading the libraries in the incorrect order.

Classes that implement IAoInitialize

Classes	Description
AoInitialize	Class initializes ArcObject components runtime environment. This class must be the first ArcObject created.