Freigeben über


So wird’s gemacht: Herstellen einer Verbindung mit einem HTTP-Server mithilfe von „Windows.Web.Http“ (HTML)

[ Dieser Artikel richtet sich an Windows 8.x- und Windows Phone 8.x-Entwickler, die Windows-Runtime-Apps schreiben. Wenn Sie für Windows 10 entwickeln, finden Sie weitere Informationen unter neueste Dokumentation]

Senden Sie eine GET-Anforderung an einen Webdienst, und rufen Sie die Antwort mithilfe der Windows.Web.Http.HttpClient-Klasse im Windows.Web.Http-Namespace ab.

[Laden Sie sich das Beispiel zu HTTPClient herunter.]

Klassen im Windows.Web.Http-Namespace stellen eine Programmierschnittstelle für moderne HTTP-Client-Apps bereit. Der Windows.Web.Http-Namespace und die dazugehörigen Namespaces Windows.Web.Http.Headers und Windows.Web.Http.Filters stellen HTTP-Clientkomponenten bereit, mit denen Benutzer HTTP-Anforderungen ausführen und HTTP-Anforderungen von modernen Webdiensten per HTTP empfangen können.

Mit Windows 8.1 wird Windows.Web.Http eingeführt. Dies ist der Windows-Runtime-Namespace für Windows-Apps, die Verbindungen mit HTTP- und REST-Webdiensten (Representational State Transfer) herstellen. Diese neue API bietet Unterstützung für alle unterstützten Sprachen mit umfassenden Features und gilt als Ersatz für die HTTP-API, die ursprünglich unter Windows 8 veröffentlicht wurde.

Diese neue API ersetzt drei andere APIs mit unterschiedlichen Features, die unter Windows 8 bisher für jede Sprachprojektion erforderlich waren.

Für grundlegende Anforderungsvorgänge verfügt die neue API über eine einfache Schnittstelle zum Durchführen allgemeiner Aufgaben. Darüber werden auch angemessene Standardeinstellungen für die Authentifizierung (AUTH) bereitgestellt, die für die meisten Szenarios geeignet sind. Zu den weiteren Funktionen für komplexere HTTP-Vorgänge gehören:

  • Methoden für häufige Verben (DELETE, GET, PUT und POST)

  • Unterstützung für häufige Authentifizierungseinstellungen und -muster

  • Zugriff auf SSL-Details (Secure Sockets Layer) zum Transport

  • Möglichkeit zum Einbinden von benutzerdefinierten Filtern in erweiterte Apps

  • Möglichkeit zum Abrufen, Festlegen und Löschen von Cookies

  • Verfügbarkeit von Statusinformationen zu HTTP-Anforderungen in asynchronen Methoden

Die Windows.Web.Http.HttpClient-Klasse wird zum Senden und Empfangen grundlegender Anforderungen über HTTP verwendet. Sie stellt die Hauptklasse zum Versenden von HTTP-Anforderungen und Empfangen von HTTP-Antworten aus einer vom URI bestimmten Ressource bereit. Mit dieser Klasse kann eine GET-, PUT-, POST-, DELETE- oder andere Anforderung an den Webdienst gesendet werden. Jede dieser Anforderungen wird als asynchrone Operation gesendet.

Die Windows.Web.Http.HttpRequestMessage-Klasse stellt eine HTTP-Anforderungsnachricht dar, die von Windows.Web.Http.HttpClient gesendet wurde. Die Windows.Web.Http.HttpResponseMessage-Klasse stellt eine HTTP-Antwortnachricht dar, die von einer HTTP-Anforderung empfangen wurde. HTTP-Nachrichten werden von IETF in RFC 2616 definiert.

Der Windows.Web.Http-Namespace stellt eine Reihe verschiedener Klassen bereit, mit denen HTTP-Inhalte dargestellt werden (HTTP-Entitätskörper und Inhaltsheader, z. B. Cookies), die einer HTTP-Anforderung oder -Antwort zugeordnet sind. Diese unterschiedlichen Klassen ermöglichen Inhalten die Nutzung eines Puffers, einer Zeichenfolge, eines Streams sowie von Name-Wert-Daten, die mit dem MIME-Typ "application/x-www-form-urlencoded", "multipart/*" und "multipart/form-data" codiert sind. Außerdem können benutzerdefinierte Inhalte festgelegt werden.

In diesem Beispiel wird die HttpStringContent-Klasse verwendet, um die HTTP-Antwort als Zeichenfolge darzustellen.

Der Windows.Web.Http.Headers-Namespace unterstützt die Erstellung von HTTP-Headern und -Cookies, die dann als Eigenschaften mit HttpRequestMessage- und HttpResponseMessage-Objekten zugeordnet werden.

