Download an offline map (ahead of time)

Your ArcGIS Runtime app can use a web map while it has no internet connection by first downloading an offline map from the web map. As soon as the offline map is downloaded, a mobile worker can disconnect their device and work with the map offline.

The owner of a web map can define a specific geographic area as an offline map area. This area of the web map will be packaged as an offline map ahead of time. These offline maps are well-suited to field apps used by mobile workers and scale well to large workforces.

The main advantages of ahead-of-time offline maps are:

  • The map author can organize a set of specific map areas for mobile workers to use.
  • Users can download the offline maps quickly and with minimal interaction. Since they are generated before they are needed, their download time is comparable to any other files and resources.
  • Many users can download the same offline map.

The steps to use ahead-of-time offline maps are:

  1. Create offline map areas for your web map.
  2. Get a list of offline map areas in your app.
  3. Create the parameters
  4. Create the job
  5. Run the job

Create offline map areas

To create offline map areas, you must use web maps created with ArcGIS Online or ArcGIS Enterprise 10.6.1 or later. You must ensure that all services used in the web map are enabled for offline use.

You can create map areas manually using ArcGIS Online or ArcGIS Enterprise. You can also create them programmatically, using Python scripts or the ArcGIS REST APIs, as described below.

ArcGIS Online or ArcGIS Enterprise

Use ArcGIS Online or ArcGIS Enterprise to create, edit, and manage offline map areas for your web maps. See the topics below for details.

Python scripts

Use ArcGIS API for Python to write python scripts to create offline map areas and generate their associated data packages. See the managing map areas Python topic for details.

  • Update the offline map area of an offline map and any of its packages that have been deleted or contain more recent data.
  • Delete an individual data package.
  • Delete an offline map area along with its associated packages.
  • Inspect any of the offline maps's packages.
  • List the web map's current map areas.

ArcGIS Rest APIs

Use the ArcGIS REST APIs if you need even more control when creating your offline map areas. There are two stages to this process:

  1. Create an offline map area: Run the Create Map Area task with a bookmark or geographical extent to define the area of interest for a web map that's enabled for offline use. The task generates a new portal item of type MapArea. Only the owner of the web map and organization administrators can run this task.
  2. Create the data defined by the map area: Run the Setup Map Area task with the map area portal item ID. This creates a set of data files such as tile packages, vector tile packages, and SQLite geodatabases. For good data management, you should organize these files into folders. Only the owner of the map area portal item owner and organization administrators can run this task.

Define updates

In addition to creating the offline map area, you can also define how users receive updates to the data used in the offline map. Updates can come from the synchronization of the offline map's geodatabases with their online services or by applying update packages to the geodatabases.

  • Synchronization allows you to download updates from the online service and upload edits from the offline map when connectivity is available. You can configure the synchronization direction control how edits are synchronized download only, upload only, or bi-directional.
  • The update packages workflow provides feature service updates in a file that is created according to a packaging schedule that you can specify when you create the offline map area. ArcGIS Runtime API can download the required files and apply their updates to the offline map's geodatabases. These files are relatively small so they are quick to download and fast to apply. This provides a scalable solution for receiving updates to read-only geodatabases and is useful when you need to provide many clients with an up-to-date read-only copy of the feature data. If your geodatabase supports creating new features, then clients may also upload new features to the map as part of the update packages workflow.

Download the offline map

Once you have created an offline map area, the offline map publication will be initiated. The following section describes how you build an ArcGIS Runtime app to download the offline map.

Get a list of offline map areas

Each web map can have up to sixteen offline map areas defined, which are available to download as offline maps. Your app needs to determine which map area to download. You can do this by allowing the mobile worker to select a map area from a map view or from a list of map areas. Alternatively, the app logic could select a map area for the mobile worker.

