ProConcepts Portal - Esri/arcgis-pro-sdk GitHub Wiki

This ProConcepts will go cover the portal API in Pro, its usage, and relevant API functionality.

ArcGIS.Desktop.Core.dll ArcGIS.Desktop.Catalog.dll

Language:      C#
Subject:       Sharing
Contributor:   ArcGIS Pro SDK Team <[email protected]>
Organization:  Esri, http://www.esri.com
Date:          10/06/2024 
ArcGIS Pro:    3.4  
Visual Studio: 2022

• Overview
• ArcGISPortalManager
  • Active Portal
  • Accessing Portals and Portal Events
• ArcGISPortal
  • Signing In
  • Portal Info
  • Portal Content
  • Basemaps

Web GIS is a pattern for delivering GIS capabilities as Internet services that can be consumed by a variety of clients including web, desktop, and mobile applications. A server that hosts GIS content, such as ArcGIS Online, is generically referred to as a portal. Pro SDK Add-ins can consume GIS services and content from portals using the ArcGIS.Desktop.Core.ArcGISPortal class.

The ArcGIS platform offers two deployment models for hosting web GIS services and content: ArcGIS Online and Portal for ArcGIS.

ArcGIS Online is a cloud-based, collaborative content management system for maps, apps, data, and other geographic information. You can access ArcGIS Online through ArcGIS.com to:

• 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 people in your organization

Portal for ArcGIS provides you with the same core capabilities as ArcGIS Online, but can be installed and hosted on-premises, behind the firewall for controlled distribution of content. Portal for ArcGIS is the technology that powers ArcGIS Online and is available to implement in your organization.

ArcGIS Online for organizations, on the other hand, lets your organization be a part of ArcGIS Online through a subscription, without needing to install or manage any server technology. With this subscription, you can set up a configurable secured site that includes administrative controls, flexible data storage capabilities, and other provisions that enable geospatial information to be more pervasive within your organization or general public. Through the subscription, you can also access the Esri cloud to turn your data into web accessible maps.

The ArcGIS Pro SDK allows developers to access and search content, folders, and groups of a general portal (on-premises instance or ArcGIS Online) or a specific organization's subscription within that portal. The collection of portals currently defined for a given session of Pro is controlled by the ArcGIS.Desktop.Core.ArcGISPortalManager class. The ArcGISPortalManager is a singleton and can be accessed via the ArcGISPortalManager.Current property.

By default, a portal connection to ArcGIS online is always added to the ArcGISPortalManager (unless network connectivity, firewall configuration, etc. prevents it). Any portal connection that is defined through the API (via the ArcGISPortalManager AddPortal method) or via the Pro "Portals" backstage tab are included in the ArcGISPortalManager's collection of portals and are shown in the list of Portals on the Portals backstage tab.

At any given point in time there is one Active Portal (or none if there are no portals specified). Usually, the active portal is connected but it does not have to be, especially if the logged on user has chosen (through the UI) not to cache his or her credentials between sessions. Refer to Sign in to your organization and Manage portal connections from ArcGIS Pro for more information on how to interact with ArcGIS Online and Portal via the Pro UI.

Note: You can be connected to many portals during a session but only one portal can be "the" active portal. The active portal drives the Pro catalog content, base maps, and so forth. The active portal is shown on the SignOnControl pulldown accessible on the top right of the Pro application ribbon bar.

To access the Active Portal, invoke the ArcGISPortalManager.Current.GetActivePortal() method. This will return an ArcGISPortal instance for the active portal which you can then manipulate to sign in, sign out, retrieve content, etc.

For example, in this sequence, a new portal connection is added to the session and is set as the active portal if the logged on user successfully connects.

  var portalUri = new Uri("http://myportal.esri.com/portal/", UriKind.Absolute);
  var portal = ArcGISPortalManager.Current.AddPortal(portalUri);
  //Trigger a popup if the user's credentials have not been previously cached
  if (portal.SignIn().success)
  {
    //Set this portal as the active portal
    ArcGISPortalManager.Current.SetActivePortal(portal);
  }

Portals do not have to be instantiated in the Pro SDK. They are automatically created within the ArcGISPortalManager's portal collection based on the set of portal connections defined in the current or previous sessions (and persisted in the user's application properties). Instead, Portals can be added, edited (to change the connection uri), removed, or retrieved via their portal uri. In each case, provide the particular portal uri you wish to manipulate.

In this example, the uri of the current active portal is cached in a variable which is used to retrieve the portal at a later point in time when it is no longer active.

  var active_portal = ArcGISPortalManager.Current.GetActivePortal();
  string cached_portal_uri = active_portal.PortalUri;

  //at some point the user switches active portals...

  //retrieve the portal that was previously active
  var portal = ArcGISPortalManager.Current.GetPortal(cached_portal_uri);

The ArcGISPortalManager provides corresponding events for new portals being added, removed, or edited and for the active portal being changed whether through the API or through the Pro UI. Consult the ProSnippets Sharing for examples.

Portals (within the ArcGIS platform) are content management systems that allows you to share maps, scenes, apps, and other geographic information with other people in your organization. A "portal" comes in one of three flavors:

• ArcGIS Online
• ArcGIS Online for Organizations
• Portal for ArcGIS

ArcGIS Online is a cloud-based version of "portal", ArcGIS Online for Organizations is simply a subscription to ArcGIS Online that lets an organization be part of ArcGIS Online without needing to install or manage any server technology. Portal for ArcGIS is a component of ArcGIS Enterprise. Organizations establish a local "portal" on their own hardware to host their geographic data and processes. Other than Portal for ArcGIS requiring its own server hardware it performs in mych the same role as an account on ArcGIS Online or ArcGIS Online for Organizations. In any case, all three flavors of portal are implemented with the same class: ArcGIS.Desktop.Core.ArcGISPortal.