Voraussetzungen

Die folgenden Beispiele in diesem Thema sind in JavaScript und HTML verfasst. Dazu sind grundlegende Kenntnisse von HTTP-Anforderungen gemäß RFC 2616 erforderlich.

Es ist auch möglich, HTTP-Anforderungen in einer App mit JavaScript und HTML auszuführen. Verwenden Sie hierzu WinJS.xhr und XMLHttpRequest. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit einem Webdienst (Windows-Runtime-App mit JavaScript).

Anweisungen

Schritt 1: Erstellen eines neuen Projekts

  1. Öffnen Sie Microsoft Visual Studio 2013, und wählen Sie Neues Projekt im Menü Datei aus.
  2. Wählen Sie aus der Liste der Vorlagen JavaScript aus.
  3. Wählen Sie unterhalb des Abschnitts die Option Store apps aus.
  4. Wählen Sie unterhalb des Abschnitts je nach Zielplattform die Option Universal Apps, Windows apps oder Windows Phone apps und anschließend die Option Leere Anwendung aus.
  5. Geben Sie für die App den Namen HttpClientGet ein, und klicken Sie auf OK.

Schritt 2: Einrichten der Funktionen zur Aktivierung des Netzwerkzugriffs

Sie müssen die Netzwerkfunktionen für Ihre App einrichten, um den Zugriff auf eine private Homepage oder ein Firmennetzwerk sowie auf das Internet zu ermöglichen. Für diese App müssen Sie Netzwerkfunktionen einrichten, da der Client eine Verbindung zu Webservices herstellt.

Für eine App, die Windows.Web.Http.HttpClient zum Herstellen einer Verbindung mit einem Webdienst auf einem anderen Computer verwendet, müssen Netzwerkfunktionen für die App festgelegt werden. Wenn die App als Client eine Verbindung mit Webdiensten im Internet herstellen können muss, ist die Funktion Internet (Client) erforderlich. Wenn die App als Client eine Verbindung mit Webservices in einem Heim- oder Arbeitsplatznetzwerk herstellen muss, ist die Funktion Private Netzwerke (Client und Server) erforderlich.

Hinweis  Für Windows Phone gibt es nur die Netzwerkfunktion Internet (Client und Server), die den gesamten Netzwerkzugriff für die App aktiviert.

 

Wenn der Webdienst auf dem gleichen Computer ausgeführt wird wie die App, ist hierfür ein Loopbackzugriff erforderlich. In Visual Studio 2013 entwickelte und ausgeführte Apps werden automatisch so registriert, dass sie von den Loopbackbeschränkungen ausgenommen werden. Weitere Informationen finden Sie unter Aktivieren von Loopback und Debuggen der Netzwerkisolation.

Weitere Informationen zum Netzwerkzugriff finden Sie unter So wird's gemacht: Konfigurieren von Netzwerkfunktionen.

Diese Schritte sind erforderlich, um vor der Bereitstellung Netzwerkfunktionen für eine App einzurichten, wenn sie auf einen Webdienst im Internet oder auf ein privates Netzwerk oder Firmennetzwerk zugreift.

  1. Öffnen Sie die Datei "package.appxmanifest" mit Visual Studio 2013.

  2. Wählen Sie die Registerkarte Capabilities (Funktionen) aus.

  3. Wenn Sie die Windows-Version des Beispiels erstellen möchten, wählen Sie die Funktionen Internet (Client) und Private Netzwerke (Client und Server) aus.

    Wenn Sie die Windows Phone-Version des Beispiels erstellen möchten, wählen Sie die Funktion Internet (Client und Server) aus.

  4. Speichern und schließen Sie die Manifestdatei.

Schritt 3: Hinzufügen einer HTML-Benutzeroberfläche

  • In diesem Abschnitt definieren wir das App-Layout in HTML, um die ungefähre Größe und die Position der einzelnen Objekte in der App festzulegen. Wir stellen die Benutzeroberfläche für die App fertig, indem wir Steuerelemente und Inhalte zum Anzeigen von Daten hinzufügen.

    In diesem Beispiel werden einfache HTML-UI-Elemente verwendet, z. B.:

    • Ein Steuerelement mit class für eine Textbeschriftung und dem Eingabefeld für die URI-Eingangsadresse sowie einem button-Element zum Starten der asynchronen Anforderung.

    • Ein Steuerelement mit einem class-Element mit einer Textbeschriftung und einem Textfeld zum Anzeigen des aktuellen Status. Hier werden die Status- und Fehlernachrichten angezeigt. Diese Steuerelement enthält auch ein class-Element, in dem die Ausgabe des Webdiensts angezeigt wird. In diesem Beispiel werden die Ergebnisse des HTTP GET-Vorgangs als unformatierter Text mit HTML-Markup angezeigt.

    Öffnen Sie den Ordner js und die vorhandene Datei default.js, und fügen Sie ihr die folgenden UI-Elemente hinzu.

    <!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>
    

