Skip To Content ArcGIS for Developers Sign In Dashboard

ArcGIS Runtime SDK for .NET

Download a preplanned map area

This code sample is available for these platforms:
View Sample on GitHub

Take a map offline using an available preplanned map area.

Use case

When a map is taken offline, a package containing basemap tiles, feature data, and other resources is created. In the preplanned workflow, the author of the web map has set up the offline packages ahead of time, which enables faster, more resource-efficient downloads compared to an on-demand workflow. Because the resources for the area are packaged once and can be downloaded many times by different users, this approach is more scalable for large organizations. To see the difference for yourself, compare this sample to the Generate an offline map sample.

How to use the sample

Select a map area to take offline, then use the button to take it offline. If the area is already offline, the offline copy will be opened. Click 'Delete offline areas' to remove any downloaded map areas.

How it works

  1. Open the map from a Portal item and display it.
  2. Create an OfflineMapTask from the Portal item.
  3. Call _offlineTask.GetPreplannedMapAreasAsync() to find the preplanned areas, then load each one by calling _area.LoadAsync().
  4. Display the areas in the UI.
  5. When the user selects a map area, start the download.
    1. Create a DownloadPreplannedOfflineMapParameters using OfflineMapTask.CreateDefaultDownloadPreplannedOfflineMapParametersAsync.
    2. Create a DownloadPreplannedOfflineMapJob using OfflineMapTask.DownloadPreplannedOfflineMap, passing in the parameters.
    3. Wait for the job to complete with job.GetResultAsync().
    4. Display any errors to the user.
    5. Show the offline map in the MapView.

Relevant API

  • DownloadPreplannedOfflineMapJob
  • DownloadPreplannedOfflineMapParameters
  • DownloadPreplannedOfflineMapResult
  • DownloadPreplannedOfflineMapResult.HasErrors
  • DownloadPreplannedOfflineMapResult.LayerErrors
  • DownloadPreplannedOfflineMapResult.TableErrors
  • OfflineMapTask
  • OfflineMapTask.CreateDefaultDownloadPreplannedOfflineMapParametersAsync
  • OfflineMapTask.DownloadPreplannedOfflineMap
  • OfflineMapTask.GetPreplannedMapAreasAsync
  • PreplannedMapArea

About the data

The Naperville stormwater network map is based on ArcGIS Solutions for Stormwater and provides a realistic depiction of a theoretical stormwater network.

Additional information

See Take a map offline - preplanned to learn about preplanned workflows, including how to define preplanned areas in ArcGIS Online.

Tags

Offline, preplanned, pre-planned, map area

Sample Code

