The first commercial edition of the ArcGIS Runtime SDK for the Microsoft .NET Framework was released as version 10.2.4 in October 2014. ArcGIS Runtime SDK for .NET enables developers to build rich, high-performance GIS applications for Windows PCs, tablets, and phones. The SDK includes three APIs that support building .NET apps for Windows Desktop, Windows Store, and Windows Phone. The APIs share a common design and structure, which encourages sharing implementation logic across the Desktop, Store, and Phone platforms.
Features and functionality for the MapView discussed in this article include setting the map background, defining map interaction options, defining an initial map extent, building geometry, using graphics, working with shapefiles, and performing client-side labeling. This release of the .NET SDK also provides offline editing, security, and licensing options and an enhanced application deployment experience.
MapView
The ArcGIS Runtime SDK for .NET was designed to support the model-view-viewmodel (MVVM) workflows from the start. The relationship between the MapView and Map control exhibits this design. The MapView control is simply a container for a Map control that exposes display-related properties and interaction events.
The Map control is an object with a collection of layers and is designed to support binding scenarios where the map is maintained in a view model or model. The example in Listing 1 shows how easy it is to bind a map created in a view model to the Map property of a MapView. Note that the Map control contents are constructed within the view model and exposed via a public property, MyMap.
MapView Background
To set the background for a map, use the MapView.MapBackground. By default, the map background is gray and contains a grid. To adjust this default, set the color, grid line color, grid width, and line width. Listing 2 provides an example in which the background color is set to light blue and the grid lines are made transparent.
MapView Interaction Options
MapView has InteractionOptions to control interaction with a map using a variety of inputs. This includes enabling and disabling all interaction or just a subset of pan, rotation, and zoom options. For example, the XAML in Listing 3 demonstrates how a set of pan options are enabled, but the user cannnot rotate or zoom in on a map in the MapView.
Setting Initial Map Extent
Use Map.InitialViewpoint to set the startup extent to an envelope or a location and scale. The property can be set in XAML (Desktop only) or in code as shown in Listing 4.
Note that the initial viewpoint can be in a different spatial reference than the map. For example, you can define a startup extent in WGS84 while the map spatial reference is set to Web Mercator. The initial viewpoint will be projected to the map’s spatial reference on the fly.
Creating Geometry
You can use a constructor or a builder to create geometry. In most cases, the constructor is the most efficient and reliable technique. As shown in Listing 5, you can start with a point collection when creating a new polygon.
Graphics Overlays
Graphics overlays enable the display of transient spatial data, such as query results or buffer polygons, as graphics on top of a map (but beneath map overlays). Graphics overlays can persist apart from a map, and graphics in an overlay will be reprojected on the fly to accommodate changes to the underlying map’s spatial reference.
To render a large number of graphics, set the rendering mode to static. When the rendering mode is static, graphics will not refresh until map navigation has stopped, but map responsiveness is retained. For a more fluid graphic rendering experience during navigation, set the rendering mode to dynamic.
Because graphics overlays are not in the map, graphics in overlays will not appear in a map’s legend or be displayed when the map is printed. Listing 7 shows a GraphicsOverlay in XAML with renderer, selection color, rendering mode, and label properties defined. Graphics must be added to the graphics overlay in code.
Working with Shapefiles
The .NET SDK supports direct read of shapefiles for display in a map as a feature layer. Listing 8 shows how to add a shapefile to a map in code (adding shapefiles in XAML is not supported). A default renderer is provided. Set the renderer on the feature layer to change symbology.
Shapefiles do not support editing. Calls to add/update/delete operations will throw a System.NotSupportedException. Also, shapefiles do not support reprojection on the fly. The spatial reference of the map and the shapefile must match for features in the shapefile to be visible.
To reproject a shapefile manually, wait until the spatial reference of the map is set, iterate through features in the shapefile, reproject to the map spatial reference, and add the shapefile features as graphics to a graphics layer or overlay. The code in Listing 9 shows simple conditional logic to determine if shapefile contents need to be displayed as graphics or features. If using a graphics overlay, a renderer must be defined.
It is important to note that QueryAsync will load the entire shapefile into memory. The code example in Listing 9 also shows how to limit the number of features returned using the MaximumRows property. You can use this technique to control the number of features, and thus memory, used in your application.
Client-Side Labeling
Client-side labeling supports feature layers and graphics overlays. If a feature layer references a layer in an ArcGIS service (either map or feature) that defines label info, it will be honored. The API supports defining label properties to manage duplicates, text wrapping, scale limits, placement, position, and the text symbol to use for display—all on the client.
In addition, labeling can be enabled or disabled completely on the MapView. In the example in Listing 10, label properties are defined on a feature layer that contains parcel polygons. Label text uses the attribute value in the “APN” field and places the label horizontally in the center of the polygon but will reposition the label for a best fit. If unable to place, then the label will be removed.
Offline Editing
Use sync-enabled feature services hosted by ArcGIS for Server (version 10.2.2 or higher) and ArcGIS Online to generate local geodatabases with editable feature tables. Local geodatabases can be generated on the fly at runtime or provisioned beforehand and made available on a device. The local geodatabase contains feature tables that can be displayed on a map and features that can be added, updated, and deleted. To apply local edits to a feature table in a geodatabase hosted by a remote feature service, merely synchronize local changes when a connection to the remote service is available. The code example in Listing 11 shows a simplified workflow for creating a local geodatabase from a sync-enabled feature service and then synchronizing changes with the service.
Keep in mind that the edits that are last committed (synced) to the service will overwrite previously committed edits, even if committed edits were made at a later time.
Security Options
Accessing secure resources is easy and flexible. Here is a list of the key characteristics of IdentityManager and its related components. IdentityManager is active by default.
IdentityManager’s challenge delegate has been replaced with a challenge interface, IChallengeHandler. The API also includes a ChallengeHandler class that implements IChallengeHandler and the constructor can be passed a method that matches the interface definition required to handle a challenge, shown in Listing 12.
The Windows Store platform includes Credential Picker, a standard UI for entering credentials. As a result, the default challenge handler (named DefaultChallengeHandler), which is included with ArcGIS Runtime SDK for .NET, is only supported for use with the Windows Store API. The Windows Desktop and Phone platforms do not have a standard UI for entering credentials at this time. The ArcGIS Runtime Toolkit for .NET contains examples of dialogs for entering credentials on both platforms that are available on GitHub. See the SignInChallengeHandler class for more details. Customizing the UI for the SignInChallengeHandler requires modifying source code in the toolkit.
The DefaultChallengeHandler (Windows Store only) and SignInChallengeHandler for Windows Phone support use of a credential locker to store and retrieve credential details. The example in Listing 13 will cast the current challenge handler to DefaultChallengeHandler, enable saving credentials in the credential locker, and include an option in the UI for the user to opt into saving credentials and enable it by default. Since Desktop does not provide a credential locker out of the box, implementation for a credential manager (Desktop only) is included with the ArcGIS Runtime Toolkit for .NET on GitHub.
IdentityManager supports accessing resources on systems secured using ArcGIS tokens, OAuth, network authentication (e.g., Integrated Windows Authentication [IWA]), and client certificates. This includes secure resources hosted by ArcGIS for Server, Portal for ArcGIS, and ArcGIS Online. A set of classes is derived from Esri.ArcGISRuntime.Security.Credential to reference different types of security protocols. These include ArcGISTokenCredential, OAuthTokenCredential, ArcGISNetworkCredential, and CertificateCredential. During a challenge, use CredentialRequestInfo.AuthenicationType to determine the type of credential to create or return.
IdentityManager supports a global OAuth authorize component via the IdentityManager.Current.OAuthAuthorizeHandler property. The component must implement IOAuthAuthorizeHandler and contains logic for hosting the sign-in page and handling authorization results. Windows Store includes OAuth implementation with the DefaultChallengeHandler. The ArcGIS Runtime Toolkit for .NET contains sample handler implementations for entering credentials on both Phone and Desktop. See these samples on GitHub.
Licensing
A set of classes under Esri.ArcGISRuntime support the SDK licensing structure. By default, the SDK runs in developer mode. Running in developer mode results in a watermark on the map (text indicating the SDK is being used for development); debug messages when standard license functionality is used; and a message box when local server starts (Desktop only).
To run an app with a basic license, get a client ID from the ArcGIS for Developers site. Standard licenses are available for purchase in deployment packs. See the licensing documentation on the ArcGIS for Developers site for more details.
The code in Listing 14 shows the licensing code workflow executed on application startup. Note that once an application session is licensed, it cannot be unlicensed.
Deployment Experience
Preparing an application for deployment is integrated with Visual Studio 2013 and 2012 editions (Express editions are not supported). To create a deployment, merely right-click a project in Solution Explorer and select Add ArcGIS Runtime Deployment Manifest.
This will create a Deployment.arcgisruntimemanifest file with a UI to enable or disable the inclusion of resources and components required for use by the application. The resources and components differ depending on the API. When you open the file or build the project, you will be prompted to include imports in your project file to support deployment and reload your project.
When the project is built, resources for deployment will be copied to the output folder for the project. The contents of the output folder can be distributed as a WPF application or used to build an app package for Store or Phone.
Next Steps
To learn more, go to the ArcGIS Runtime SDK for .NET section of the ArcGIS for Developers website, where you can download the product and browse system requirements, guide documentation, and API reference. Source code for an extensive toolkit, instructive samples, and demo applications are available on GitHub to enhance your development experience. For those developers who want to get started quickly with Visual Studio, Esri provides NuGet packages for both the core product and toolkit. Details about the NuGet packages and other tools and features can be found on the ArcGIS for Developers website.
About the author