Schritt 4: Erstellen von HttpClient

  • Erstellen Sie zuerst das Windows.Web.Http.HttpClient-Objekt, und fügen Sie einen Benutzer-Agent-Header hinzu.

    Das HttpClient-Objekt sendet in der HTTP-Anforderung standardmäßig keinen Benutzer-Agent-Header an den Webdienst. Einige HTTP-Server, darunter auch bestimmte Microsoft-Webserver, verlangen jedoch, dass ein Benutzer-Agent-Header in vom Client gesendete HTTP-Anforderungen eingefügt wird. Der HTTP-Server gibt einen Fehler zurück, wenn kein Header vorhanden ist. Wir müssen einen Benutzer-Agent-Header hinzufügen, indem wir Klassen im Windows.Web.Http.Headers-Namespace verwenden. Wir fügen diesen Header der HttpClient.DefaultRequestHeaders-Eigenschaft hinzu, um diese Fehler zu vermeiden.

    Öffnen Sie den Ordner js, und fügen Sie eine neue Datei mainpage.js hinzu. Fügen Sie der Datei dann den folgenden Code hinzu.

    (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)");
            }
        });
    })();
    

    Öffnen Sie den Ordner js und die Datei default.js, und fügen Sie der Datei dann den folgenden Code hinzu.

    (// 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();
    })();
    

