Como conectar-se a um servidor HTTP usando Windows.Web.Http (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Envie uma solicitação GET a um serviço Web e recupere a resposta usando a classe Windows.Web.Http.HttpClient no namespace Windows.Web.Http.

[Obtenha a amostra de HTTPClient agora.]

As classes no namespace Windows.Web.Http fornecem uma interface de programação para aplicativos cliente HTTP modernos. O namespace Windows.Web.Http e os namespaces Windows.Web.Http.Headers e Windows.Web.Http.Filters relacionados fornecem componentes de cliente HTTP que permitem que os usuários façam solicitações e recebam respostas HTTP de serviços Web modernos por HTTP.

O Windows 8.1 apresenta o Windows.Web.Http, o namespace de Tempo de Execução do Windows a ser usado para aplicativos do Windows que se conectam a serviços Web HTTP e REST (Representational State Transfer). Essa nova API dá suporte a todos os recursos em todas as linguagens compatíveis e substitui a API HTTP lançada originalmente para o Windows 8 .

Essa nova API substitui o uso de três APIs diferentes com recursos distintos que antes eram necessários para a projeção de cada linguagem no Windows 8.

WinJS.xhr para JavaScript
System.Net.Http.HttpClient No namespace System.Net.Http para C# e VB.Observação Sem suporte no Windows Phone.
XML HTTP Extended Request (IXMLHTTPRequest2) para C++

Para operações básicas de solicitação, a nova API tem uma interface simples para tratar as tarefas mais comuns e fornece padrões adequados de autenticação (AUTH) que se aplicam à maioria dos cenários. Para operações HTTP mais complexas, há recursos adicionais incluídos.

Métodos para verbos comuns (DELETE, GET, PUT e POST)
Suporte para configurações e padrões de autenticação comuns
Acesso a detalhes do protocolo SSL no transporte
Capacidade de incluir filtros personalizados em aplicativos avançados
Capacidade de obter, definir e excluir cookies
Informações de progresso da Solicitação HTTP disponíveis em métodos assíncronos

A classe Windows.Web.Http.HttpClient é usada para enviar e receber solicitações básicas por HTTP. Ela fornece a classe principal para enviar solicitações HTTP e receber respostas HTTP de um recurso identificado por um URI. Essa classe pode ser usada para enviar uma solicitação GET, PUT, POST, DELETE e outras para um serviço Web. Cada uma dessas solicitações é enviada como uma operação assíncrona.

A classe Windows.Web.Http.HttpRequestMessage representa uma mensagem de solicitação HTTP enviada por Windows.Web.Http.HttpClient. A classe Windows.Web.Http.HttpResponseMessage representa uma mensagem de resposta HTTP recebida de uma solicitação HTTP. As mensagens HTTP são definidas em RFC 2616 pela IETF.

O namespace Windows.Web.Http fornece várias classes diferentes que representam o conteúdo HTTP (o corpo da entidade HTTP e os cabeçalhos de conteúdo, inclusive cookies) associado a uma solicitação ou a uma resposta HTTP. Essas classes diferentes permitem que o conteúdo use um buffer, uma cadeia de caracteres, um fluxo, bem como dados de nome/valor codificados com o tipo MIME de aplicativo/x-www-formulário-urlcodificada, tipo MIME de partes múltiplas/* e tipo MIME de partes múltiplas/dados de formulário. Além disso, é possível definir conteúdo personalizado.

Neste exemplo, a classe HttpStringContent é usada para representar a resposta HTTP como uma cadeia de caracteres.

O namespace Windows.Web.Http.Headers dá suporte à criação de cabeçalhos e cookies HTTP, que são, então, associados como propriedades a objetos HttpRequestMessage e HttpResponseMessage.

Pré-requisitos

Os exemplos a seguir neste tópico são fornecidos em JavaScript e HTML. É necessário ter conhecimentos básicos em solicitações HTTP, conforme detalhado em RFC 2616.

Também é possível fazer solicitações HTTP em um aplicativo em JavaScript e HTML com WinJS.xhr e XMLHttpRequest. Para obter mais informações, consulte Conectando a um serviço Web (aplicativos do Tempo de Execução do Windows em JavaScript).

Instruções

Etapa 1: Criar um novo projeto

Abra o Microsoft Visual Studio 2013 e selecione Novo Projeto no menu Arquivo.
Na lista de modelos, selecione JavaScript.
Na seção, escolha Store apps.
Na seção, selecione Universal Apps, Windows apps ou Windows Phone apps (dependendo da plataforma que você deseja) e selecione Aplicativo em Branco.
Nomeie o aplicativo HttpClientGet e clique em OK.

Etapa 2: Definir recursos para permitir acesso à rede

Você deve definir recursos de rede para seu aplicativo a fim de permitir o acesso a uma rede corporativa ou doméstica privada e à Internet. Para este aplicativo, você deve habilitar os recursos de rede, pois o cliente está conectando-se a serviços Web.

Para que um aplicativo usando Windows.Web.Http.HttpClient se conecte a um serviço Web em um computador diferente, ele precisa ter recursos de rede definidos. Se o aplicativo precisa poder se conectar como um cliente a serviços Web na Internet, a funcionalidade Internet (Cliente) é necessária. Se o aplicativo precisa poder se conectar como um cliente a serviços Web em uma rede doméstica ou corporativa, a funcionalidade Redes Privadas (Cliente e Servidor) é necessária.

Observação No Windows Phone, existe apenas um recurso de rede Internet (Cliente e Servidor) que habilita todos os acessos de redes para o aplicativo.

Se o serviço Web estiver em execução no mesmo computador que o aplicativo, será necessário acesso loopback. Os aplicativos desenvolvidos e executados no Visual Studio 2013 serão registrados automaticamente como isentos das restrições de loopback. Para saber mais, consulte Como habilitar o loopback e depurar o isolamento da rede.

Para saber mais sobre o acesso à rede, veja Como configurar recursos de rede.

Estas etapas são necessárias para definir os recursos de rede para um aplicativo antes de ele ser implantado ou se ele acessa um serviço Web na Internet ou em uma rede privada ou corporativa.

Use o Visual Studio 2013 para abrir o arquivo package.appxmanifest.
Selecione a guia Recursos.
Para compilar a versão Windows do exemplo, selecione os recursos Internet (Cliente) e Redes Privadas (Cliente e Servidor).

Para compilar a versão Windows Phone do exemplo, selecione a funcionalidade Internet (Cliente e Servidor).
Salve e feche o arquivo de manifesto.

Etapa 3: Adicionar a interface do usuário HTML

Nesta seção, definimos o layout do aplicativo em HTML para especificar o tamanho aproximado e a posição de cada objeto no aplicativo. Completamos a interface do usuário do aplicativo adicionando controles e conteúdo para exibir dados.

Esta amostra usa elementos simples de interface do usuário HTML que incluem:

Um controle com class usado para um rótulo de texto, o campo de entrada para o endereço de URI de entrada, um button usado para iniciar a solicitação assíncrona.
Um controle com um class contendo um rótulo de texto e um campo de texto para exibir o status atual. É aí que as mensagens de status e erro são exibidas. Esse controle também contém uma class onde a saída recebida do serviço Web é exibida. Nesta amostra, o resultado da operação HTTP GET é exibido como texto sem formatação contendo marcação HTML.

Abra a pasta js, abra o arquivo default.js existente e adicione os elementos de interface do usuário a seguir a esse arquivo.

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title>HttpClientGet</title>

    <!-- WinJS references - Windows -->
    <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />
    <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
    <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>

    <!-- WinJS references - Phone -->
    <link href="/css/ui-themed.css" rel="stylesheet" />
    <script src="//Microsoft.Phone.WinJS.2.1/js/base.js"></script>
    <script src="//Microsoft.Phone.WinJS.2.1/js/ui.js"></script>

    <!-- HttpClientGet references -->
    <link href="/css/default.css" rel="stylesheet" />
    <script src="/js/default.js"></script>
    <script src="/js/mainpage.js"></script>
</head>

<body>
    <div data-win-control="SampleInput">
        <p> Download the contents of a page and display it. </p>
        <p class="clear">
            <label for="inputAddress">URI Address:</label>
            <input type="text" id="inputAddress" value="https://www.contoso.com" />
        </p>
        <p>
            <button id="startButton">Start</button>
        </p>
    </div>
    <div data-win-control="SampleOutput">
        <p class="clear">
            <label for="statusText">Status:</label>
            <input type="text" id="statusText" value="" />
        </p>
        <textarea id="outputView"></textarea>
    </div>
</body>
</html>

Etapa 4: Criar o HttpClient

Primeiro, crie o objeto Windows.Web.Http.HttpClient e adicione um cabeçalho de agente do usuário.

Por padrão, nenhum cabeçalho de agente do usuário é enviado com a solicitação HTTP para o serviço Web pelo objeto HttpClient. Alguns servidores HTTP, incluindo alguns servidores Web da Microsoft, exigem que um cabeçalho de agente do usuário seja incluído com a solicitação HTTP enviada do cliente. O servidor HTTP retorna um erro se nenhum cabeçalho está presente. É necessário adicionar um cabeçalho de agente do usuário usando classes no namespace Windows.Web.Http.Headers. Adicionamos esse cabeçalho à propriedade HttpClient.DefaultRequestHeaders para evitar esses erros.

Abra a pasta js, adicione um novo arquivo mainpage.js e adicione o código a seguir ao arquivo.

(function () {
    "use strict";

    var httpClient;
    var httpPromise;

    var page = WinJS.UI.Pages.define("/html/mainpage.html", {
        ready: function (element, options) {
            document.getElementById("startButton").addEventListener("click", start, false);

            httpClient = new Windows.Web.Http.HttpClient();

            // Add a user-agent header
            headers = httpClient.defaultRequestHeaders;

            // UserAgent is a HttpProductInfoHeaderValueCollection
            // A collection of HttpProductInfoHeaderValue items

            // The safe way to check a header value from the user is the TryParseAdd method
            // Since we know this header is okay, we use ParseAdd with will throw an exception
            // with a bad value 

            headers.userAgent.parseAdd("ie");
            headers.userAgent.parseAdd("Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0)");
        }
    });
})();

Abra a pasta js e o arquivo default.js, e adicione o código a seguir a ele.

(// For an introduction to the Blank template, see the following documentation:
// https://go.microsoft.com/fwlink/p/?LinkID=232509
(function () {
    "use strict";

    var app = WinJS.Application;
    var activation = Windows.ApplicationModel.Activation;

    app.onactivated = function (args) {
        if (args.detail.kind === activation.ActivationKind.launch) {
            if (args.detail.previousExecutionState !== activation.ApplicationExecutionState.terminated) {
                startButton.onclick = start;

            } else {
                startButton.onclick = start;
            }
            args.setPromise(WinJS.UI.processAll());
        }
    };

    app.oncheckpoint = function (args) {
        // This application is about to be suspended. Save any state
        // that needs to persist across suspensions here. You might use the
        // WinJS.Application.sessionState object, which is automatically
        // saved and restored across suspension. If you need to complete an
        // asynchronous operation before your application is suspended, call
        // args.setPromise().
    };

    app.start();
})();

Etapa 5: Enviar a solicitação GET e receber a resposta

Quando o botão Iniciar é clicado, primeiro validamos se o URI especificado no inputAddress é válido. Em seguida, enviamos a solicitação GET usando o URI e aguardamos para receber a resposta do servidor HTTP.

A maior parte do trabalho é feita no manipulador de cliques do Button Iniciar. Quando você clica nesse botão, o texto nos elementos de interface do usuário statusText e outputView é atualizado. Primeiro, o endereço de URI de entrada é verificado para garantir que o usuário tenha passado um endereço de URI válido. Se tivermos um URI válido do usuário, o aplicativo enviará a solicitação HTTP GET para o URI especificado e aguardará a resposta HTTP. Se ocorrer um erro ou uma exceção, o resultado será exibido no elemento de interface do usuário statusText. Se nenhum erro ocorrer, a resposta do serviço Web será exibida no elemento de interface do usuário outputView.

Uma exceção é gerada quando uma cadeia de caracteres inválida do URI é passada ao construtor para o objeto Windows.Foundation.Uri.

No JavaScript, não há nenhum método para tentar analisar uma cadeia de caracteres para um URI. Para pegar essa exceção nesse caso, use um bloco try/catch em torno do código onde o URI foi construído.

A amostra também verifica se o esquema HTTP no URI é HTTP ou HTTPS, pois esses são os únicos esquemas com suporte no Windows.Web.Http.HttpClient.

Usando as palavras-chave then e done no JavaScript, o código para enviar a solicitação GET e recuperar a resposta de forma assíncrona é semelhante ao código que usaríamos para concluir essa operação de forma síncrona.

Exceções devido a erros de rede (perda de conectividade, falhas de conexão e falhas do servidor HTTP, por exemplo) podem acontecer a qualquer momento. Esses erros geram as exceções. Quando não é resolvida pelo aplicativo, a exceção pode fazer seu aplicativo inteiro ser terminado pelo tempo de execução. É necessário escrever um código para tratar exceções quando você chama a maioria dos métodos de rede assíncronos. Às vezes, quando acontece uma exceção, um método de rede pode ser repetido para tentar resolver o problema. Outras vezes, o aplicativo tem de se planejar para continuar sem conectividade de rede, usando os dados que já foram armazenados em cache. Para saber mais sobre como tratar exceções de rede, veja Resolvendo exceções em aplicativos de rede.

O método HttpResponse.EnsureSuccessStatusCode gera uma exceção se o servidor Web retornou um código de status de erro HTTP, um HttpResponse.StatusCode não no intervalo Successful (200-299) para a solicitação. Usamos um bloco try/catch para qualquer exceção e imprimimos a mensagem de exceção no elemento de interface do usuário statusText se ocorre um erro.

A propriedade HttpResponse.Content representa o conteúdo da resposta HTTP. O método HttpClient.GetAsync(Uri) lê o conteúdo HTTP para uma cadeia de caracteres como uma operação assíncrona, Nós substituímos todas as marcas <br> no texto HTML retornado por novas linhas para fins de exibição. Se o método é bem-sucedido, exibimos o HttpResponse.StatusCode no elemento de interface do usuário statusText e HttpResponse.Content é retornado pelo serviço Web no elemento de interface do usuário outputView.

Abra a pasta js e adicione o código a seguir ao arquivo mainpage.js.
```
    function start()
    {

        var response = new Windows.Web.Http.HttpResponseMessage();

        var statusText = document.getElementById("statusText");
        var outputView = document.getElementById("outputView");

        // The value of 'inputAddress' is set by the user 
        // and is therefore untrusted input. 
        // If we can't create a valid absolute URI, 
        // We notify the user about the incorrect input.

        statusText.Text = "Testing URI is valid.";

        var uriString = document.getElementById("inputAddress").value.trim();
        if (!uriString) {
            return;
        }

        var resourceUri;
        try {
           resourceUri = new Windows.Foundation.Uri(uriString);
        }
        catch (Exception) {
            statusText.Text = "Invalid URI, please re-enter a valid URI.";
            return;
        }

        if (resourceUri.schemeName != "http" && resourceUri.schemeName != "https") {
            statusText.Text = "Only 'http' and 'https' schemes supported. Please re-enter URI";
            return;
        }

        var responseBodyAsText="";
        outputView.Text = "";
        statusText.Text = "Waiting for response ...";

        httpPromise = httpClient.getAsync(resourceUri).then(function (response) {
            outputStatus = response.statusCode + " " + response.reasonPhrase;

            response.EnsureSuccessStatusCode();

            response.content.readAsStringAsync().then(function (responseBodyAsText) {
            // Format the HTTP response to display better
            responseBodyAsText = responseBodyAsText.replace(/<br>/g, "\r\n");
            outputView.value = responseBodyAsText;
            return response;
        });
    )};

    httpPromise.done(function (response) {
        statusText.value = response.StatusCode + " " + response.ReasonPhrase + "\r\n";
    }, onError);

    function onError(error) {
        statusText.value = "Error = " + error.number + "  Message: " + error.message;
    }

})();
```
O Windows.Web.Http.HttpClient usa WinInet para enviar solicitações HTTP e de serviço Web, e receber respostas. O valor de tempo limite padrão usado pelo WinInet para uma operação de conexão HTTP é 60 segundos. Se um servidor HTTP ou serviço Web fica temporariamente inativo ou é bloqueado por um firewall e o servidor não consegue responder à solicitação do Windows.Web.Http.HttpClient, o WinInet aguarda os 60 segundos padrão antes de retornar um erro, o que faz uma exceção ser gerada no aplicativo. Se a consulta de um nome de servidor HTTP retorna vários endereços IP para o nome, o WinInet tenta diversos outros endereços IP para o site, cada qual com um tempo limite padrão de 60 segundos, antes de falhar. Um aplicativo que estiver fazendo uma solicitação HTTP ou de serviço Web poderá aguardar vários minutos fazendo tentativas de vários endereços IP, antes de um erro ser retornado pelo WinInet e uma exceção ser gerada. Esse comportamento pode dar ao usuário a impressão de que o aplicativo parou de funcionar. O tempo limite padrão usado pelo WinInet para enviar e receber operações depois que uma conexão foi estabelecida é de 30 segundos.

Para melhorar a resposta do aplicativo e minimizar esses problemas, o aplicativo pode ser aperfeiçoado definindo um tempo limite mais curto em operações do Windows.Web.Http.HttpClient, para que as operações falhem antes com o tempo limite em vez de fazê-lo com as configurações padrão do WinInet. Para saber mais sobre como configurar um tempo limite, consulte Definindo os valores de tempo limite com WinJS.xhr ou HttpClient e Como definir tempos limite em operações de soquete.

Comentários

Neste tópico, vimos como usar a classe Windows.Web.Http.HttpClient para enviar uma solicitação GET para um serviço Web e recuperar a resposta usando as classes Windows.Web.Http.HttpResponseMessage e relacionadas no namespace Windows.Web.Http.Headers.