ArcGIS Runtime SDK for macOS

Migrate to version 100.x

When you compile your 10.2.x application code against 100.x libraries for the first time, you will get a lot of compilation errors. Conceptually, you'll need to consider 100.x as almost 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 way in which your workflows are achieved has been re-designed in many cases to fit better with the ArcGIS platform and the Web GIS model as it has evolved today.

The aim of this topic is to outline areas of the API that have undergone considerable changes and to provide guidance for re-factoring 10.2.x code for a 100.x app. Although not an exhaustive list, it will help you get past some of the major migration hurdles. It will also help you decide whether functionality required for your app is available in 100.x. In some cases, it might be better to wait for a future release of the 100.x family before migrating a particular app.

In many cases, functionality that appears to be missing from 100.1 is available but has been implemented differently. These changes generally require you to rework 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.

Functional Changes

Maps

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, see Build a new map.

AGSWebMap and its related classes that used to represent a web map have been removed. A web map is now represented by AGSMap 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 AGSGeoView base class, subclassed by AGSMapView and AGSSceneView, is solely responsible for display and interaction, separating concerns from the model objects (AGSMap and AGSScene) 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 setViewpoint...() methods. AGSMapViewDidEndZoomingNotification and AGSMapViewDidEndPanningNotification notifications have been removed. To be informed when a user pans or zooms the maps, you can register a block with the viewpointChangedHandler .

To control which gestures and interactions are supported by the mapview, you can change its interactionOptions 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 AGSGeoViewTouchDelegate protocol which is a replacement of the previousAGSMapViewTouchDelegate 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 identifyGraphicsOverlay...() or identifyLayer...() methods on the mapview.

AGSMapViewLayerDelegate has been removed. As a replacement for mapViewDidLoad() 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.

AGSMapViewCalloutDelegate 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 identifyGraphicsOverlay...() or identifyLayer...() methods on the mapview.

AGSHitTestable, AGSInfoTemplateDelegate and AGSLayerCalloutDelegate have also been removed for the same reason.

Loadable

The AGSLoadable interface was newly introduced at 100.0.0. It's design and purpose is intended for those workflows that involve accessing lots of data over the wire from connected online resources. All resources, such as maps, layers, tasks etc, that load metadata asynchronously to initialize their state adopt the loadable pattern. The loadable pattern makes the behavior of loading state more consistent and uniform, and also makes its asynchronous nature more explicit. Loadable resources do not automatically load their state. They load lazily, when asked either by the developer, or by other objects that depend on them. This becomes quite useful for those cases where you may, for example, what to obtain information from a map resource without having to visualize it first. The status of a loadable resource can be easily monitored to determine if it is loading, loaded successfully, or failed to load, and you can retry loading it if it failed to load.

Common use cases for using AGSLoadable are explained and demonstrated through code examples in the Loadable pattern topic.

If 10.2.x versions of your apps performed editing tasks involving feature services, it's important for you to understand the new loadable pattern clearly. Features from an AGSArcGISFeatureTable return AGSArcGISFeature objects which implement 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. When you want to edit the feature, you must load it first, otherwise the edit operation will fail. For complete details and code examples of loading features in editing workflows, see the Edit features guide 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 AGSGraphicsLayer. Graphics are now added to GeoViews (AGSMapView or AGSSceneView) 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.

The guide topic Add graphics overlays to your app provides code for creating graphics overlays and adding them to the map. You can see the code for adding and working with graphics in a graphics overlay in Add graphics and text to graphics overlays.

At 100.x, there is also a simpler pattern for identifying graphics within graphics overlays. The identifyGraphicsOverlay(...)completion: method on AGSGeoView (AGSMapView or AGSSceneView) 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 ( AGSFeatureCollectionLayer) 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 ( AGSSketchGraphicsLayer) has been replaced by Sketch Editor ( AGSSketchEditor). A sketch editor needs to be set on the mapview and then started to begin creating or modifying a sketch.

The AGSSketchGraphicsLayerGeometryDidChangeNotificationnotification has been replaced with AGSSketchEditorGeometryDidChangeNotification

Geometry

Mutable geometries (AGSMutablePoint, AGSMutableEnvelope, AGSMutablePolygon, AGSMutablePolyline, AGSMutableMultipoint) have been replaced with geometry builders - AGSPointBuilder, AGSEnvelopeBuilder, AGSPolygonBuilder, AGSPolylineBuilder, AGSMultipointBuilder.