Schritt 5: Senden der GET-Anforderung und Empfangen der Antwort

  • Wenn auf die Schaltfläche Start geklickt wird, überprüfen wir zuerst, ob der unter inputAddress angegebene URI gültig ist. Anschließend senden wir die GET-Anforderung mithilfe des URIs und warten auf den Eingang der Antwort vom HTTP-Server.

    Die meiste Arbeit wird im Klickhandler für das Button-Element "Start" ausgeführt. Wenn auf diese Schaltfläche geklickt wird, wird der Text in den UI-Elementen statusText und outputView aktualisiert. Zuerst wird die URI-Eingangsadresse überprüft, um sicherzustellen, dass der Benutzer eine gültige URI-Adresse übergeben hat. Falls wir über einen gültigen URI vom Benutzer verfügen, sendet die App die HTTP GET-Anforderung an den angegebenen URI und wartet auf die HTTP-Antwort. Wenn ein Fehler oder eine Ausnahme auftritt, wird das Ergebnis im UI-Element statusText angezeigt. Wenn kein Fehler auftritt, wird die Antwort des Webdiensts im outputView-Benutzeroberflächenelement angezeigt.

    Eine Ausnahme wird ausgelöst, wenn eine ungültige Zeichenfolge für den Uniform Resource Identifier (URI) an den Konstruktor für das Windows.Foundation.Uri-Objekt übergeben wird.

    In JavaScript gibt es keine Methode zum Analysieren einer Zeichenfolge für einen URI. Verwenden Sie zum Abfangen dieser Ausnahme in diesem Fall einen try/catch-Block für den Code, mit dem der URI erstellt wird.

    Im Beispiel wird auch überprüft, ob das HTTP-Schema im URI HTTP oder HTTPS lautet, da dies die einzigen von Windows.Web.Http.HttpClient unterstützten Schemas sind.

    Mit den Schlüsselwörtern then und done in JavaScript ähnelt der Code zum Senden der GET-Anforderung und zum synchronen Abrufen dem Code, der zum synchronen Abschließen dieses Vorgangs verwendet wird.

    Ausnahmen aufgrund von Netzwerkfehlern (z. B. Unterbrechung der Netzwerkverbindung, Verbindungsfehler und HTTP-Serverfehler) können jederzeit auftreten. Diese Fehler haben zur Folge, dass Ausnahmen ausgelöst werden. Wenn sie nicht von Ihrer App behandelt wird, kann eine Ausnahme dazu führen, dass die gesamte App von der Runtime beendet wird. Beim Aufrufen der meisten asynchronen Netzwerkmethoden müssen Sie Code zum Behandeln von Ausnahmen schreiben. In manchen Fällen kann eine Netzwerkmethode beim Auftreten einer Ausnahme wiederholt werden, um das Problem zu beheben. In anderen Fällen muss die App ohne Netzwerkverbindung mit zuvor zwischengespeicherten Daten weiter ausgeführt werden. Weitere Informationen zum Behandeln von Netzwerkausnahmen finden Sie unter Behandeln von Ausnahmen in Netzwerk-Apps.

    Die HttpResponse.EnsureSuccessStatusCode-Methode löst eine Ausnahme aus, wenn der Webserver einen HTTP-Fehlerstatuscode HttpResponse.StatusCode zurückgegeben hat, der für die Anforderung nicht im Bereich Successful (200 bis 299) liegt. Wir verwenden für alle Ausnahmen einen try/catch-Block und geben die Ausnahmemeldung im UI-Element statusText aus, wenn ein Fehler auftritt.

    Die HttpResponse.Content-Eigenschaft stellt den Inhalt der HTTP-Antwort dar. Die HttpClient.GetAsync(Uri)-Methode liest den HTTP-Inhalt als asynchronen Vorgang in eine Zeichenfolge. Für die Anzeige ersetzen wir alle <br>-Tags im zurückgegebenen HTML-Text durch Zeilenumbrüche. Wenn die Methode erfolgreich ist, werden der HttpResponse.StatusCode im UI-Element statusText und der vom Webdienst zurückgegebene HttpResponse.Content im UI-Element outputView angezeigt.

    Öffnen Sie den Ordner js, und fügen Sie der Datei mainpage.js den folgenden Code hinzu.

        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;
        }
    
    })();
    

    Windows.Web.Http.HttpClient nutzt WinInet zum Senden von HTTP- und Webdienstanforderungen sowie zum Empfangen von Antworten. Der standardmäßige Zeitüberschreitungswert, der von WinInet für einen HTTP-Verbindungsvorgang verwendet wird, lautet 60 Sekunden. Wenn ein HTTP-Server oder Webdienst vorübergehend nicht verfügbar oder durch eine Firewall blockiert ist und der Server auf die Windows.Web.Http.HttpClient-Anforderung nicht antwortet oder antworten kann, wird von WinInet die standardmäßig festgelegten 60 Sekunden lang abgewartet, bevor ein Fehler zurückgegeben wird, der in der App zur Auslösung einer Ausnahme führt. Falls die Namensabfrage für einen HTTP-Servernamen mehrere IP-Adressen für den Namen zurückgibt, probiert WinInet einige andere IP-Adressen für die Site aus. Dabei wird jeweils die Standardzeitüberschreitung von 60 Sekunden eingehalten, bevor ein Fehler auftritt. Eine App, die eine HTTP- oder Webdienstanforderung ausführt, kann mehrere Minuten lang erneute Versuche für mehrere IP-Adressen durchführen, bevor von WinInet ein Fehler zurückgegeben und eine Ausnahme ausgelöst wird. Dieses Verhalten kann für Benutzer den Anschein erwecken, als ob die App nicht mehr reagiert. Die standardmäßige Zeitüberschreitung, die von WinInet zum Senden und Empfangen von Vorgängen nach dem Herstellen einer Verbindung verwendet wird, beträgt 30 Sekunden.

    Wenn Apps schneller reagieren und diese Probleme verringert werden sollen, können Sie die Leistung einer App verbessern, indem Sie einen kürzeren Zeitraum für die Zeitüberschreitung bei Windows.Web.Http.HttpClient-Vorgängen festlegen. Für Vorgänge tritt aufgrund der Zeitüberschreitung dann schneller ein Fehler auf, als durch die WinInet-Standardeinstellungen vorgegeben ist. Weitere Informationen zum Einrichten einer Zeitüberschreitung finden Sie unter Festlegen von Timeoutwerten mit "WinJS.xhr" oder "HttpClient" sowie unter So wird's gemacht: Festlegen von Timeouts für Socketvorgänge.

Anmerkungen

Wir haben in diesem Thema gezeigt, wie die Windows.Web.Http.HttpClient-Klasse für das Senden einer GET-Anforderung an einen Webdienst verwendet wird und wie die Antwort mit der Windows.Web.Http.HttpResponseMessage-Klasse und verwandten Klassen im Windows.Web.Http.Headers-Namespace abgerufen wird.

Verwandte Themen

Weitere Ressourcen

Herstellen von Verbindungen mit Webdiensten

Behandeln von Ausnahmen in Netzwerk-Apps

So wird's gemacht: Konfigurieren von Netzwerkfunktionen

Aktivieren von Loopback und Debuggen der Netzwerkisolation.

Festlegen von Timeoutwerten mit "WinJS.xhr" oder "HttpClient"

Referenz

Windows.Foundation.Uri

Windows.Web.Http

Windows.Web.Http.Filters

Windows.Web.Http.Headers

Beispiele

Beispiel für HttpClient

Beispiel zur Webauthentifizierung