Ableiten von WebRequest

Die WebRequest-Klasse ist eine abstrakte Basisklasse, die die grundlegende Methoden und Eigenschaften bereitstellt, mit denen ein protokollspezifischer Anforderungshandler erstellt wird, der in das austauschbare Protokollmodell von .NET Framework passt. Anwendungen, die die WebRequest-Klasse verwenden, können Daten mit einem beliebigen unterstützten Protokoll anfordern, ohne das verwendete Protokoll anzugeben.

Zwei Kriterien müssen erfüllt sein, damit eine protokollspezifische Klasse als ein austauschbares Protokoll verwendet werden kann: Die Klasse muss die IWebRequestCreate-Schnittstelle implementieren und sie mit der WebRequest.RegisterPrefix-Methode registrieren. Die Klasse muss alle abstrakten Methoden und Eigenschaften von WebRequest überschreiben, um die austauschbare Schnittstelle bereitzustellen.

WebRequest-Instanzen sind für die einmalige Verwendung vorgesehen. Wenn Sie eine andere Anforderung vornehmen möchten, erstellen Sie eine neue WebRequest. WebRequest unterstützt die ISerializable-Schnittstelle, um Entwicklern zu ermöglichen, eine WebRequest-Vorlage zu serialisieren und die Vorlage für zusätzliche Anforderungen zu rekonstruieren.

IWebRequest Create-Methode

Die Create-Methode ist verantwortlich für das Initialisieren einer neuen Instanz der protokollspezifischen Klasse. Wenn eine neue WebRequest erstellt wird, entspricht die WebRequest.Create-Methode dem angeforderten URI und die URI-Präfixe werden mit der RegisterPrefix-Methode registriert. Die Create-Methode des entsprechenden protokollspezifischen Nachfolgers muss eine initialisierte Instanz des Nachfolgers zurückgeben, die eine Standardtransaktion für Anforderungen/Antworten für das Protokoll ausführen kann, ohne ein protokollspezifisches Feld zu ändern.

ConnectionGroupName-Eigenschaft

Die ConnectionGroupName-Eigenschaft wird verwendet, um eine Gruppe von Verbindungen mit einer Ressource zu benennen, damit mehrere Anforderungen über eine einzelne Verbindung ausgeführt werden können. Um die Freigabe von Verbindungen zu implementieren, müssen Sie eine protokollspezifische Methode zum Pooling und Zuweisen von Verbindungen verwenden. Zum Beispiel implementiert die bereitgestellte ServicePointManager-Klasse die gemeinsame Nutzung von Verbindungen für die HttpWebRequest-Klasse. Die ServicePointManager-Klasse erstellt eine ServicePoint, die eine Verbindung mit einem bestimmten Server für jede Verbindungsgruppierung bereitstellt.

ContentLength-Eigenschaft

Die ContentLength-Eigenschaft gibt die Anzahl der Datenbytes an, die beim Hochladen von Daten an den Server gesendet werden.

In der Regel muss die Method-Eigenschaft so festgelegt werden, dass sie angibt, dass ein Upload stattfindet, wenn die ContentLength-Eigenschaft auf einen Wert größer als 0 (null) festgelegt ist.

ContentType-Eigenschaft

Die ContentType-Eigenschaft stellt spezielle Informationen zur Verfügung, die Sie für Ihr Protokoll an den Server senden müssen, um den Typ des Inhalts, den Sie senden, zu identifizieren. In der Regel ist dies der MIME-Inhaltstyp aller hochgeladenen Daten.

Credentials-Eigenschaft

Die Credentials-Eigenschaft enthält Informationen, die zum Authentifizieren der Anforderung mit dem Server erforderlich sind. Sie müssen die Details des Authentifizierungsprozesses für Ihr Protokoll implementieren. Die AuthenticationManager-Klasse ist verantwortlich für das Authentifizieren von Anforderungen und die Bereitstellung eines Authentifizierungstokens. Die Klasse, die die von Ihrem Protokoll benötigten Anmeldeinformationen bereitstellt, muss die ICredentials-Schnittstelle implementieren.

Header-Eigenschaft

Die Headers-Eigenschaft enthält eine beliebige Auflistung von Name/Wert-Paaren der Metadaten, die der Anforderung zugeordnet sind. Alle für das Protokoll erforderlichen Metadaten, die als Name/Wert-Paar ausgedrückt werden, können in die Header-Eigenschaft aufgenommen werden. In der Regel müssen diese Informationen festgelegt werden, bevor die GetRequestStream- oder GetResponse-Methoden aufgerufen werden. Sobald die Anforderung gestellt wurde, gelten die Metadaten als schreibgeschützt.

Sie müssen die Header-Eigenschaft nicht verwenden, um die Header-Metadaten zu nutzen. Protokollspezifische Metadaten können als Eigenschaften verfügbar gemacht werden. So macht die HttpWebRequest.UserAgent-Eigenschaft z.B. den HTTP-Header User-Agent verfügbar. Wenn Sie die Header-Metadaten als Eigenschaft verfügbar machen, sollten Sie vermeiden, dass die gleiche Eigenschaft die Header-Eigenschaft verwendet.

Methode-Eigenschaft

Die Method-Eigenschaft enthält das Verb oder die Aktion, die der Server auf Anfrage ausführen soll. Die Standardeinstellung für die Method-Eigenschaft muss eine Standardanforderung/-antwort aktivieren, ohne protokollspezifische Eigenschaften festzulegen. Die Method-Methode wird z.B. standardmäßig auf „GET“ festgelegt, womit eine Ressource von einem Webserver angefordert und die Antwort zurückgegeben wird.