<ContentPage
    x:Class="ArcGISRuntimeXamarin.Samples.DownloadPreplannedMap.DownloadPreplannedMap"
    xmlns="http://xamarin.com/schemas/2014/forms"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:esriUI="clr-namespace:Esri.ArcGISRuntime.Xamarin.Forms;assembly=Esri.ArcGISRuntime.Xamarin.Forms"
    xmlns:resources="clr-namespace:Forms.Resources;assembly=ArcGISRuntime">
    <RelativeLayout>
        <esriUI:MapView
            x:Name="MyMapView"
            BindingContext="{x:Reference Name=ResponsiveFormContainer}"
            Style="{StaticResource MapWithFormStyle}" />
        <resources:ResponsiveFormContainer x:Name="ResponsiveFormContainer">
            <StackLayout>

                <Label
                    x:Name="MessageLabel"
                    HorizontalTextAlignment="Center"
                    Text="Select an area, then download it." />
                <ListView
                    x:Name="AreasList"
                    HeightRequest="150"
                    ItemSelected="AreaSelected">
                    <ListView.ItemTemplate>
                        <DataTemplate>
                            <ViewCell>
                                <OnPlatform x:TypeArguments="View">
                                    <On Platform="iOS, Android">
                                        <Grid>
                                            <Grid.ColumnDefinitions>
                                                <ColumnDefinition Width="auto" />
                                                <ColumnDefinition Width="*" />
                                            </Grid.ColumnDefinitions>
                                            <Image
                                                Grid.RowSpan="2"
                                                Margin="-10,2,2,2"
                                                HeightRequest="70"
                                                Source="{Binding PortalItem.ThumbnailUri}" />
                                            <Label
                                                Grid.Column="1"
                                                Margin="10,0"
                                                Text="{Binding PortalItem.Title}"
                                                VerticalTextAlignment="Center" />
                                        </Grid>
                                    </On>
                                    <!--  Work around nasty Xamarin.Forms bug that affects UWP only - https://github.com/xamarin/Xamarin.Forms/issues/5188  -->
                                    <On Platform="UWP">
                                        <Label
                                            Margin="10,0"
                                            Text="{Binding PortalItem.Title}"
                                            VerticalTextAlignment="Center" />
                                    </On>
                                </OnPlatform>
                            </ViewCell>
                        </DataTemplate>
                    </ListView.ItemTemplate>
                </ListView>
                <Grid>
                    <Grid.ColumnDefinitions>
                        <ColumnDefinition Width="*" />
                        <ColumnDefinition Width="*" />
                        <ColumnDefinition Width="*" />
                    </Grid.ColumnDefinitions>
                    <Button
                        x:Name="DownloadButton"
                        Grid.Column="0"
                        Clicked="OnDownloadMapAreaClicked"
                        Text="Download" />
                    <Button
                        Grid.Column="1"
                        Clicked="OnDeleteAllMapAreasClicked"
                        Text="Delete all" />
                    <Button
                        x:Name="ShowOnlineButton"
                        Grid.Column="2"
                        Clicked="ShowOnlineButton_Clicked"
                        IsEnabled="False"
                        Text="Show Online" />
                </Grid>

            </StackLayout>
        </resources:ResponsiveFormContainer>
        <!--  Busy indication  -->
        <Grid
            x:Name="BusyIndicator"
            BackgroundColor="#807f7f7f"
            RelativeLayout.HeightConstraint="{ConstraintExpression Type=RelativeToParent,
                                                                   Factor=1,
                                                                   Property=Height}"
            RelativeLayout.WidthConstraint="{ConstraintExpression Type=RelativeToParent,
                                                                  Factor=1,
                                                                  Property=Width}">
            <Grid HorizontalOptions="Center" VerticalOptions="Center">
                <Grid.RowDefinitions>
                    <RowDefinition Height="auto" />
                    <RowDefinition Height="auto" />
                </Grid.RowDefinitions>
                <Label
                    x:Name="BusyText"
                    Margin="10"
                    FontSize="18"
                    TextColor="White" />
                <ProgressBar
                    x:Name="ProgressView"
                    Grid.Row="1"
                    HeightRequest="10"
                    HorizontalOptions="Center"
                    IsEnabled="True"
                    VerticalOptions="Center"
                    WidthRequest="100" />
            </Grid>
        </Grid>
    </RelativeLayout>
</ContentPage>
// Copyright 2019 Esri.
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
// You may obtain a copy of the License at: http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
// language governing permissions and limitations under the License.

using ArcGISRuntime.Samples.Managers;
using Esri.ArcGISRuntime.Data;
using Esri.ArcGISRuntime.Mapping;
using Esri.ArcGISRuntime.Portal;
using Esri.ArcGISRuntime.Tasks.Offline;
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Linq;
using System.Threading.Tasks;
using Xamarin.Forms;

namespace ArcGISRuntimeXamarin.Samples.DownloadPreplannedMap
{
    [ArcGISRuntime.Samples.Shared.Attributes.Sample(
        "Download a preplanned map area",
        "Map",
        "Take a map offline using a preplanned map area",
        "Select a map area to take offline, then use the button to take it offline. Click 'Delete offline areas' to remove any downloaded map areas.")]
    public partial class DownloadPreplannedMap : IDisposable
    {
        // ID of a web map with preplanned map areas.
        private const string PortalItemId = "acc027394bc84c2fb04d1ed317aac674";

        // Folder to store the downloaded mobile map packages.
        private string _offlineDataFolder;

