When you work with the RouteTask, you'll follow the general pattern of 1) creating the task, 2) configuring the parameters, and 3) solving the route. You must also specify what to do with the results and handle any errors returned by the task.

Creating the route task

When you create an instance of RouteTask, you provide a URL to a network layer resource. This is exposed through the REST endpoint of an ArcGIS Server network analysis service. If you're not certain how to construct the URL, you can use the Services Directory to help you. In the code snippet below, MyMapDoc is the network analysis service and MyRoute is the network layer resource.

routeTask = new ESRI.ArcGIS.VE.RouteTask("http://myServer/ArcGIS/rest/services/MyMapDoc/NAServer/MyRoute");

Configuring the route parameters

In order to get the results you want from the route task, you need to specify the details of your routing problem such as stop locations, barrier locations, the impedance attribute, etc. You do this using ESRI.ArcGIS.VE.RouteParameters.

routeParams = new ESRI.ArcGIS.VE.RouteParameters();

The example below shows how you'd use RouteParameters to define two stops for a route:

//define 2 stops by coordinate pairs
var stop1 = new ESRI.ArcGIS.VE.GraphicFeature();
var stop2 = new ESRI.ArcGIS.VE.GraphicFeature();
stop1.Geometry = { "x": -117.21, "y": 34.065 };
stop2.Geometry = { "x": -117.185, "y": 34.05 };

stopSet = new ESRI.ArcGIS.VE.FeatureSet();
stopSet.Features = new Array();

stopSet.Features.push(stop1);
stopSet.Features.push(stop2);
routeParams.Stops = stopSet;

The route parameters also designate whether driving directions are returned, whether stops are visited in the order they were added, and whether the task fails if one stop is unreachable. For a complete description of each parameter, see the RouteParameters entry in the API reference.

In the above example, the stops were specified using x,y geometries. Optionally, you can specify stops and barriers as network locations. Network locations have their positions recorded relative to other segments on the network. Using network locations can result in faster route solving. See Network analysis classes in the ArcGIS Desktop Help to learn about the four network location fields: SourceID, SourceOID, PosAlong, and SideOfEdge.

You can solve multiple routes at once by adding route names to each of your stops. The code below sets up two routes: Route A and Route B.

stop1.Attributes = { "Name": "A", "RouteName": "Route A" };
stop2.Attributes = { "Name": "B", "RouteName": "Route A" };  
stop3.Attributes = { "Name": "C", "RouteName": "Route B" };
stop4.Attributes = { "Name": "D", "RouteName": "Route B" };

When solving multiple routes in this way, you'll get an array of RouteResult objects. You can iterate through this array and add the routes to the map.

Solving the route

Once you've created the route task and configured its parameters, you can call RouteTask.Solve() to solve the route.

routeTask.Solve(routeParams, responseHandler);

The arguments for this method are the route parameters and a handler function that works with the route results. This handler function might draw the result geometry on the map, list the driving directions, or report the route distance and driving time.