In der Regel muss die ContentLength-Eigenschaft auf einen Wert höher als 0 (null) festgelegt werden, wenn die Method-Eigenschaft auf ein Verb oder eine Aktion festgelegt ist, die angeben, dass ein Upload stattfindet.

PreAuthenticate-Eigenschaft

Anwendungen legen die PreAuthenticate-Eigenschaft fest, um anzugeben, dass die Authentifizierungsinformationen mit der ursprünglichen Anforderung gesendet werden sollen anstatt auf eine Authentifizierungsaufforderung zu warten. Die PreAuthenticate-Eigenschaft ist nur sinnvoll, wenn das Protokoll die Authentifizierungsinformationen unterstützt, die mit der ursprünglichen Anforderung gesendet wurden.

Proxy-Eigenschaft

Die Proxy-Eigenschaft enthält eine IWebProxy-Schnittstelle, die verwendet wird, um auf die angeforderte Ressource zuzugreifen. Die Proxy-Eigenschaft ist nur sinnvoll, wenn Ihr Protokoll Proxyanforderungen unterstützt. Sie müssen den Standardproxy festlegen, wenn dieser von Ihrem Protokoll benötigt wird.

In einigen Umgebungen, z.B. hinter einer Unternehmensfirewall, benötigt Ihr Protokoll möglicherweise einen Proxy. In diesem Fall müssen Sie die IWebProxy-Schnittstelle implementieren, um eine Proxyklasse zu erstellen, die für Ihr Protokoll verwendet werden kann.

RequestUri-Eigenschaft

Die RequestUri-Eigenschaft enthält den URI, der an die WebRequest.Create-Methode übergeben wurde. Er ist schreibgeschützt und kann nicht geändert werden, sobald WebRequest erstellt wurde. Wenn Ihr Protokoll Umleitung unterstützt, kann die Antwort aus einer durch einen anderen URI identifizierten Ressource stammen. Wenn Sie den Zugriff auf den URI, der geantwortet hat, ermöglichen müssen, müssen Sie eine zusätzliche Eigenschaft angeben, die diesen URI enthält.

Timeouteigenschaft

Die Timeout-Eigenschaft enthält die abzuwartende Zeitdauer in Millisekunden, bevor die Anforderung ein Timeout und eine Ausnahme auslöst. Timeout gilt nur für synchrone Anforderungen durch die GetResponse-Methode. Asynchrone Anforderungen müssen die Abort-Methode verwenden, um eine ausstehende Anforderung abzubrechen.

Das Festlegen der Timeout-Eigenschaft ist nur sinnvoll, wenn die protokollspezifische Klasse einen Timeout-Prozess implementiert.

Abort-Methode

Die Abort-Methode bricht eine ausstehende asynchrone Anforderung an einen Server ab. Nachdem die Anforderung abgebrochen wurde, löst ein Aufruf von GetResponse, BeginGetResponse, EndGetResponse, GetRequestStream, BeginGetRequestStream oder EndGetRequestStream eine WebException aus, und die Status-Eigenschaft ist auf WebExceptionStatus festgelegt.

BeginGetRequestStream- und EndGetRequestStream-Methoden

Die BeginGetRequestStream-Methode startet eine asynchrone Anforderung für den Datenstrom, der zum Hochladen von Daten an den Server verwendet wird. Die EndGetRequestStream-Methode schließt die asynchrone Anforderung ab und gibt den angeforderten Datenstrom zurück. Diese Methoden implementieren die GetRequestStream-Methode mithilfe des standardmäßigen asynchronen .NET Framework-Musters.

BeginGetResponse- und EndGetResponse-Methoden

Die BeginGetResponse-Methode beginnt eine asynchrone Anforderung an einen Server. Die EndGetResponse-Methode schließt die asynchrone Anforderung ab und gibt die angeforderte Antwort zurück. Diese Methoden implementieren die GetResponse-Methode mithilfe des standardmäßigen asynchronen .NET Framework-Musters.

GetRequestStream-Methode

Die GetRequestStream-Methode gibt einen Datenstrom zurück, der zum Schreiben von Daten an den angeforderten Server verwendet wird. Der zurückgegebene Datenstrom sollte ein lesegeschützter, nicht suchender Datenstrom sein. Er soll einen unidirektionalen Datenstrom darstellen, der an den Server geschrieben wird. Der Datenstrom gibt FALSE für die CanRead- und CanSeek-Eigenschaften und TRUE für die CanWrite-Eigenschaft zurück.

Die GetRequestStream-Methode öffnet in der Regel eine Verbindung mit dem Server und sendet vor der Rückgabe des Datenstroms Headerinformationen, die angeben, dass Daten an den Server gesendet werden. Da GetRequestStream die Anforderung startet, dürfen die Header-Eigenschaften oder die ContentLength-Eigenschaft in der Regel nicht nach dem GetRequestStream-Aufruf festgelegt werden.

GetResponse-Methode

Die GetResponse-Methode gibt einen protokollspezifischen Nachfolger der WebResponse-Klasse zurück, der die Antwort des Servers darstellt. Solange die Anforderung noch nicht durch die GetRequestStream-Methode eingeleitet wurde, erstellt die GetResponse-Methode eine Verbindung mit der durch RequestUri identifizierten Ressource, versendet Headerinformationen, die den Typ der Anforderung angeben, und empfängt dann die Antwort von der Ressource.

Sobald die GetResponse-Methode aufgerufen wird, sollten alle Eigenschaften als schreibgeschützt angesehen werden. WebRequest-Instanzen sind für die einmalige Verwendung vorgesehen. Wenn Sie eine andere Anforderung vornehmen möchten, erstellen Sie eine neue WebRequest.

Die GetResponse-Methode ist verantwortlich für das Erstellen eines entsprechenden WebResponse-Nachfolgers, der die eingehende Antwort enthält.

Siehe auch