How to cancel a promise (HTML)

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

You sometimes need to stop an asynchronous operation that is underway, for example when the user has canceled the action that started the operation, or has navigated away from the page that contained the UI that started the operation. You can do this by canceling the promise that represents the asynchronous operation.

Instructions

Step 1:

The code in the following example allows you to click a Start button to begin an asynchronous operation to download a web page, and to click a Cancel button to cancel the operation.

1. Create a blank Windows Runtime app named TestCancel.

2. Open "default.html" and add a DIV element to that has an ID of xhrDiv.

   <div id="xhrDiv"></div>
   

3. Also in "default.html", add two BUTTON elements and give them IDs of startBtn and cancelBtn.

   <button id="startBtn">Start</button>
   <button id="cancelBtn">Cancel</button>
   

4. Open "default.js" (/js/default.js). Add the following variable assignments immediately after the use strict directive.

   var xhrDiv;
   var xhrPromise = null;
   

5. Also in "default.js", in the event handler for app.onactivated, add the following code.

   xhrDiv = document.getElementById("xhrDiv");
   
   var startBtn = document.getElementById("startBtn");
   var cancelBtn = document.getElementById("cancelBtn");
   
   startBtn.addEventListener("click", startHandler);
   cancelBtn.addEventListener("click", cancelHandler);
   

6. Add the startHandler method. The start handler is responsible for starting the download. To do so, you call WinJS.xhr, which returns a promise. In the then clause of the promise, you add a completed function and an error function. The error function is called when the operation is canceled, as well as for any errors that may occur during the download operation. In the case of a canceled promise, the result parameter of the error function is an error. If the XmlHttpRequest fails, the result parameter is the XmlHttpRequest.

   The URL you choose should be a page that takes some time to download, since in a later step you must click the Cancel button before the download finishes.

   function startHandler() {
       xhrDiv.textContent = "";
       xhrDiv.style.backgroundColor = "#000000";
       xhrPromise = WinJS.xhr({ url: encodeURI("<your choice of URL>") })
           .then(function complete(result) {
               xhrDiv.textContent = "Downloaded the page";
               xhrDiv.style.backgroundColor = "#00FF00";
           }, 
           function error(result) {
               if (result.name == "Canceled") {
                   xhrDiv.textContent = result.message;
                   xhrDiv.style.backgroundColor = "#FF0000";
               }
               else {
                   xhrDiv.textContent = "other error";
                   xhrDiv.style.backgroundColor = "#FF00FF";
               } 
           });
   }
   

7. Add the cancelHandler method. This handler just cancels the promise.

   function cancelHandler(ev) {
       if (xhrPromise != null) {
           xhrPromise.cancel();
       }
   }
   

8. Start the app in debug mode. You should see the Start button and the Cancel button. If you click Start, the HTTP request is started asynchronously, and if it succeeds you should see the DIV turn green and display the words "Downloaded the page". If you click Start and then Cancel (you have to do this quickly), you should see the DIV turn red and display the words "Canceled".