Follow these steps to retrieve all of the map areas:

  1. Instantiate the offline map task by passing either a map (created from a web map) or a web map's portal item to the OfflineMapTask constructor.

    Use dark colors for code blocksCopy
                                                                                                                                                                                                                                                                                             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    271
    272
    273
    274
    275
    276
    277
    278
    279
    280
    281
    // Get the ArcGIS Online portal.
    var agol = await ArcGISPortal.CreateAsync();
    
    // Get a web map item using its ID.
    PortalItem webmapItem = await PortalItem.CreateAsync(agol, "acc027394bc84c2fb04d1ed317aac674");
    
    // Create a map from the web map item.
    Map onlineMap = new Map(webmapItem);
    
    // Create an OfflineMapTask from the map ...
    _takeMapOfflineTask = await OfflineMapTask.CreateAsync(onlineMap);
    // ... or a web map portal item.
    //_takeMapOfflineTask = await OfflineMapTask.CreateAsync(webmapItem);
    
  2. Retrieve a list of the offline map areas from the web map using the GetPreplannedMapAreasAsync() method on the OfflineMapTask.

  3. Load each PreplannedMapArea.

  4. Show the map area titles and thumbnails in a list, display the map area extents, or select a map area by name.

    Use dark colors for code blocksCopy
                                                                                                                                                                                                                                                                                             
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    271
    272
    273
    274
    275
    276
    277
    278
    279
    280
    281
    // Find the available offline (preplanned) map areas.
    IReadOnlyList<PreplannedMapArea> preplannedAreas = await _takeMapOfflineTask.GetPreplannedMapAreasAsync();
    
    // Loop through all map areas.
    foreach (var mapArea in preplannedAreas)
    {
        // Load the offline map area so property values can be read.
        await mapArea.LoadAsync();
    
        // Add each area to a list in the UI.
        AreasList.Items.Add(mapArea);
    }
    

Create the parameters

To download an offline map to your device, you should provide a set of DownloadPreplannedOfflineMapParameters. To obtain a set of default parameters pass in the map area to OfflineMapTask.CreateDefaultDownloadPreplannedOfflineMapParametersAsync(). The value of these default parameters will match the advanced offline settings configured by the web map author (discussed in Take web maps offline).

Use dark colors for code blocksCopy
                                                                                                                                                                                                                                                                                         
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
// Get the default parameters (provide a map area).
var defaultDownloadParams =
    await _takeMapOfflineTask.CreateDefaultDownloadPreplannedOfflineMapParametersAsync(selectedMapArea);

// Update some of the parameter values.
defaultDownloadParams.ContinueOnErrors = false;
defaultDownloadParams.IncludeBasemap = true;
defaultDownloadParams.ReferenceBasemapDirectory = _offlineDataFolder;

For more information see Advanced parameters.

Create the job

Create the DownloadPreplannedOfflineMapJob using OfflineMapTask.DownloadPreplannedOfflineMap() and provide both the DownloadPreplannedOfflineMapParameters and the download directory.

Use dark colors for code blocksCopy
                                                                                                                                                                                                                                                                                         
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
// Create folder path where the map package will be downloaded.
string packagePath = Path.Combine(_offlineDataFolder, selectedMapArea.PortalItem.Title);

var preplannedMapJob = _takeMapOfflineTask.DownloadPreplannedOfflineMap
                                (defaultDownloadParams, packagePath);
// Handle ProgressChanged to update the UI (progress bar, eg) while the job is running.
preplannedMapJob.ProgressChanged += OnJobProgressChanged;

Run the job

To download the offline map to your device, start the DownloadPreplannedOfflineMapJob. Upon completion, the job returns an instance of the DownloadPreplannedOfflineMapResult.

