When you compile your unchanged 10.2.x application code against 100.x libraries for the first time, you will see compilation errors. Conceptually, you'll need to consider 100.x as a different product from the previous versions of ArcGIS Runtime. In reality, it is the same product, but it will best serve you to think about it as a different API, at least from the beginning. The ways your workflows are achieved has been re-designed in many cases to fit better with ArcGIS and the Web GIS model as it has evolved today.
This topic outlines areas of the API that have undergone considerable changes, and provides guidance for re-factoring 10.2.x code for a 100.x app. Although this topic doesn't cover every change, it will help you get over some major migration hurdles. It will also help you decide whether functionality required for your app is available in 100.x.
Functional changes
In many cases where functionality appears to be missing from 100.x, it is available but has been implemented differently. These changes require you to change your code to use new programming patterns or classes. The following sections describe some of the functional areas of the API where these types of changes have been implemented.
Maps and scenes
The Map object has been split out from the view that displays it, to represent the model in a Model-View-Controller (MVC) architecture. This same design is also implemented for Scene objects. These important objects are at the heart of the ArcGIS Runtime and have an API that follows the ArcGIS Web GIS information model. They contain operational layers, basemaps, bookmarks, pop-ups, and other ArcGIS specific data to be leveraged in your apps. They also include APIs to instantiate maps from URLs, portal items, or default basemaps. For details on how to add views and maps to your apps.
AGS and its related classes that used to represent a web map have been removed. A web map is now represented by AGS which can have a variety of sources. This makes working with maps simple and consistent regardless of where it originates from, be it on a remote ArcGIS portal, inside a mobile map package (.mmpk file) on disk, or even it is only in memory that has been programmatically created by combining layers and a basemap.
Views
The AGS base class, subclassed by AGS and AGS, is solely responsible for display and interaction, separating concerns from the model objects (AGS and AGS) and allowing the APIs to be simplified and harmonized between the 2D and 3D worlds. The Views contain graphics overlays, as well as operations, to easily identify features and graphics without having to write any layer type specific code. There is a lot you can control with the GeoView.
You can no longer add layers directly to the mapview. Instead, layers need to be added to a map which is then set on the mapview. To display graphics, you need to add a graphics overlay to the mapview containing those graphics. These graphics are displayed on top of all other map layers.
To programmatically navigate the mapview, you need to change its viewpoint using set methods. AGS and AGS notifications have been removed. To be informed when a user pans or zooms the maps, you can register a block with the viewpoint.
To control which gestures and interactions are supported by the mapview, you can change its interaction settings.
To be notified about touch events on the mapview, you need to set a touch delegate on the mapview. This delegate must conform to the AGS protocol which is a replacement of the previous AGS protocol. The new delegate methods are similar to the old ones but there are some minor name changes. You must implement these delegate methods with the correct signatures to be sure they are invoked. Also, the touch events no longer automatically return the graphics or features that were hit-tested at the touch location. You need to manually perform the hit-testing in the touch event handler using identify or identify methods on the mapview.
AGS has been removed. As a replacement for map delegate method, you can monitor the mapview's spatialReference property to know when it is fully initialized to display its map contents. The other delegate methods are no longer relevant as the mapview does not perform automatic hit-testing of features/graphics on touch events as described above.
AGS has been removed. The mapview no longer automatically displays or dismisses the callout when a user taps on graphics or features the map. You are responsible for displaying and dismissing the callout by listening to the touch events.
Callout
The mapview no longer automatically displays or dismisses the callout when a user taps on graphics or features on the map. You are responsible for displaying and dismissing the callout by listening to the touch events and hit-testing for graphics or features using identify or identify methods on the mapview.
AGS, AGS and AGS have also been removed for the same reason.
Loadable
The
<AGSLoadable>
interface was introduced at 100.0.0. Its design and purpose is intended for those workflows that involve accessing lots of data over the wire from connected online resources. All resources that load metadata asynchronously to initialize their state (such as maps, layers, and tasks) adopt the loadable pattern. The loadable pattern makes the behavior of loading state more consistent and explicit. Loadable resources do not automatically load their state. They load lazily when loaded by your app code or loaded by other objects that depend on them. This becomes useful for cases where, for example, you need to obtain information from a map resource without having to visualize it first. You can explicitly load the map resource without first associating it to a map view. The status of a loadable resource is easy to monitor to determine whether it is loading, has loaded successfully, or has failed to load. Your app can retry loading it if the resource failed to load due to a transient or recoverable condition.
Common use cases for using
<AGSLoadable>
are explained and demonstrated through code examples in the topic Loadable pattern for asynchronous resources.
If 10.2.x versions of your apps performed editing tasks involving feature services, it's important for you to fully understand the new loadable pattern. For example, retrieving features from an
AGSArcGISFeatureTable
return
AGSArcGISFeature
object which implements the loadable pattern for increased efficiency. When getting
AGSArcGISFeature
objects for rendering and query purposes, a minimum set of required fields is returned, such as identifiers, geometry, fields used for symbolizing, and so on. You must first load the feature that you want to edit, or the edit operation will fail. For complete details and code examples of loading features in editing workflows, see the Edit features topic.
Graphics overlays and graphics
Graphics have always been used to display temporary or ad-hoc geographic data on top of a map. In 10.2.x, you added graphics to your map using an AGS. Graphics are now added to Geo (AGS or AGS) as overlays. This ensures that graphics are always displayed on top, even when map or scene layers are reordered. This also makes it convenient to switch out maps and scenes while still keeping the graphics in place.
At 100.x, there is also a simpler pattern for identifying graphics within graphics overlays. The identify method on AGS (AGS or AGS) identifies visible graphics in the specified graphics overlay, near the provided screen point.
Because Graphics Overlays display graphics on top of all other layers in a map, they cannot be interleaved with other layer like was the case with Graphics Layers. If you want to interleave your own data with the map layers, consider using a feature collection layer (AGS) instead of graphics overlays. A feature collection layer displays data in a feature collection which contains features organized into individual feature collection tables. You can create one of these feature collection tables in memory and add your feature data to it.
Sketch
Sketch Layer (AGS) has been replaced by Sketch Editor (AGS). A sketch editor needs to be set on the mapview and then started to begin creating or modifying a sketch.
The AGS notification has been replaced with AGS.
Geometry
Mutable geometries (AGS, AGS, AGS, AGS, AGS) have been replaced with geometry builders - AGS, AGS, AGS, AGS, AGS.
Tasks
Geodatabase Sync Task (AGSGDB) has been renamed to AGS. Also, the asynchronous operations to generate a new geodatabase and sync an existing geodatabase now return a job handle (AGS, and AGS) to represent the execution on the service. The job has to be explicitly started to initiate the processing on the service and it also provides the results of the execution in the completion block.
Export Tile Cache Task (AGS) also returns a job handle (AGS, and AGS) for the asynchronous operations to generate a tile cache and estimate the tile cache size. The job has to be explicitly started to initiate the processing on the service and it also provides the results of the execution in the completion block.
Geometry Service Task (AGS) has been removed. Use AGS instead.
Query Task (AGS) has been removed. Use the query...() methods on AGS instead.
Identify Task (AGS) has been removed. Use identify or identify methods on the mapview instead.
Locator (AGS) has been renamed to AGS. AGS has been removed and replaced with completion blocks on the locator task's asynchronous operations that previously required the delegates.
AGS has been removed and replaced with completion blocks on the route task's asynchronous operations that previously required the delegates.
Geoprocessor (AGS) has been renamed to AGS. The asynchronous operations to perform the geoprocessing function returns a job handle (AGS). The job has to be explicitly started to submit it to the service and it also provides the results of the execution in the completion block. The AGS has been removed and replaced with completion blocks on the job's asynchronous operations.
Find Task (AGS) has been removed. No replacement.
Route Task (AGS), is available at version 100.0, but Closest Facility Task, (AGS) and Service Area Task (AGS) are available only from version 100.1 onwards. Their API for inputs and results have changed slightly.
Feature tables
AGSServiceFeatureTable
now has a Feature that is similar to the 10.2.x Mode property (Snapshot or On). The value determines how features are requested from the service for use in the client.
- On Interaction with Caching - Features are requested and stored in the table when needed based on user interaction (panning or zooming to different extents, for example). Features are cached to reduce the number of requests for features.
- On Interaction without Caching - Features are always requested from the service. There is no caching of features, so this consumes the largest amount of network bandwidth.
- Manual Caching - Features are only requested when explicitly requested by the app. All queries are made to the local version of the data.
Offline
One of the big differences with 100.x is that the APIs for common operations such as editing, searching, geocoding, or routing are the same whether you are online or offline. You just need to specify whether your data source.
With respect to packaging maps and taking them offline, ArcGIS Pro lets you create and share offline mobile map packages. See Share a mobile map package. A Mobile Map Package (.mmpk), represented by the
AGSMobileMapPackage
class, is a set of items bundled together into a single archive file for easy transport. The items are one or more maps, their associated layers and data, and optionally networks and locators. A mobile map package also includes metadata about the package that you can glean useful information from using the new API. You don't need a Local Server to access these packages. You can also take the map offline directly using the on-demand and ahead-of-time workflows provided since 100.3.
See the
AGSMobileMapPackage
class in the API reference and the Offline maps, scenes, and data topic for a thorough description of how to create and work with Mobile Map Packages.
You can also take your connected ArcGIS based feature and tiled layers offline on demand with dedicated tasks and associated jobs, just as you were able to with previous versions. However, you might find that the class names and methods differ slightly from previous versions. The
AGSGeodatabaseSyncTask
works with ArcGIS feature services to take features offline in a mobile geodatabase (.geodatabase file) and allow them to be edited and synced. The
AGSExportTileCacheTask
extracts tiles from a tiled ArcGIS map service as a tile package (.tpk file) and allows them to be viewed offline.
The Edit features guide topic provides code examples and in-depth discussion for editing both online and offline with the new API.
Authentication
Performing authentication has been re-architected around a central authentication manager (AGS) that issues challenges (AGS) when a resource (such as a layer or a task) attempts to access a secure service. Additionally, the SDK contains an in-built challenge handler that tries to resolve the challenge by displaying UI to solicit user details, but developers can choose to customize this behavior and handle challenges themselves by providing a delegate (AGS).
AGSO has been removed. To support OAuth based authentication in your app you need to set the app's OAuth configuration (AGSO) on the authentication manager. The configuration includes, among other things, a redirectURL which must use a custom URL scheme for the app. This will allow the user to sign in using an external Safari browser which offers more security as compared to performing the authentication in app. When the user finishes logging in through Safari, the app will be invoked and passed the credentials to access the resource. You will need to use AGS to handle this app invocation and complete the OAuth authentication workflow.
Portal
The mapping API has been refactored for better integration with the portal API. This API allows you to load maps stored in a portal (web maps) into your app, make updates to web maps, and save changes back to the portal item. Also, your app can save maps created by your app as a new portal item. These web maps can then be used elsewhere within the ArcGIS system.
The ArcGIS organization portals document provides more information on the use of portal. For an example of saving and updating web maps stored in your portal, see the Create and save map sample.
The following delegates have been removed - AGS, AGS, AGS, AGS, AGS. They have been replaced with completion blocks on the corresponding asynchronous operations that required the delegates.
AGS, AGS, and AGS classes implement the loadable pattern (AGS) which means they must be loaded for their information to be available.
AGS and AGS notifications have been removed. The loadable protocol provides mechanisms to monitor the loadStatus of the portal.
Error handling
With 100.x, it's easier to determine where errors occur in the stack so you can provide better error messages to your Runtime app users. A new standardized error domain property indicates whether the error occurred client-side within the ArcGIS Runtime, or server-side from an ArcGIS Server service or web service. A consistent error code property can be used to further diagnose the error's cause or determine what error message should be displayed to the user. For a complete list of error domains and codes, see the Platform error codes topic.
Xcode project changes
The installation location of ArcGI on your machine has been slightly changed from the 10.2.5 release. It is now installed under $ (notice the additional folder Static). Be sure to update your project's Framework search paths setting and ArcGIS.bundle reference accordingly.
Also, you now need a minimum of Xcode 8 with iOS 10 SDK to build your apps with the Runtime SDK. iOS 9 and 10 are supported for app deployment.
Licensing changes
Like earlier, you have access to all the capabilities during development and testing, however the licensing model for deployment has changed to include 4 levels - Lite, Basic, Standard, and Advanced where each level unlocks a different set of capabilities. You can license your app either by using a license string or using user authentication. More details are available in the License topic.
Additional Resources
The information above provides a high level overview of the changes between version 10.2.x and 100.0, but as you embark on migrating your apps, you may find yourself needing more fine-grained, detailed information about how to change references to classes, methods or properties that have changed and no longer compile. We know that many of you borrow heavily from the SDK samples or use them as a starting point and build on it. So to ease your migration path a little and provide more detailed information, we've ported the most popular 10.2.x samples to the latest version of the SDK. You can download the diff and open it in Safari to see a simple side-by-side comparison of what code needed to be changed. The diff is searchable in Safari so you can look for specific classes, methods, or properties and quickly find the corresponding changes. We've also made the ported samples available for download in a branch on GitHub.