Migrate to 100.x from 10.2.x

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.

Changes to ArcGIS Runtime SDK for .NET

Many of the changes described in this topic apply to all ArcGIS Runtime SDKs because the architectural changes for version 100.x were implemented at the lowest level of ArcGIS Runtime. Changes specific to ArcGIS Runtime SDK for .NET are related to the APIs for individual platforms and frameworks and how they are delivered to your development projects. For more information related to this release, refer to the Release notes.

• ArcGIS Runtime SDK for .NET contains APIs for the following platforms:

  • Universal Windows Platform (UWP) - Replaces the 10.2.x Windows Store and Windows Phone APIs.
  • Windows Presentation Framework (WPF)
  • Windows UI Library (WinUI)
  • Xamarin.Android
  • Xamarin.iOS
  • Xamarin.Forms - Supports cross-platform development for Android, iOS, and UWP.

• The SDK is provided as a Visual Studio extension that adds project templates to your Visual Studio instllation. You can find and install the extension directly in Visual Studio using the Manage Extensions dialog.

• If your software development environment is not always connected to the internet, you can download an alternative Visual Studio extension from the ArcGIS Developer site that can be installed into Visual Studio on Windows using a .vsix file. This extension will install project templates and deploy a set of NuGet packages as a local source on your machine. See Install and setup for more information.

• You do not need to install the Visual Studio extension to access the NuGet packages. Each of the APIs listed above can be added to your project from NuGet packages hosted on nuget.org.

• ArcGIS Runtime Local Server is now a separate installation. When developing an ArcGIS Runtime app, you can use the ArcGIS Runtime API to work with geoprocessing and map services in Local Server. The Local Server components themselves are installed separately with ArcGIS Runtime Local Server SDK. See Install Local Server for details.

• .NET requirements continue to change. Check the system requirements for the minimum required version of .NET and the Visual Studio workloads required for the platform(s) targeted by your app.

• The process for creating a deployment for your app has been simplified in 100.x and no longer requires an ArcGIS Runtime .NET Deployment Manifest. See Deployment for details.

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

In ArcGIS Runtime SDK for .NET, at 10.2.7, the Map and Scene objects were split out from the controls that display them (MapView and SceneView) in order to facilitate a Model-View-ViewModel (MVVM) architecture for your apps. At 100.0.0, this change was adopted by all ArcGIS Runtime SDKs. If your app was created with ArcGIS Runtime SDK for .NET 10.2.7, this will not affect your migration to 100.x.

Views

The GeoView base class, inherited by MapView and SceneView, is solely responsible for display and interaction, separating concerns from the model objects (Map and Scene) and allowing the APIs to be simplified and harmonized between the 2D and 3D worlds. GeoView contains graphics overlays, as well as operations, to easily identify features and graphics without having to write any layer type specific code. At 100.0.0, this change was adopted by all ArcGIS Runtime SDKs. If your app was created with ArcGIS Runtime SDK for .NET 10.2.7, this will not affect your migration to 100.x.

Loadable

The ILoadable 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 ILoadable 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 ArcGISFeatureTable return ArcGISFeature object which implements the loadable pattern for increased efficiency. When getting ArcGISFeature 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 are used to display temporary or ad-hoc geographic data on top of a map. In 10.2.x, you could add graphics to your map using a GraphicsLayer. At 10.2.7, the introduction of GraphicsOverlay allowed graphics to be displayed as part of the map view or scene view. GraphicsOverlay ensures that graphics are always displayed on top of everything else in the view, even when layers are reordered or the map is changed. Graphics in an overlay are also reprojected, conforming to the spatial reference assigned to the view. Starting at 100.0.0, graphics may only be displayed in a GraphicsOverlay, GraphicsLayer is no longer available.

Also at 100.x, there is a easier pattern for identifying graphics within graphics overlays. The IdentifyGraphicsOverlayAsync method on GeoView (MapView or SceneView) identifies visible graphics in the specified graphics overlay, near the provided screen point. The Identify graphics code sample illustrates this technique.

Feature tables

ServiceFeatureTable 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.

ServiceFeatureTable no longer has Where or OutFields properties. To filter the data returned from the service, you can call ServiceFeatureTable.PopulateFromServiceAsync with values for those parameters.

Identify features and graphics