        // Task for taking map areas offline.
        private OfflineMapTask _offlineMapTask;

        // Hold onto the original map.
        private Map _originalMap;

        // Hold list of map areas for use in the UI.
        private readonly List<PreplannedMapArea> _mapAreas = new List<PreplannedMapArea>();

        // Most recently opened map package.
        private MobileMapPackage _mobileMapPackage;

        public DownloadPreplannedMap()
        {
            InitializeComponent();
            Initialize();
        }

        private async void Initialize()
        {
            try
            {
                // The data manager provides a method to get a suitable offline data folder.
                _offlineDataFolder = Path.Combine(DataManager.GetDataFolder(), "SampleData", "DownloadPreplannedMapAreas");

                // If temporary data folder doesn't exists, create it.
                if (!Directory.Exists(_offlineDataFolder))
                {
                    Directory.CreateDirectory(_offlineDataFolder);
                }

                // Create a portal to enable access to the portal item.
                ArcGISPortal portal = await ArcGISPortal.CreateAsync();

                // Create the portal item from the portal item ID.
                PortalItem webMapItem = await PortalItem.CreateAsync(portal, PortalItemId);

                // Show the map.
                _originalMap = new Map(webMapItem);
                MyMapView.Map = _originalMap;

                // Create an offline map task for the web map item.
                _offlineMapTask = await OfflineMapTask.CreateAsync(webMapItem);

                // Find the available preplanned map areas.
                IReadOnlyList<PreplannedMapArea> preplannedAreas = await _offlineMapTask.GetPreplannedMapAreasAsync();

                // Load each item, then add it to the list of areas.
                foreach (PreplannedMapArea area in preplannedAreas)
                {
                    await area.LoadAsync();
                    _mapAreas.Add(area);
                }

                // Show the map areas in the UI.
                AreasList.ItemsSource = _mapAreas;

                // Hide the loading indicator.
                BusyIndicator.IsVisible = false;
            }
            catch (Exception ex)
            {
                // Something unexpected happened, show the error message.
                Debug.WriteLine(ex);
                await Application.Current.MainPage.DisplayAlert("There was an error.", ex.Message, "OK");
            }
        }

        private void ShowOnlineButton_Clicked(object sender, EventArgs e)
        {
            // Show the online map.
            MyMapView.Map = _originalMap;

            // Disable the button.
            ShowOnlineButton.IsEnabled = false;
        }

        private async Task DownloadMapAreaAsync(PreplannedMapArea mapArea)
        {
            // Close the current mobile package.
            _mobileMapPackage?.Close();

            // Set up UI for downloading.
            ProgressView.Progress = 0;
            BusyText.Text = "Downloading map area...";
            BusyIndicator.IsVisible = true;

            // Create folder path where the map package will be downloaded.
            string path = Path.Combine(_offlineDataFolder, mapArea.PortalItem.Title);

            // If the area is already downloaded, open it.
            if (Directory.Exists(path))
            {
                try
                {
                    // Open the offline map package.
                    _mobileMapPackage = await MobileMapPackage.OpenAsync(path);

                    // Open the first map in the package.
                    MyMapView.Map = _mobileMapPackage.Maps.First();

                    // Update the UI.
                    BusyText.Text = string.Empty;
                    BusyIndicator.IsVisible = false;
                    MessageLabel.Text = "Opened offline area.";
                    return;
                }
                catch (Exception e)
                {
                    Debug.WriteLine(e);
                    await Application.Current.MainPage.DisplayAlert("Couldn't open offline area. Proceeding to take area offline.", e.Message, "OK");
                }
            }

            // Create download parameters.
            DownloadPreplannedOfflineMapParameters parameters = await _offlineMapTask.CreateDefaultDownloadPreplannedOfflineMapParametersAsync(mapArea);

            // Set the update mode to not receive updates.
            parameters.UpdateMode = PreplannedUpdateMode.NoUpdates;

            // Create the job.
            DownloadPreplannedOfflineMapJob job = _offlineMapTask.DownloadPreplannedOfflineMap(parameters, path);

            // Set up event to update the progress bar while the job is in progress.
            job.ProgressChanged += OnJobProgressChanged;

            try
            {
                // Download the area.
                DownloadPreplannedOfflineMapResult results = await job.GetResultAsync();

                // Set the current mobile map package.
                _mobileMapPackage = results.MobileMapPackage;

                // Handle possible errors and show them to the user.
                if (results.HasErrors)
                {
                    // Accumulate all layer and table errors into a single message.
                    string errors = "";

                    foreach (KeyValuePair<Layer, Exception> layerError in results.LayerErrors)
                    {
                        errors = $"{errors}\n{layerError.Key.Name} {layerError.Value.Message}";
                    }

                    foreach (KeyValuePair<FeatureTable, Exception> tableError in results.TableErrors)
                    {
                        errors = $"{errors}\n{tableError.Key.TableName} {tableError.Value.Message}";
                    }

                    // Show the message.
                    await Application.Current.MainPage.DisplayAlert("Warning!", errors, "OK");
                }

                // Show the downloaded map.
                MyMapView.Map = results.OfflineMap;

                // Update the UI.
                ShowOnlineButton.IsEnabled = true;
                MessageLabel.Text = "Downloaded preplanned area.";
                DownloadButton.Text = "Display";
            }
            catch (Exception ex)
            {
                // Report any errors.
                Debug.WriteLine(ex);
                await Application.Current.MainPage.DisplayAlert("Downloading map area failed.", ex.Message, "OK");
            }
            finally
            {
                BusyText.Text = string.Empty;
                BusyIndicator.IsVisible = false;
            }
        }

