ArcGIS Runtime SDK for .NET (WPF)

Access the ArcGIS platform

The ArcGIS platform provides a full range of GIS capabilities. There are various ways to add powerful functionality and intelligence to your ArcGIS Runtime app by connecting to platform capabilities.

ArcGIS Online

ArcGIS Online is a cloud-based, collaborative content management system for maps, apps, data, and other geographic content. You can access ArcGIS Online through mobile devices, a website (www.ArcGIS.com), and desktop map viewers. With ArcGIS Online you can do the following:

  • Create web maps.
  • Web enable your data.
  • Share your maps, data, and applications.
  • Find relevant and useful basemaps, data, and configurable GIS resources.
  • Manage content and users in your organization.

Tip:

With your free ArcGIS for Developers account, you have access to ArcGIS Online for development and testing. Sign in at developers.arcgis.com or www.ArcGIS.com. You may want to upgrade to a paid ArcGIS Developer Subscription.

Using ArcGIS Runtime SDK, you can work with content in a portal, for example you can access and edit existing content and create new content items, search for users and groups, and share and unshare items.

Learn more about developing with ArcGIS Online in ArcGIS Online Help.

ArcGIS for organizations

To access all the capabilities of ArcGIS Online, your organization can purchase a subscription. With this subscription, you can store and process geographic data, solve complex routing problems, perform spatial analysis, create reports, and enrich your own data with demographic and geographic attributes. You also gain access to various productivity apps. A subscription can help you make geospatial information more pervasive both within your organization and throughout the general public.

Tip:

Your free ArcGIS for Developers account includes some subscription-only services for development and testing. Sign in at developers.arcgis.com or www.ArcGIS.com. If you upgrade your free account to a paid plan, you can still sign in using both of these sites.

Learn more about ArcGIS for organizations on esri.com.

Portals, users, roles, groups, and sharing

ArcGIS Online is an information portal and is represented in the API by the ArcGISPortal class. This class is loadable.

When you sign in to ArcGIS Online with an organization account, you see a specialized view that your organization administrator has configured for you, giving you access to maps, content, and other services specific to your organization. You can also access all your own content and services.

A registered user of a portal is represented in the API by the PortalUser class. When you have signed in to a portal, you can get authentication information relating to the authenticated user from the portal class. Several options are available for signing in to a portal, such as OAuth 2.0, network credentials, tokens, and public keys (PKI). Two authentication patterns are available—named user and app login. For an overview of the ways to access secure services, see ArcGIS Security and Authentication.

Portals and named users have an essential role to play in some app licensing scenarios. For more information about licensing, see License your app.

Groups are a way to collaborate with other users who share a common interest. A user can create groups, join groups, and share items with those groups. Groups have titles, descriptions, thumbnails, and unique IDs to help users identify them. The sharing model within ArcGIS Online is based on groups. Groups are represented in the API by the PortalGroup class.

A free, public account is another way to access ArcGIS Online. These accounts are not associated with an organization and offer a limited set of functionality. A public account allows you to use and create maps and share your maps and apps with everyone. Public accounts are for noncommercial use only.

Connect to public content and services on ArcGIS Online

To connect to ArcGIS Online and access public content anonymously, you can begin by creating a portal, without authenticating with the portal.

// call the static method CreateAsync without arguments to get a reference to the arcgis.com portal
ArcGISPortal portal = await ArcGISPortal.CreateAsync();


// get portal info and display it to the user
PortalInfo portalInfo = portal.PortalInfo;


Console.WriteLine(string.Format("Access: {0}", portalInfo.Access.ToString()));
Console.WriteLine(string.Format("Name: {0}", portalInfo.PortalName));
Console.WriteLine(string.Format("Mode: {0}", portalInfo.PortalMode.ToString()));

From here, you can access public content; for example, you can display a web map, or download the data stored in a portal item. You can also search for content such as web maps, map services, map features, groups, and users.

Some organizations share content publicly and allow anonymous access to that content; connect to publicly accessible content from such organizations by specifying the organization URL. For example:

// call the static method CreateAsync with a Uri argument to get a reference to a specific portal
ArcGISPortal portal = await ArcGISPortal.CreateAsync(new Uri("http://anorganization.maps.arcgis.com/sharing/rest"));

Connect to secured content and services on ArcGIS Online

Apps that target organization users who are known to the ArcGIS platform (named users) should pass a credential for the user when creating the portal object.

// generate an ArcGISTokenCredential using input from the user (username and password)
var cred = await AuthenticationManager.Current.GenerateCredentialAsync(
                                                new Uri("http://anorganization.maps.arcgis.com/sharing/rest"),
                                                userName,
                                                password) as ArcGISTokenCredential;


// connect to the portal, pass in the token 
ArcGISPortal portal = await ArcGISPortal.CreateAsync(
                                                new Uri("http://anorganization.maps.arcgis.com/sharing/rest"),
                                                cred,
                                                CancellationToken.None);


// get the current portal user and check privileges
PortalUser user = portal.User;
IEnumerable<PortalPrivilege> privileges = user.Privileges;

The portal object now has access to all the secure content for which the user has access rights and can be used to find out more information about the user, such as the user's full name (instead of the account user name). Additionally, information about the organization such as the name, banner image, description, and so on, can be found as shown above. Apps often make use of this information when a user connects to a specific portal, to show the user organization branding and context.

