Connecting to web services (HTML)
These topics demonstrate various methods to connect to a web service in a Windows Runtime app. The recommended method is to use Windows.Web.Http.HttpClient, a new Windows Runtime class available for all languages. This is the most full-featured and powerful API an app can use to access a web service.
Classes in the Windows.Web.Http namespace provide a programming interface for modern HTTP client apps. The Windows.Web.Http namespace and the related Windows.Web.Http.Headers and Windows.Web.Http.Filters namespaces provide HTTP client components that allow users to make HTTP requests and receive HTTP responses from modern web services over HTTP.
For basic HTTP request operations, the Windows.Web.Http.HttpClient has a simple interface to handle the most common tasks and provides sensible defaults for authentication (AUTH) that apply to most scenarios. For more complex HTTP operations, many additional capabilities are available.
Unlike XMLHttpRequest, which allows you to specify whether the request should be made asynchronously, WinJS.xhr is always asynchronous. WinJS.xhr returns a WinJS.Promise, so that you can handle completed requests, errors, and in-progress requests by using the then or done methods.
Warning It is now possible to use XMLHttpRequest to transfer extremely large objects, such as Blob objects and FormData objects, which might take a long time to complete. Windows.Web.Http.HttpClient can also be used to send or receive extremely large objects including streams. Because an app can be terminated at any time, you should consider using the background transfer in the Windows.Networking.BackgroundTransfer namespace for these operations. For more info about uploading and downloading large content, see How to Upload a file and Transferring data in the background.
|Windows 8.1, Windows Phone 8.1, Windows Server 2012 R2||
This is the recommended method to connect to a HTTP server to send and receive data.
|WinJS.xhr||Windows 8, Windows Phone 8.1, Windows Server 2012,||
On Windows 8 and Windows Server 2012, this was the recommended method when XMLHttpRequest was not adequate.
For more information on how to connect to a web service for apps written in C++/XAML and apps using the .NET Framework 4.5 and written in C# or Visual Basic, see Connecting to web services (XAML).
With the "ms-https-connections-only" meta element value you can prevent your app from using HTTP connections for navigation or other non-media web content retrievals. When you set this meta element's content attribute to "true", HTTP navigation and non-media web content retrievals will fail.
WinJS.xhr provides an easy way to download web content in your app. This topic shows how to download a file using WinJS.xhr, handle any errors, and report on the progress of the download. It also shows how to download different types of content.
You can upload and download binary data when you use WinJS.xhr (which wraps XMLHttpRequest). This example shows how to upload a bitmap from your Pictures. The Windows Runtime method that is used to open the bitmap file returns an IRandomAccessStream, so you must use MSApp.createBlobFromRandomAccessStream to convert it to a Blob.
Warning You can now use XMLHttpRequest to upload or download objects that are larger than a few MB, such as Blob objects and FormData objects, which may take a long time to complete. Because apps can be terminated at any time, you should consider using the Windows Runtime background transfer APIs for these operations. For more information about uploading and downloading content, see How to upload a file and How to download a file. For a general discussion of background transfer, see Transferring data in the background.
When you request Web resources by using WinJS.xhr, the response might be cached, which means that later requests will return the version of the resource that already exists on the client computer rather than resending the request. However, you can add an HTTP header that ensures that the request is sent again, even if it has already been cached.
When you use XMLHttpRequest, you can set time-out values directly, but you cannot do this when you use Windows.Web.Http.HttpClient or WinJS.xhr. However, there is a way to set time-outs on WinJS.Promise objects. By calling WinJS.Promise.timeout, you ensure that the request is canceled if it has not completed within the specified time.
A mashup is a web application that uses data from two or more sources to create something new. This example shows you how to use XMLHttpRequest (XHR) to retrieve and display a remote Really Simple Syndication (RSS) feed.
- Other resources
- App capability declarations
- Handling exceptions in network apps
- How to configure network isolation capabilities
- How to enable loopback and debug network isolation
- HttpClient Sample
- Integrating content and controls from web services sample
- Using a Blob to save and load content sample
- Web authentication sample
- XHR, handling navigation errors, and URL schemes sample