How to use extensions

Summary

Extensions provide additional functionality to applications. Before using the functionality provided in an extension, the extension must be checked out, and when the tasks requiring the extension are complete, the extension should be checked in. Unlike product licenses that are checked out for the duration of the application's life, extensions can be checked in and out as their functionality is required.

Extensions in ArcGIS for Desktop customizations

If you are working on an ArcGIS for Desktop customization, programmatically enable the extension by doing the following steps:

Obtain a reference to the Extension Manager. See the following code example:

[C#]


        Type factoryType = Type.GetTypeFromProgID("esriSystem.ExtensionManager");
IExtensionManager extensionManager = (IExtensionManager)Activator.CreateInstance
    (factoryType);

[VB.NET]


        Dim factoryType As Type = Type.GetTypeFromProgID("esriSystem.ExtensionManager")
Dim extensionManager As IExtensionManager = CType(Activator.CreateInstance(factoryType), IExtensionManager)

Obtain a reference to the necessary extension. The following code example shows checking for the ArcGIS Spatial Analyst extension:

[C#]


        IUID uid = new UIDClass();
uid.Value = "esriSpatialAnalystUI.SAExtension";
IExtension extension = extensionManager.FindExtension(uid);
IExtensionConfig extensionConfig = (IExtensionConfig)extension;

[VB.NET]


        Dim uid As IUID = New UIDClass()
uid.Value = "esriSpatialAnalystUI.SAExtension"
Dim extension As IExtension = extensionManager.FindExtension(uid)
Dim extensionConfig As IExtensionConfig = CType(extension, IExtensionConfig)

Before enabling the extension, verify that it is not enabled. If the extension is already enabled through the ArcGIS for Desktop application you are customizing, do not continue with enabling the extension. See the following code example:

[C#]


        bool wasEnabled = (extensionConfig.State == esriExtensionState.esriESEnabled);

[VB.NET]


        Dim wasEnabled As Boolean = (extensionConfig.State = esriExtensionState.esriESEnabled)

If the extension is not enabled as shown in the previous step, verify the extension is available, then enable it. See the following code example:

[C#]


        if (!wasEnabled)
{
    if (!(extensionConfig.State == esriExtensionState.esriESUnavailable))
    {
        //Enable the license.
        extensionConfig.State = esriExtensionState.esriESEnabled;
    }
    else
    // Handle the case when the license is not available.
    {
        // Provide an error message or exit to avoid running unavailable functionality.
    }
}

[VB.NET]


        If Not wasEnabled Then
    If Not(extensionConfig.State = esriExtensionState.esriESUnavailable) Then
        ' Enable the license.
        extensionConfig.State = esriExtensionState.esriESEnabled
    Else ' Handle the case when the license is not available.
        ' Provide an error message or exit to avoid running unavailable functionality.
    End If
End If

Perform the tasks that require the extension's functionality.
Disable the extension. If the application already enabled it, you can skip this step to keep the application state the same before and after your customization runs. See the following code example:

[C#]


        if (!wasEnabled && !(extensionConfig.State == esriExtensionState.esriESUnavailable))
{
    extensionConfig.State = esriExtensionState.esriESDisabled;
}

[VB.NET]


        If (Not wasEnabled) AndAlso Not(extensionConfig.State = esriExtensionState.esriESUnavailable) Then
    extensionConfig.State = esriExtensionState.esriESDisabled
End If

Extensions in ArcGIS Engine controls applications

If you are working in an ArcGIS Engine controls application, most applications can use the LicenseControl to perform licensing. However, the LicenseControl checks out extensions for the life of the application. For more information, see Using the LicenseControl.

If greater control over the checking out and checking in of extensions is required, the extensions can be handled the same way they are checked out and checked in for stand-alone applications, as shown in the Extensions in stand-alone applications section.

Extensions in stand-alone applications

If you are working in a stand-alone application, programmatically check out the extension by doing the following steps:

Check if the extension is available by using the IsExtensionCodeAvailable method. The following code example checks for an available Spatial Analyst license for an ArcGIS for Desktop Basic license:

[C#]


        IAoInitialize aoInitialize = new ESRI.ArcGIS.esriSystem.AoInitializeClass();
esriLicenseStatus licenseStatus = aoInitialize.IsExtensionCodeAvailable
    (esriLicenseProductCode.esriLicenseProductCodeBasic,
    esriLicenseExtensionCode.esriLicenseExtensionCodeSpatialAnalyst);

[VB.NET]


        Dim aoInitialize As IAoInitialize = New AoInitializeClass
Dim licenseStatus As esriLicenseStatus = aoInitialize.IsExtensionCodeAvailable(esriLicenseProductCode.esriLicenseProductCodeBasic, esriLicenseExtensionCode.esriLicenseExtensionCodeSpatialAnalyst)

Check out the extension by calling CheckOutExtension. The following code example checks out the Spatial Analyst extension:

[C#]


        aoInitialize.CheckOutExtension
    (esriLicenseExtensionCode.esriLicenseExtensionCodeSpatialAnalyst);

[VB.NET]


        aoInitialize.CheckOutExtension(esriLicenseExtensionCode.esriLicenseExtensionCodeSpatialAnalyst)

Perform the tasks that require the functionality of the extension.
Check in the extension by calling CheckInExtension. The following code example checks in the Spatial Analyst extension:

[C#]


        aoInitialize.CheckInExtension
    (esriLicenseExtensionCode.esriLicenseExtensionCodeSpatialAnalyst);

[VB.NET]


        aoInitialize.CheckInExtension(esriLicenseExtensionCode.esriLicenseExtensionCodeSpatialAnalyst)

To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):

ESRI.ArcGIS.System (ESRI.ArcGIS.esriSystem)