FeatureLayer and GraphicsOverlay no longer have a HitTestAsync method for identifying features or graphics (GeoElement objects) that intersect a geometry. Instead, you should use one of the following methods on GeoView to do the equivalent.

• IdentifyGraphicsOverlayAsync - Identify graphics from a single GraphicsOverlay in the view.
• IdentifyGraphicsOverlaysAsync - Identify graphics from all GraphicsOverlay objects in the view.
• IdentifyLayerAsync - Identify features from a single Layer in the view.
• IdentifyLayersAsync - Identify features from all Layer objects in the view.

See Identify graphics sample for an example of using these methods.

Geoprocessing

The 10.2.x Geoprocessor class has been replaced with GeoprocessingTask in 100.x. The task can create a geoprocessing job that tracks progress of the server processing. You can listen for status changes as the job progresses, and respond when it's complete by reading the results (outputs) from the job. The process is outlined in the following steps.

1. Create a new GeoprocessingTask. Pass in the Uri for the geoprocessing service endpoint.
2. Create a new GeoprocessingParameters object to store the inputs to the task.
3. Call GeoprocessingTask.CreateJob to return a GeoproccessingJob. Pass in the GeoprocessingParameters.
4. Set up a listener for the GeoproccessingJob.JobChanged event.
5. Start the job by calling GeoproccessingJob.Start.
6. In the JobChanged handler, check the job status.

When the status is JobStatus.Succeeded, call GetResultAsync to get the results, which includes a dictionary of outputs and (optionally) a map image.

Hydrography

At 100.2.0, a new EncLayer displays content from ENC (Electronic Navigational Charts) data in S-57 format. In addition to displaying and identifying features, you can change various display settings for view groups, text, and other elements (such as isolated dangers, contours, color scheme, and so on). In 10.2.x, this functionality is available in the Esri.ArcGISRuntime.Hydrographic namespace. At 100.2.0, you'll find the same API in Esri.ArcGISRuntime.Hydrography namespace.

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 MobileMapPackage 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 MobileMapPackage 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 GeodatabaseSyncTask works with ArcGIS feature services to take features offline in a mobile geodatabase (.geodatabase file) and allow them to be edited and synced. The ExportTileCacheTask 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.

The pattern for generating a local geodatabase has changed at 100.x and you'll need to make some changes to this code if migrating a 10.2.x app.

1. Call GeodatabaseSyncTask.CreateAsync to create an instance of the GeodatabaseSyncTask. Pass in the Uri for the feature service endpoint.
2. Set some of the same 10.2.x options, such as ReturnAttachments, OutSpatialReference, and SyncModel.
3. Call GeodatabaseSyncTask.GenerateGeodatabase to return a GenerateGeodatabaseJob.
4. Set up a listener for the GenerateGeodatabaseJob.JobChanged event.
5. Start the job by calling GenerateGeodatabaseJob.Start.
6. In the GenerateGeodatabaseJob.JobChanged handler, check the job status.
7. When the status is JobStatus.Succeeded, read the contents of the database, add feature layers to the map, and so on.

Authentication

All security and authentication related aspects are managed by a new AuthenticationManager class which helps to unify and centralize how authentication is performed, regardless of the security solution in place. It allows the developer to decide how much control to exercise over authentication-related events handled by an app. It also caches credentials by default, reducing the number of times a user is prompted for credentials. The authentication manager issues an authentication challenge whenever authentication-related events occur. Developers can monitor these challenges and respond with appropriate credentials to get access to secured resources, or allow the authentication manager to prompt the end user for credentials.

One change you will notice from the previous IdentityManager is that Uri objects are generally now used to represent URL endpoints (instead of using URL strings). ServerInfo.ServerUri is now set with a System.Uri rather than a string. Likewise, AuthenticationManager.FindCredential, AuthenticationManager.GenerateCredential, and IOAuthAuthorizeHandler.AuthorizeAsync take Uri objects as arguments instead of strings.

For some examples of using AuthenticationManager to handle authentication in your runtime app, see the Create and save map and ArcGIS token challenge samples.

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 WebMap and WebMapViewModel classes are no longer used to load a web map from a portal. At 100.x, the Map class has constructors that take either a PortalItem or a Uri representing the web map.

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.

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.

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.