ArcGISPortal instances are not created via the API. Instead, they are retrieved from the ArcGISPortalManager class which stores and manages all ArcGISPortal instances within the Pro session (refer to the previous section). Only one portal can be the active portal at a given point in time but any ArcGISPortal instance retrieved from ArcGISPortalManager, active or not, can be searched for content and services whereas, only the active portal can be searched via the Pro UI.

Services provided by portal or by ArcGIS for Server may require a login before they can be accessed. Some portals may provide anonymous access to some resources, but restrict access to others based on organization or group membership. "Sign in" to a portal is provided with the portal.SignIn method. If the user has not previously connected during the session, or has not cached his or her credentials, then the user is presented with a popup (typically an OAuth popup) and they must provide their credentials (Integrated Windows Authentication and Public Key Infrastructure, PKI, are also supported).

Once signed in, a token is assigned to the session which is managed by the underlying EsriHttpClient instance. All calls to portal information or content go through EsriHttpClient. To sign out, call portal.SignOut.

Refer to Manage portal connections from Pro.

This method will return (via portal self) the view of the portal as seen by the current user, whether anonymous or logged in. It includes information such as the name, logo, featured items, group queries, organization info, etc. for this portal. If the user is not logged in, this call will return the default view of the portal. If the user is logged in, the view of the returned portal will be specific to the organization to which the user belongs. The default view of the portal is dependent on the culture of the user, which is obtained from the user's profile.

In this example, the code connects to the portal, retrieves the portal info and the (logged-on) user's organization id. If sign in failed, the default view of the portal will be returned and the organization id will be "0".

  var portal = ArcGISPortalManager.Current.GetPortal(new Uri("http://www.arcgis.com"));
  //Force login
  if (!portal.IsSignedOn()) {
     portal.SignIn();
  }
  //If the sign in failed, this will be the default view of the portal
  var portalInfo = await portal.GetPortalInfoAsync();
  var orgid = portalInfo.OrganizationId;

There are two primary search mechanisms on the ArcGISPortal. Use portal.GetUserContentAsync to search for content from given user's home folder (a.k.a "My Content" folder) or from subfolder of the home folder with the given folder ID. Multilevel folders are not supported. A Portal.PortalUserContent instance is returned. It contains two enumerations:

• A collection of the user's Folder Ids
• A collection of the user's content items (from the given folder or home folder)

The corollary for portal.GetUserContentAsync in the Pro UI is the content retrieved for the "My Content" tab in either of the catalog pane or a catalog view.

The SearchItemsAsync method on the ArcGISPortal class can be used to find any type of portal item. The method accepts a PortalQueryParameters argument that holds a query expression and other preferences for the search see topic18193.html. ArcGIS for Portal has a full-featured text search engine and the PortalQueryParameters can accept a query expression and other preferences for the search. The query expression used to set the Query property can further refine search criteria using specific fields as well. Consult the ArcGIS REST API for details on how to format query expressions.

Consult the ProSnippets Sharing for examples on how to query portal. A complete example is provided in portal execute a portal search.

Results from a search are returned in a PortalQueryResultSet<PortalItem> topic18218.html. Depending on the number of results, more than one query may need to be executed to return all the items. The portalQueryParams.Limit property sets the maximum number of results to be included in the result set response. The default value is 10 and the maximum allowed value is 100. The start index, along with the limit parameter can be used to paginate the search results. The actual number of returned results may be less than Limit. This happens when the number of results remaining after StartIndex is less than Limit. If multiple queries are required to retrieve all the results, the resultSet.NextQueryParameters property will contain a new query parameters with the correct StartIndex set for the next page of results. The previous query string and limit is maintained. If the NextQueryParameters is null then there are no more results to be retrieved.

In this example, the results are added to a collection in a loop until there are no more results to be retrieved. The loop will exit when the NextQueryParameters is null.

 //Get all web maps and map services - include user, organization
 // and "usa" in the title with the query
 var query = PortalQueryParameters.CreateForItemsOfTypes(new List<PortalItemType>() {
    PortalItemType.WebMap, PortalItemType.MapService}, owner, "", "title:usa");
 query.OrganizationId = portalInfo.OrganizationId;

 //retrieve in batches of up to a 100 each time
 query.Limit = 100;

 //Loop until done
 var portalItems = new List<PortalItem>();
 while (query != null) {
   //run the search - StartIndex is initially "0".
   PortalQueryResultSet<PortalItem> results = await portal.SearchForContentAsync(query);
   portalItems.AddRange(results.Results);
   query = results.NextQueryParameters;//Null when there are no more results
   //query.StartIndex will have been incremented automatically...
 }

 //process results
 foreach (var pi in portalItems) {
   //Do something with the portal items
 }

Because results are "PortalItems" and PortalItem "is a" Item, it can be passed as the parameter to any of the class factories that consume items (eg MapFactory or LayerFactory) assuming that the provided item represents content of the correct type. Consult ProConcepts Content and Items, portal content.

Administrators of portals or organizations can configure custom basemap galleries. The list of basemaps that comprise the basemap gallery can be retrieved via the portal.GetBasemapsAsync() method, topic 20332. Each basemap is returned as an ArcIGS.Desktop.Core.PortalItem. Any of the basemap items can be set as the Pro basemap on the map via map.SetbasemapLayers(portalItem), topic 20816.