        private void OnJobProgressChanged(object sender, EventArgs e)
        {
            // Because the event is raised on a background thread, the dispatcher must be used to
            // ensure that UI updates happen on the UI thread.
            Device.BeginInvokeOnMainThread(() =>
            {
                // Update the UI with the progress.
                DownloadPreplannedOfflineMapJob downloadJob = sender as DownloadPreplannedOfflineMapJob;
                ProgressView.Progress = downloadJob.Progress / 100.0;
                BusyText.Text = $"Downloading map... {downloadJob.Progress}%";
            });
        }

        private async void OnDownloadMapAreaClicked(object sender, EventArgs e)
        {
            if (AreasList.SelectedItem != null)
            {
                PreplannedMapArea selectedMapArea = AreasList.SelectedItem as PreplannedMapArea;
                await DownloadMapAreaAsync(selectedMapArea);
            }
        }

        private async void OnDeleteAllMapAreasClicked(object sender, EventArgs e)
        {
            try
            {
                // Set up UI for downloading.
                BusyText.Text = "Deleting downloaded map area...";
                BusyIndicator.IsVisible = true;

                // Reset the map.
                MyMapView.Map = _originalMap;

                // Close the current mobile package.
                _mobileMapPackage?.Close();

                // Delete all data from the temporary data folder.
                Directory.Delete(_offlineDataFolder, true);
                Directory.CreateDirectory(_offlineDataFolder);

                // Update the UI.
                MessageLabel.Text = "Deleted downloaded areas.";
                DownloadButton.Text = "Download";
                MessageLabel.Text = "Downloaded preplanned area.";
            }
            catch (Exception ex)
            {
                // Report the error.
                await Application.Current.MainPage.DisplayAlert("Deleting map areas failed.", ex.Message, "OK");
            }
            finally
            {
                BusyIndicator.IsVisible = false;
            }
        }
        private void AreaSelected(object sender, SelectedItemChangedEventArgs e)
        {
            PreplannedMapArea selectedMapArea = e.SelectedItem as PreplannedMapArea;
            string path = Path.Combine(_offlineDataFolder, selectedMapArea.PortalItem.Title);
            if (Directory.Exists(path))
            {
                DownloadButton.Text = "Display";
            }
            else
            {
                DownloadButton.Text = "Download";
            }
        }

        public void Dispose()
        {
            // Close the current mobile package.
            _mobileMapPackage?.Close();
        }
    }
}