Skip To Content

Access maps and content from your portal

In this topic

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. Your ArcGIS Runtime SDK for .NET apps can consume GIS services from portals using classes available in the Esri.ArcGISRuntime.Portal namespace.

The ArcGIS platform offers two deployment models for hosting web GIS services: 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, mobile devices, and desktop map viewers 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

Tip:

With your free ArcGIS for Developers account, you have access to ArcGIS Online for development and testing, including the ability to create hosted feature services.

Learn more about ArcGIS Online.

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 Runtime SDK allows developers to access and search content, users, and groups of a general portal (on-premises instance or ArcGIS Online) or a specific organization's subscription within that portal. Classes in the API wrap calls to the ArcGIS REST API to communicate with the back end portal.

In this tutorial, you learn how to find and access content stored in a portal, and to incorporate that content into your app.

Prerequisites

This tutorial requires a supported version of Microsoft Visual Studio and ArcGIS Runtime SDK for .NET. Refer to the appropriate topics in the guide for information on installing the SDK and system requirements.

Familiarity with Visual Studio, XAML, and C# is recommended.

Create a WPF app

You'll use Visual Studio to create a WPF app.

  1. Open a supported version of Microsoft Visual Studio.
  2. Choose File > New > Project (or click New Project on the Start page) to create a project.
  3. Click Windows Desktop > WPF Application in the New Project dialog box (you can create your project in either C# or VB .NET).
    Note:

    Visual Studio 2015 organizes project types slightly differently. You'll find WPF Application projects under Windows > Classic Desktop

    Tip:

    ArcGIS Runtime SDK for .NET provides a project template for creating your mapping app, called ArcGIS Runtime 10.2.7 for .NET App. Creating your project from the template will add the appropriate references and a page with a map view containing a single base layer. In this tutorial, you'll build your app from a blank template.

  4. Choose a folder location for your new project and name it PortalApp.

    Visual Studio New Project dialog box

  5. Click OK to create the project.

    Your project opens in Visual Studio and contains a single WPF window called MainWindow.xaml.

  6. Next, you'll add a reference to the ArcGIS Runtime SDK for .NET API assembly.
  7. Right-click the References node under the PortalApp project listing in the Visual Studio Solution Explorer window, and click Add Reference in the context menu.
  8. Check the listing for the Esri.ArcGISRuntime assembly under Assemblies > Extensions.

    Visual Studio Reference Manager dialog box

  9. Click OK to add the reference to ArcGIS Runtime for .NET.

    Visual Studio project references

  10. The Esri.ArcGISRuntime library contains the Map control and all core API components and classes you'll need.

Add a MapView

Your app will contain an empty MapView control. At runtime, your app will connect to, and display content from, ArcGIS Online.

Begin by creating a basic UI for your app. To use the classes in the ArcGIS Runtime API, define XML namespace references in MainWindow.xaml.

  1. Open the MainWindow.xaml page in XAML view.
  2. Add the following XAML in the Windowelement of MainWindow.xaml to define an XML namespace reference for ArcGIS Runtime API.

    xmlns:esri="http://schemas.esri.com/arcgis/runtime/2013"

  3. Inside the Grid element on the page, add the XAML below to create an empty MapView control. Assign the name MyMapView to the control so you can reference it in your code behind.

    <esri:MapView x:Name="MyMapView"/>

Your MapView displays maps and layers from a portal (ArcGIS Online) while the app runs.

Create a search UI

Your app allows the user to search a portal for web maps, feature services, and basemap layers. The user can get a description and thumbnail for search results, and display an item on the map. Begin by creating a UI to receive search criteria from the user and display a list of results.

When complete, your UI looks like the following:

Design view of the UI layout

  1. Open your MainWindow.xaml page in XAML view. Add the following XAML inside the existing Grid element on the page, immediately below the line that defines the MapView.

    <StackPanel Background="White"
            Width="300"  
            HorizontalAlignment="Right"
            Margin="10">
        <StackPanel Orientation="Horizontal" 
                Margin="5">
            <TextBlock Text="Search:"/>
            <TextBox x:Name="SearchTextBox" 
                    Width="100"
                    Margin="10,0"
                    HorizontalContentAlignment="Right"
                    Text="Turtle"/>
            <ComboBox x:Name="ItemTypeComboBox" 
                    SelectedValuePath="Content"
                    Width="120">
                <ComboBoxItem Content="Web map" IsSelected="True"/>
                <ComboBoxItem Content="Feature service"/>
                <ComboBoxItem Content="Basemap"/>
            </ComboBox>
        </StackPanel>
        <Button x:Name="SearchButton"  
            Content="Search ArcGIS.com" 
            Margin="20"/>
        <ListBox x:Name="ResultListBox" 
                Margin="20,0"
                MaxHeight="200">
            <!-- results shown here -->
    
        </ListBox>
        <TextBlock x:Name="SnippetTextBlock" Text="" Height="50" Margin="10" TextWrapping="Wrap"/>
        <Image x:Name="ThumbnailImage" Stretch="UniformToFill" Width="200" Height="133"/>
        <Button x:Name="ShowMapButton" 
            Content="Show Map" 
            Margin="5"
            Width="150" 
            IsEnabled="False"/>
    </StackPanel>

  2. The ResultListBox shows portal items that match your user's search criteria. Add an ItemTemplate to the list box to define how the result items display.
  3. Add the following XAML inside the ListBox element, below the <!-- results shown here --> comment.

    <ListBox.ItemTemplate>
        <DataTemplate>
            <StackPanel Orientation="Vertical">
                <TextBlock Text="{Binding Title}"/>
                <TextBlock Text="{Binding Owner}" FontSize="9"/>
            </StackPanel>
        </DataTemplate>
    </ListBox.ItemTemplate>

    The DataTemplate uses data binding to display the Title and Owner for each search result. At runtime, the ListBox binds to a list of ArcGISPortalItem objects. Title and Owner are properties of those objects.

  4. Define a click event handler for the search button as shown in the following example.

    <Button x:Name="SearchButton"  
        Content="Search ArcGIS.com" 
        Margin="20"
        Click="SearchButton_Click"/>

  5. Right-click the SearchButton_Click handler in your XAML and choose Go To Definition in the context menu. You will add code to this handler to search the portal.

Add code to search the portal

You can search a portal, such as ArcGIS Online, using keywords that describe portal items. You can also narrow your search to specific types of items, such as web maps, layer packages, text files, and so on. Add code to the app's search button to perform such a search based on input from the user.

  1. At the top of the MainWindow.xaml.cs file, add the following using statements for ArcGIS Runtime API namespaces you need.

    using Esri.ArcGISRuntime.Controls;
    using Esri.ArcGISRuntime.Portal;
    using Esri.ArcGISRuntime.WebMap;

  2. Inside the MainWindow class, add the variable declarations below. These variables store private references to the portal (ArcGIS Online) and to the currently selected search result (if any).

    private ArcGISPortal arcGISOnline;
    private ArcGISPortalItem selectedPortalItem;

  3. Add the async keyword to the definition of the SearchButton_Click function, as shown in bold in the following example.

    private async void SearchButton_Click(object sender, RoutedEventArgs e)

    The async keyword in the function definition indicates that asynchronous calls are made in the function that uses the await keyword.

  4. Add the following try catch block to the SearchButton_Click function. If an exception is encountered while searching, the error message is shown to the user.

    try
    {   
       
    }
    catch (Exception ex)
    {
        MessageBox.Show(ex.Message, "Error searching portal");
    }

  5. Inside the try portion of the block, add the following code to initialize a connection to the portal, if it doesn't already exist.

    // if first run, get a ref to the portal (ArcGIS Online)
    if (this.arcGISOnline == null) 
    {
        // create the uri for the portal 
        var portalUri = new Uri("https://www.arcgis.com/sharing/rest");
        // create the portal 
        this.arcGISOnline = await ArcGISPortal.CreateAsync(portalUri); 
    }
    The Esri.ArcGISRuntime.Portal.ArcGISPortal class provides static methods that allow you to connect to a portal.

    Note:

    If you call the static ArcGISPortal.CreateAsync method without arguments, a connection is made to ArcGIS Online. In the previous code, the portalUri variable can be omitted from the arguments and it works the same. If you want to connect to another portal, you provide the portal URI as shown.

  6. After the if block that initializes the arcGISOnline variable, declare a variable to store results of a portal search. The results are an enumerable of ArcGISPortalItem.

    // create a variable to store search results (collection of portal items)
    IEnumerable<ArcGISPortalItem> results = null;

  7. Next, add the following branching statement based on the type of item the user wants to search.

    if (this.ItemTypeComboBox.SelectedValue.ToString() == "Basemap")
    {
    
    }
    else
    {
    
    }
    A search for basemaps uses a different method (SearchBasemapGalleryAsync) and doesn't require a query expression.

  8. In the if portion of your branching statement, add the following code for basemap searches. This asynchronously searches the portal for basemaps and stores the results.

    // basemap search returns web maps that contain the basemap layer
    var basemapSearch = await this.arcGISOnline.ArcGISPortalInfo.SearchBasemapGalleryAsync();
    results = basemapSearch.Results;

    Note:

    SearchBasemapGalleryAsync returns a collection of web maps. Each web map in the results contains the basemap layer described in the portal item.

  9. Below the branching statement, add the following code to bind the collection of portal items to the results list box. You will add the code for the else portion of the branching statement in a following step.

    // show the results in the list box
    this.ResultListBox.ItemsSource = results;

    Here's the code you've written so far:

    private async void SearchButton_Click(object sender, RoutedEventArgs e)
    {
        try
        {
            // if first run, get a ref to the portal (ArcGIS Online)
            if (this.arcGISOnline == null)
            {
                // create the uri for the portal 
                var portalUri = new Uri("https://www.arcgis.com/sharing/rest");
                // create the portal 
                this.arcGISOnline = await ArcGISPortal.CreateAsync(portalUri);
            }
    
            // create a variable to store search results (collection of portal items)
            IEnumerable <ArcGISPortalItem> results = null;
            if (this.ItemTypeComboBox.SelectedValue.ToString() == "Basemap")
            {
                // basemap search returns web maps that contain the basemap layer
                var basemapSearch = await this.arcGISOnline.ArcGISPortalInfo.SearchBasemapGalleryAsync();
                results = basemapSearch.Results;
            }
            else
            {
    
            }
    
            // show the results in the list box
            this.ResultListBox.ItemsSource = results;
        }
        catch (Exception ex)
        {
            MessageBox.Show(ex.Message, "Error searching portal");
        }
    }
  10. Run your app. Choose Basemap from the combo box and click the Search ArcGIS.com button. Several results appear in the list.
    Note:

    Your app does not use the query text when searching basemaps.

    Basemap search results

  11. Stop running your app and return to Visual Studio. Next, you will add code to find web map and feature service portal items using a search term.
  12. In the else portion of your branching statement, add the following code to build a query expression using information provided by the user.

    // get the search term and item type provided in the UI
    var searchTerm = this.SearchTextBox.Text.Trim();
    var searchItem = this.ItemTypeComboBox.SelectedValue.ToString();
    
    // build a query that searches for the specified type
    // ('web mapping application' is excluded from the search since 'web map' will match those item types too)
    var queryString = string.Format("\"{0}\" type:(\"{1}\" NOT \"web mapping application\")", searchTerm, searchItem);

    Note:

    The query string uses the search term provided by the user and also narrows the search to a specified item type. Because a search for items of type Web map also matches items of type Web mapping application, those items have been explicitly excluded from the search using the NOT portion of the expression.

  13. A search for portal items requires a SearchParameters object. Add the following code (directly below the code you added previously) to create a new SearchParameters object that defines the query expression, search result sorting preferences, and maximum number of results for the search.

    // create a SearchParameters object, set options
    var searchParameters = new SearchParameters()
    {
        QueryString = queryString,
        SortField = "avgrating",
        SortOrder = QuerySortOrder.Descending,
        Limit = 10
    };
    A maximum of 10 portal items return for the search, sorted highest to lowest according to the average user rating.

  14. Add the following code to execute the search using the search parameters and store the results.

    // execute the search
    var itemSearch = await this.arcGISOnline.SearchItemsAsync(searchParameters);
    results = itemSearch.Results;

  15. Run your app and test the search. Find web maps and feature services using search terms.

    Web map search results

Next, you will display properties for the chosen portal item in the list, including a thumbnail image and item description.

Show portal item properties

Currently, the title and owner name are the only information displayed for portal items found in a search. You will now add code to display a short description and a thumbnail image for the chosen portal item.

  1. In MainWindow.xaml, add an event handler for the ResultListBox control's SelectionChanged event, as shown in the following example.

    <ListBox x:Name="ResultListBox" 
            Margin="20,0"
            MaxHeight="200"
            SelectionChanged="ResultList_SelectionChanged">

  2. Right-click ResultList_SelectionChanged in your XAML and choose Go To Definition in the context menu.
  3. Before coding the ResultList_SelectionChanged handler, add the following function (ResetUI) to reset values for several of the UI controls. You will call this function when a new selection is made in the results list to make sure the UI is in sync with the currently chosen portal item.

    private void ResetUI()
    {
        // clear UI controls
        this.SnippetTextBlock.Text = "";
        this.ThumbnailImage.Source = null;
        this.ShowMapButton.IsEnabled = false;
    }

  4. Return to the ResultList_SelectionChanged function. Add the following code to call your new ResetUI function.

    // clear UI controls
    this.ResetUI();

  5. Add the following code to store the chosen portal item in the private variable you defined previously (selectedPortalItem). Return from the handler if the current item is null.

    // store the currently selected portal item 
    this.selectedPortalItem = this.ResultListBox.SelectedItem as ArcGISPortalItem;
    if (this.selectedPortalItem == null) { return; }
    In the rest of the code in this function, you can safely assume that selectedPortalItem refers to a portal item.

  6. The Snippet property on ArcGISPortalItem contains a brief description of the item in plain text. Add the following code to show a description of the item if the snippet is not null.

    // show the portal item snippet (brief description) in the UI
    if (!string.IsNullOrEmpty(this.selectedPortalItem.Snippet)) 
    {
        this.SnippetTextBlock.Text = this.selectedPortalItem.Snippet;            
    }

    Note:

    ArcGISPortalItem also provides a Description property, which provides information about the item formatted as HTML.

  7. A portal may or may not have a thumbnail image. Add the following code to display an image for the chosen portal item if the ThumbnailUri property is not null.

    // show a thumbnail for the selected portal item (if there is one)
    if (this.selectedPortalItem.ThumbnailUri != null)
    {
        var src = new BitmapImage(this.selectedPortalItem.ThumbnailUri);
        this.ThumbnailImage.Source = src;
    }

  8. Run your app and test the new code. Search for portal items and choose one in the list of results. A description and thumbnail image displays on the page.

    Portal item description and thumbnail

Display portal items in the map

After finding a portal item, you can work with the data it represents. You may want to show a web map from a portal item, including all the layers it contains or you may want to choose individual layers to display. In the following steps, add code to display a web map from a chosen portal item.

  1. Open your MainWindow.xaml page in XAML view.
  2. Add a click handler to ShowMapButton as shown in the following example.

    <Button x:Name="ShowMapButton" 
            Content="Show Map" 
            Margin="5"
            Width="150" 
            IsEnabled="False"
            Click="ShowMapButton_Click"/>

  3. Right-click ShowMapButton_Click in your XAML and choose Go To Definition in the context menu.
  4. In MainWindow.xaml.cs, add the async keyword to the ShowMapButton_Click event handler, as shown in the following example.

    private async void ShowMapButton_Click(object sender, RoutedEventArgs e)

  5. Before coding the ShowMapButton_Click event handler, add code to enable the button only when a portal item of type web map is chosen in the result list.
  6. At the end of the ResultList_SelectionChanged event handler, add the code shown in the following example to enable the ShowMapButton control when a web map type of portal item is chosen in the list.

    // enable the show map button when a web map portal item is chosen
    this.ShowMapButton.IsEnabled = (this.selectedPortalItem.Type == ItemType.WebMap);

  7. You can now add code to the ShowMapButton_Click event handler with the assumption that a web map portal item is currently chosen. The static FromPortalItemAsync method on the Esri.ArcGISRuntime.WebMap.WebMap class opens a web map from a portal item. Use this method to get the web map represented by the currently chosen portal item in the list.
  8. Return to ShowMapButton_Click and add the code shown in the following example to open the web map represented by the chosen portal item.

    // create a web map from the selected portal item
    var webMap = await WebMap.FromPortalItemAsync(this.selectedPortalItem);

    The WebMap class contains properties for accessing the basemap layers, operational layers, and tasks the map contains. To display the entire map, load the web map into a WebMapViewModel object and reference its Map property.

    Tip:

    For more information about the Model-View-ViewModel design pattern, for which the WebMapViewModel is designed, refer to the Use the MVVM design pattern tutorial.

  9. Add the code shown in the following example to create a new WebMapViewModel containing the web map. LoadAsync is a static method on the WebMapViewModel class.

    // load the web map into a web map view model
    var webMapVM = await WebMapViewModel.LoadAsync(webMap, this.arcGISOnline);

  10. Complete the ShowMapButton_Click event handler by adding the code in the following example to show the web map on your page's MapView control.

    // show the web map view model's map in the page's map view control
    this.MyMapView.Map = webMapVM.Map;

  11. Run your app. Search for web maps, select one in the result list, then click the Show Map button. The chosen web map displays in your map view. Try searching the feature services. The Show Map button is not enabled when a feature service portal item is chosen in the list.

    Displaying a webmap from ArcGIS Online

Well done, you've completed the tutorial. For more examples of working with content from a portal, see the arcgis-runtime-samples-dotnet repository on GitHub. For a fully functional portal viewer application built using the Model-View-ViewModel (MVVM) design pattern, see the arcgis-portalviewer-dotnet repository.

Related topics