Some operations return results directly from asynchronous methods on the task. For more complex or longer running operations, tasks make use of jobs instead.
To use tasks that return results directly:
Create the task by initializing it to use the required data or service.
Some operations require only simple value inputs (for example a simple geocode operation may only require an address string as input).
Others require input parameters (for example, to limit a geocode operation to a specific country).
Call the async operation method, passing in the inputs you defined.
Use the results from the operation as required, for example to display geocode results on a map.
The following code creates a LocatorTask to geocode an address entered by the user. The best match is used to create a graphic to display on the map.
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
// Create a new LocatorTask from a geocode service endpointvar locatorUri = new Uri("https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer");
LocatorTask onlineLocator = new LocatorTask(locatorUri);
// If the address text box is not empty, run the geocode taskif (!string.IsNullOrEmpty(AddressTextBox.Text.Trim()))
{
// Pass the address to the GeocodeAsync method and get the results IReadOnlyList<GeocodeResult> matches = await onlineLocator.GeocodeAsync(AddressTextBox.Text);
// Get the first match (one with the highest score) GeocodeResult bestMatch = matches[0];
// Use geometry and attributes from the match (and a symbol created earlier) to create a new graphic Graphic fromGraphic = new Graphic(bestMatch.DisplayLocation, bestMatch.Attributes);
// Add the graphic to an existing graphics overlay in the map view MyMapView.GraphicsOverlays[0].Graphics.Add(fromGraphic);
}
Define input parameters
Tasks offer numerous options that allow you to tailor the operation to your requirements. For example, when geocoding you can restrict your search to a specific area, country, category of place, and/or number of results. When an author publishes a service or packages a resource, they can choose default values for these options that suit the specific data or the most common use case for the service.
To use these default parameter values, tasks provide helper methods that create parameter objects initialized with service-specific values. You can then make any changes to the parameter values before passing them to an operation. Creating these default parameter objects is useful for operations with many options, such as tracing a utility network.
The following example gets the default parameters for a route task, then explicitly sets values for some properties.
Some parameters objects have constructors that you can use if you know the values of all the input parameters you want to use. This can be more efficient when parameter settings are simple.
For example, the following code creates a new GeocodeParameters that restricts the search country to France and limits the results (matches) to a maximum of 5.
Many tasks can work either online by using services, or offline by using local data and resources. For example, you can geocode an address by using the default Esri geocoding service, your own geocoding service, a locator file (.loz), or a mobile map package (.mmpk).
Some tasks expose operations that have multiple stages (like preparing and downloading a geodatabase), and can generate multiple progress messages (such as percentage complete). These types of tasks are always bound to ArcGIS Server (or Local Server for platforms that support it). An example is GeodatabaseSyncTask.GenerateGeodatabase.
Instead of returning results directly, these tasks make use of jobs to monitor status, return progress updates, and return their results. Each Job<T> represents a specific operation of a task. Jobs are useful for longer-running operations, because they can also be paused, resumed, and canceled. Your app can support a user action or host OS terminating a running job object, and then recreate and resume the job later.
To use operations like these:
Create the task by initializing it to use the required data or service.
Call the async operation method to get a job, passing in the input parameters you defined.
Start the job.
Optionally, listen for changes to the job status and check the job messages, for example to update a UI and report progress to the user.
Listen for the job completion and get the results from the operation. Check for errors in the job, and if successful, use the results.
The following example creates a task to synchronize local edits to a service. The StatusChanged event is handled to report success or failure of the job.
Calling Job<T>.Status retrieves the current JobStatus in the job's workflow. Jobs periodically fire a changed event as they are running, usually with decreasingly frequency as a job progresses. More than one JobMessage may appear in a change event. The job complete listener is called as soon as the job finishes. Whether successful or not, jobs cannot be restarted.
Report job progress
A job represents an asynchronously running operation that might take some time to finish. As described previously, you can monitor changes to job status for notification when a job has completed, failed, or been canceled, but what about the time in-between? Users may become frustrated waiting for a long job to complete without getting feedback on its progress. Fortunately, jobs provide a mechanism for reporting the current progress (percentage complete) for the running operation they represent.
As a job runs it raises a Job.ProgressChanged() event. You can get the current progress of the job at any point from the Job<T>.Progress property, an integer representing the percentage of the operation that has been completed. This allows your app to provide more specific information about the status of a running job using UI elements like progress bars.
The following example updates a label in the UI to show the percentage complete for the job.
Jobs are designed to handle a user exiting an app while the job is running or having the app terminated by the host operating system. Jobs also provide a mechanism for explicitly pausing or canceling the operation.
Cancel a job
Sometimes, the results of a job are no longer required. For example, a user could change their mind about the area of a tile cache they want to download and want to cancel the job and start over.
Calling Job<T>.CancelAsync() changes JobStatus to canceling, cancels the Job<T>, and waits for any asynchronous, server-side operations to be canceled. After all cancelation tasks complete (including any server-side tasks), JobStatus changes to failed and Job<T>.CancelAsync() returns true. If one or more jobs cannot be canceled, Job<T>.CancelAsync() returns false.
You should always cancel unneeded jobs (for example when exiting your app) to avoid placing unnecessary load on the server.
The following example shows code you would add to the StatusChanged handler to check for a System.OperationCanceledException when the job fails. Canceling the job might require additional cleanup of incomplete data or other code on the client.
Jobs can be long-running operations, so there is no guarantee that they will be completed while the app is running. You can pause a job explicitly using Job<T>.Progress. For example, when an app is backgrounded and does not have permissions for background operation. Pausing may also be useful if a user wishes to temporarily stop network access for any reason.
Job changed messages will not be received for a paused job. Pausing a job does not stop any server-side processes from executing. While a job is paused, outstanding requests can complete. Therefore, when resuming a job it may have a different state than when it was paused.
You can serialize a job to JSON to persist it if your app is backgrounded or the process is otherwise terminated. When you deserialize it again the JobStatus will be in the paused state regardless of its state when serialized and should be restarted to resume listening for completion. The job changed listener is a good place to update the job JSON for storage by your app.
The following example shows code to save the state of a job in its StatusChanged event handler. Additional code could be used to save this text (JSON) as a local file for deserialization later.
The job can be deserialized from a JSON string and resumed if necessary. You must rewire event handlers to monitor the job status (StatusChanged), for example), as shown in the following example.
Additionally, jobs using services are designed to handle situations where network connectivity is temporarily lost without needing to be immediately paused. A started job will ignore errors such as network errors for a period of up to 10 minutes. If errors continue for longer, the job will fail and the message will indicate the loss of network connection.
To handle inconsistent connectivity, you can serialize and pause a job when your app loses connectivity for a few minutes to avoid job failure (as failed jobs cannot be restarted). The job can then be deserialized and resumed when connectivity returns.