To ensure the job was successful, check the following:

  • If at least one table or layer failed to be downloaded successfully, HasErrors in DownloadPreplannedOfflineMapResult will be true. In that case, you should examine the LayerErrors and TableErrors dictionaries in that result object to identify the problem.
  • The job's Parameters property is a reference to the DownloadPreplannedOfflineMapParameters with which the job was created. If ContinueOnErrors in that parameters object is false, then the job will be terminated immediately if a single layer or table fails to be taken offline.
  • If the offline map publishing has failed, or is still in progress, you will not be able to download the offline map packages. Before running this job, you can check whether the publishing process is complete, has failed, or is still in progress by examining the PackingStatus of the PreplannedMapArea. (Note: The download preplanned offline map job has a Parameters property that returns the job's DownloadPreplannedOfflineMapParameters, which contain PreplannedMapArea.)

If you want to display the map immediately, then use DownloadPreplannedOfflineMapResult.OfflineMap.

Use dark colors for code blocksCopy
                                                                                                                                                                                                                                                                                         
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
// Generate the offline map and download it.
var preplannedMapResult = await preplannedMapJob.GetResultAsync();
if (!preplannedMapResult.HasErrors)
{
    // Job completed successfully and all content was generated.
    _mobileMapPackage = preplannedMapResult.MobileMapPackage;
    Debug.WriteLine("Map " + _mobileMapPackage.Item.Title +
        " was saved to " + _mobileMapPackage.Path);
    // Show the offline map in a MapView.
    MyMapView.Map = preplannedMapResult.OfflineMap;
}
else
{
    // Job is finished but one or more layers or tables had errors.
    foreach (var layerError in preplannedMapResult.LayerErrors)
    {
        // Report layer errors ...
    }
    foreach (var tableError in preplannedMapResult.TableErrors)
    {
        // Report table errors ...
    }
}

Offline maps created by the ahead-of-time workflow are stored in an unpacked mobile map package. When your app goes into the field, you will need to open the map directly from the mobile map package's download directory stored on your device.

Advanced parameters

Once you have the default parameters you can customize them in the following ways:

Continue if a table or layer fails

The DownloadPreplannedOfflineMapJob downloads a map's tables and layers for offline use. By default this job will continue, even if one table or layer has failed. Failures could be due to an intermittent network connection, loss of the service, or an unsupported layer type. The approach ensures that you can take a map offline but you may have some data missing.

To ensure that the offline map contains all of its layers and tables, you can request that the job is stopped if any layer or table fails to download. To do this, set ContinueOnErrors in DownloadPreplannedOfflineMapParameters to false.

Which basemap should the map use?

The author of the web map can define whether the map uses:

  • The basemap defined by the web map.

    This is the default situation and ensures that a tile package is downloaded as part of the mobile map package.

  • A tile package that is already on the device.

    The tile package must be downloaded or copied onto the device and can be located using an actual file path on the device or a path that is relative to the mobile map package. You must ensure that the tile package covers the areas required by your offline map(s). The benefits of this option are that the mobile map package file will be smaller, the download time may be faster, and you can use the tile package in many different maps and apps.

    To use the tile package on your device, employ certain properties in DownloadPreplannedOfflineMapParameters:

    • Set ReferenceBasemapDirectory to the directory which contains the tile package.
    • Confirm that the tile package file, ReferenceBasemapFilename, exists on the device.

    Only then should you run the DownloadPreplannedOfflineMapJob. This job will add the tile package, as a basemap, to the offline map.

  • No basemap

    If you only want to take the operational layers offline, you can programmatically exclude the basemap by setting IncludeBasemap in DownloadPreplannedOfflineMapParameters to false. In that case, the DownloadPreplannedOfflineMapJob will not download layers included as part of the map's basemap. (For more information, see Basemap in Map or its base class GeoModel.) This task will not use the local tile package, even if you have specified one.

Manage the update mode

Your local geodatabase can receive updates from its online feature services. The DownloadPreplannedOfflineMapParameters.UpdateMode parameter indicates how this operates via one of four possible PreplannedUpdateMode enum values.

  • Synchronize with the feature services.

    This flexible option allows you to edit the local geodatabase and synchronize it with its online feature services. This enum value is SyncWithFeatureServices.

  • Download update packages.

    The web map author can specify that update packages are generated for the feature services in the map (discussed in Define updates). This option means that the local geodatabase can only receive updates via the update packages. You cannot create, update, or delete features in the local geodatabase. This enum value is DownloadScheduledUpdates.

  • Download update packages and upload new features.

    The web map author can specify that update packages are generated and that the map supports the creation of new features. This option means that, while the local geodatabase can receive updates from its feature services via the update packages, you can also create new features that can be uploaded to the feature services. This enum value is DownloadScheduledUpdatesAndUploadNewFeatures.

  • No updates from the feature services.

    If you want to avoid receiving any updates to the local geodatabase, use the enum value NoUpdates. This option disables data synchronization with the map’s geodatabases and prevents the corresponding feature services from creating synchronization replicas. The benefits are that the burden on the feature server is reduced and you will not need to unregister geodatabases when they are no longer required.

Next steps

Once you have obtained the offline map follow these steps:

  1. Display and interact with the maps, layers and data offline. Explore and edit the feature data, if necessary.
  2. Update an offline map by synchronizing your edits with the online services, when connectivity is restored.
  3. Finish using an offline map by unregistering any geodatabases and fully releasing all locks on the mobile map package.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.