API Versioning Considerations
Every ArcGIS Explorer software release presents the opportunity for ESRI to enhance the ArcGIS Explorer API. Backwards compatibility is maintained each time a new version of the API is released, this means any custom task that has been compiled against an older version of the API will run against the newest API release. However, a custom task that has been compiled against the newest version of the API, will not work when running in an older version of ArcGIS Explorer that supports an older version of the API.
| Note | |
|---|---|
| ESRI have taken the opportunity to enhance the ArcGIS Explorer API at version 1.0.0.410. | |
A custom task that has been built against the newest version of the ArcGIS Explorer API may make use of new methods and properties that are not exposed in an older version of the API; running the custom task against an older version of the API may result in application instability. To prevent this happening, when ArcGIS Explorer attempts to load a custom task, it checks the API version the custom task was compiled against. If ArcGIS Explorer detects that a custom task has been compiled against a newer version of the API, than the API that is exposed in the version of ArcGIS Explorer attempting to load the custom task, the custom task will not be loaded.
| Note | |
|---|---|
| To minimize this inconvenience for the custom task developer, changes to the ArcGIS Explorer API will not accompany every release of ArcGIS Explorer.. | |
The ideal approach to accommodating API changes is to ensure all users are running the newest version of ArcGIS Explorer. In which case all custom tasks compiled against a previous version of the ArcGIS Explorer API will continue to run successfully, and any new tasks compiled against the newest API version will also run successfully.
If a custom task is to be distributed to users running different versions of ArcGIS Explorer API, you have two options:
- If you are not using methods and properties that are exposed only in the newest version of the API, you should compile your task against an older version of the API; your custom task will run against all subsequent versions of the API.
- If you do want to distribute a custom task that makes use of methods and properties in the newest version of the API, but want to deploy your task to users using both old and new API’s, you can build two versions of your custom task. One version can use the new methods and properties and be compiled against the newest API; the second version of the task can use methods and properties exposed in an older version of the API. You can specify which version of your custom task ArcGIS Explorer should load by using the Assembly element in an NMF file. Distribute an NMF pointing to the newer version of your custom task to users using the latest version of ArcGIS Explorer, and an NMF pointing to an older version of your custom task to users using an older version of ArcGIS Explorer.
If you are having problems with deploying and downloading tasks, refer to the Deployment Troubleshooting topic.