Instance methods on geometry engine (AGSGeometryEngine) have been changed to static class methods.

Tasks

Geodatabase Sync Task (AGSGDBSyncTask) has been renamed to AGSGeodatabaseSyncTask. Also, the asynchronous operations to generate new a geodatabase and sync an existing geodatabase now return a job handle (AGSGenerateGeodatabaseJob, and AGSSyncGeodatabaseJob) 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 (AGSExportTileCacheTask) also returns a job handle (AGSExportTileCacheJob, and AGSEstimateTileCacheSizeJob) 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 (AGSGeometryServiceTask) has been removed. Use AGSGeometryEngine instead.

Query Task (AGSQueryTask) has been removed. Use the query...() methods on AGSServiceFeatureTable instead.

Identify Task (AGSIdentifyTask) has been removed. Use identifyGraphicsOverlay...() or identifyLayer...() methods on the mapview instead.

Locator (AGSLocator) has been renamed to AGSLocatorTask. AGSLocatorDelegate has been removed and replaced with completion blocks on the locator task's asynchronous operations that previously required the delegates.

AGSRouteTaskDelegate has been removed and replaced with completion blocks on the route task's asynchronous operations that previously required the delegates.

Geoprocessor (AGSGeoprocessor) has been renamed to AGSGeoprocessingTask. The asynchronous operations to perform the geoprocessing function returns a job handle (AGSGeoprocessingJob). 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 AGSGeoprocessorDelegate has been removed and replaced with completion blocks on the job's asynchronous operations.

Find Task (AGSFindTask) has been removed. No replacement.

Route Task ( AGSRouteTask ), is available at version 100.0, but Closest Facility Task, (AGSClosestFacilityTask) and Service Area Task (AGSServiceAreaTask) are available only from version 100.1 onwards. Their API for inputs and results have changed slightly.

Feature tables

AGSServiceFeatureTable now has a FeatureRequestMode that is similar to the 10.2.x Mode property (Snapshot or OnDemand). 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

The APIs for common operations such as editing, searching, geocoding or routing are the same whether you are online or offline. This is one of the big differences to keep in mind at 100.x. Also, with respect to packaging Offline maps, ArcGIS Pro comes center-stage with the ability to create and share offline mobile map packages. A Mobile Map Package (.mmpk) , represented by the AGSMobileMapPackage class,is a set of items bundled together for transport, often for use in offline workflows. 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 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 (AGSAuthenticationManager) that issues challenges (AGSAuthenticationChallenge) 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 (AGSAuthenticationManagerDelegate).

AGSOAuthLoginViewController has been removed. To support oAuth based authentication in your app you need to set the app's oAuth configuration (AGSOAuthConfiguration) 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 AGSApplicationDelegate to handle this app invocation and complete the oAuth authentication workflow.

Portal

The mapping API has been re-factored to be more integrated with the portal API at version 100.x. The 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, and save maps created with your runtime app as a new portal item. These web maps can then be used elsewhere within the ArcGIS system.

If your applications will be taking advantage of the new map saving capabilities, the Save a map topic will provide great examples for doing this.

The following delegates have been removed - AGSPortalDelegate, AGSPortalGroupDelegate, AGSPortalInfoDelegate, AGSPortalItemDelegate, AGSPortalUserDelegate. They have been replaced with completion blocks on the corresponding asynchronous operations that required the delegates.

AGSPortal, AGSPortalItem, and AGSPortalUser classes implement the loadable pattern (AGSLoadable) which means they must be loaded for their information to be available.

AGSPortalDidLoadNotification and AGSPortalDidFailToLoadNotification notifications have been removed. The loadable protocol provides mechanisms to monitor the loadStatus of the portal.

Error handling

Certainly you've had to handle errors in your applications in many different ways. With 100.x, it's now 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 is available, which indicates if 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 what the error was and what error message should be displayed to the user. For a complete list of error domains and codes, please see the Platform error codes topic in the guide.

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 capabilities. You can license your app either by using a license key or a by logging into a portal with a named user. More details are available in the License your app topic.

XCode project changes

The installation location of ArcGIS.framework on your machine has been slightly changed from the 10.2.4 release. It is now installed under $HOME/Library/SDKs/ArcGIS/macOS/Frameworks/Static (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 macOS 10.12 SDK to build your apps with the Runtime SDK. macOS El Capitan (10.11) and macOS Sierra (10.12) are supported for app deployment.