Minor changes

Many of the breaking changes you will encounter when migrating your app from 10.2.x to 100.x are due to classes moving to a different namespace or changes to class or member names. This section describes some of the reorganizing and renaming in the API between these versions.

Namespace changes

Some of the namespaces that were available in 10.2.x of ArcGIS Runtime SDK for .NET have been removed. Usually, the classes that existed in these namespaces have been moved elsewhere. Sometimes, the same functionality exists at 100.x but has been implemented in a new class.

• Esri.ArcGISRuntime.Layers no longer exists. The classes found here at 10.2.x are now in the Esri.ArcGISRuntime.Mapping namespace.
• Esri.ArcGISRuntime.Controls no longer exists. Classes like MapView and SceneView are now in the Esri.ArcGISRuntime.UI.Controls namespace. Others, such as GraphicsOverlay and map grids are now in the Esri.ArcGISRuntime.UI namespace. Things like Map and Camera have been moved to the new Esri.ArcGISRuntime.Mapping namespace.
• Esri.ArcGISRuntime.Symbology.SceneSymbology no longer exists. The corresponding 100.x classes are in the Esri.ArcGISRuntime.Symbology namespace.
• Esri.ArcGISRuntime.WebMap no longer exists. Many of the classes found here at 10.2.x have been moved to Esri.ArcGISRuntime.Mapping and Esri.ArcGISRuntime.Mapping.Popups namespaces.
• At 10.2.x, the classes for working with Electronic Navigational Charts (ENC) are in the Esri.ArcGISRuntime.Hydrographic namespace. In 100.2.0, you'll find them in Esri.ArcGISRuntime.Hydrographic (as well as an EncLayer in Esri.Mapping).

Class and member name changes

Several classes, properties, and methods have been renamed at 100.x for clarity and succinctness. The following table lists some naming changes in the API.

Member Category	10.2.x	100.x
Layers	ArcGISTiledMapServiceLayer	ArcGISTiledLayer
	ArcGISLocalTiledLayer	ArcGISTiledLayer
	SceneLayer	ArcGISSceneLayer
	IdentityManager	AuthenticationManager
	Layer.ID	Layer.Id
	Layer.DisplayName	Layer.Name
	ArcGISTiledMapServiceLayer.ServiceUri (string)	ArcGISTiledLayer.Source (Uri)
	ArcGISLocalTiledLayer.Path (string)	ArcGISTiledLayer.Source (Uri)
MapView	Events: MapViewTapped, MapViewDoubleTapped, and so on.	These events are now defined on the GeoView base class: GeoViewTapped, GeoViewDoubleTapped.
	MapView.ExtentChanged	GeoView.ViewPointChanged
	Extent (Envelope)	VisibleArea (Polygon)
	Editor	SketchEditor
	DrawShape enum (defines shape type for Editor to draw).	SketchCreationMode
	MinScale, MaxScale	These properties are now defined on the Map: Map.MinScale, Map.MaxScale
	WrapAround (bool)	WrapAroundMode (WrapAroundMode enum)
	LayerLoaded	LayerViewStateChanged
Portal	ArcGISPortalItem	PortalItem
	ArcGISPortalUser	PortalUser
	ArcGISPortalGroup	PortalGroup
	QueryParameters, SearchParameters	PortalQueryParameters
	SearchResultInfo<T>	PortalQueryResultSet<T>
	ArcGISPortal.CurrentUser	ArcGISPortal.User
	ArcGISPortal.SearchItemsAsync	ArcGISPortal.FindItemsAsync
Symbology and renderers	3D Marker symbols, such as BoxMarkerSymbol, SphereMarkerSymbol, and so on.	Use SimpleMarkerSceneSymbol and set the Style using a value from the SimpleMarkerSceneSymbolStyle enum.
	ClassBreaksRenderer.Field	ClassBreaksRenderer.FieldName
	ClassBreaksRenderer.Infos (ClassBreakInfo collection)`	ClassBreaksRenderer.ClassBreaks (ClassBreak collection)
SceneView and Scene	Scene.Surface	Scene.BaseSurface
	ServiceElevationSource	ArcGISTiledElevationSource
	FileElevationSource	RasterDataSource
	SceneView.ElevationExaggeration	Surface.ElevationExaggeration