Typically, the portal object with the authenticated user is cached and used throughout the app session, to provide the app with a view of a portal that is centered around a single user. When the app is restarted, the credential must be reinstated, or the user must repeat the authentication process.

To access secure content, an app needs to provide a way to sign in to the platform, a process often known as authentication. The recommended approach for authenticating a user known to the platform is to use a user login and OAuth. Apps that target users who are unknown to the ArcGIS platform can authenticate with the platform on behalf of the user by using an app login.

ArcGIS Enterprise

ArcGIS Enterprise provides you with the same core capabilities as ArcGIS Online, but it can be installed and hosted on your own premises, behind your firewall, for controlled distribution of content.

Learn more about ArcGIS Online on esri.com.

Connect to ArcGIS Enterprise portal

Connecting to an instance of ArcGIS Enterprise portal is done in a very similar way to connecting to ArcGIS Online and is represented in the API by the same class, ArcGISPortal. Use the URL to the Enterprise portal website, along with an appropriate credential valid on that portal, or no credential if accessing public content anonymously.

// generate an ArcGISTokenCredential using input from the user (username and password)
var cred = await AuthenticationManager.Current.GenerateCredentialAsync(
                                                new Uri("http://geoportal.mycompany.com/sharing/rest"),
                                                userName,
                                                password) as ArcGISTokenCredential;


// connect to the portal, pass in the token 
ArcGISPortal portal = await ArcGISPortal.CreateAsync(
                                                new Uri("http://geoportal.mycompany.com/sharing/rest"),
                                                cred,
                                                CancellationToken.None);


// get the current portal user and check privileges
PortalUser user = portal.User;
IEnumerable<PortalPrivilege> privileges = user.Privileges;

ArcGIS Server

ArcGIS Server (a component of ArcGIS Enterprise) is a complete and integrated server-based GIS, allowing you to publish many different types of GIS services for use by a variety of clients including ArcGIS Runtime apps. Some services provide similar functionality to that available from ArcGIS Online—for example, you can create map layers based on map, feature, or WMS services, and perform geocoding, routing, or geoprocessing functions by using services hosted by ArcGIS Server.

Discover content and services on ArcGIS Server

Use the ArcGIS Services Directory to browse the available services on an ArcGIS Server site. Open the REST Services home page in a browser, for example, http://sampleserver6.arcgisonline.com/arcgis/rest/services.

Contact your ArcGIS Server system administrator if you're uncertain about the server URL or ArcGIS instance.

Connect to ArcGIS Server

Connecting to ArcGIS Server is a little different from connecting to portals—in the place of connecting to the portal itself, you pass the URL of the service you want to use to a class designed to work with that service type.

For example, you can create a map layer by passing in the URL to a dynamic map service:

var uri = new Uri(@"http://sampleserver6.arcgisonline.com/arcgis/rest/services/DamageAssessment/MapServer");
ArcGISMapImageLayer dynamicLayer = new ArcGISMapImageLayer(uri);

If the service is secured, valid credentials or authentication will be required.

ArcGIS Server services are listed below, along with the classes that make use of them.

Service typeAPI classes

Feature service

FeatureLayer, FeatureTable

Map service—Dynamic

ArcGISMapImageLayer

Map service—Tiled

ArcGISTiledLayer

ArcGIS Server services and related API classes

Learn more about ArcGIS for Server on esri.com.

Authentication Manager

Your app may need to access secured resources that are restricted to authorized users. For example, your organization may host private data layers or feature services that are only accessible by verified users. You may also need to take advantage of premium ArcGIS Online services, such as routing, that require secured user access. The ArcGIS platform provides many ways to secure access to your organization's content and services. The ArcGIS Runtime SDK provides full support for access to secured ArcGIS Server, ArcGIS Online, or ArcGIS Enterprise resources using the following authorization methods:

  • ArcGIS Tokens: proprietary token-based authentication mechanism.
  • OAuth 2.0: secure delegated access to server resources.
  • Web-tier security: HTTP secured service / Integrated Windows Authentication (IWA).
  • Certificate: Public Key Infrastructure (PKI).

Implementing these security methods in your app (potentially for a variety of platforms) can be a lot of work. To simplify authentication, ArcGIS Runtime provides classes to automate the process: Authentication Manager (AuthenticationManager) and Authentication Challenge (_NONE_SUCH_CLASS_).

The Authentication Manager manages access by the app to secured resources. This singleton creates an Authentication Challenge whenever an authentication or security issue is encountered anywhere in the API. The types of Authentication Challenge include the following:

  • Username / password: Challenges needing username / password authentication.
  • OAuth: Challenges needing an OAuth authorization code.
  • Client Certificate: Challenges needing a client certificate to be provided.
  • Secure Sockets Layer (SSL) Handshake - Challenges needing a response to certain SslError errors, usually an untrusted host due to a self-signed certificate.

Your app responds to an Authentication Challenge by providing the requested authentication information, which may be a certificate, credentials, or username and password.

After your app provides the authentication information, the Authentication Manager caches that information. The Authentication Manager contains an instance of a CredentialCache which maintains a cache of credentials, in memory, that have been previously used to satisfy authentication challenges. This allows a credential to be reused where appropriate, and prevents unnecessary or duplicate challenges from being issued while accessing secure resources from the same security realm. Caching happens automatically if credential caching is enabled on the Authentication Manager. When the app wants to sign out, clear the credential cache within the Authentication Manager.

Related topics