Ableiten von WebRequestDeriving from 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.The WebRequest class is an abstract base class that provides the basic methods and properties for creating a protocol-specific request handler that fits the .NET Framework pluggable protocol model. Anwendungen, die die WebRequest-Klasse verwenden, können Daten mit einem beliebigen unterstützten Protokoll anfordern, ohne das verwendete Protokoll anzugeben.Applications that use the WebRequest class can request data using any supported protocol without needing to specify the protocol used.

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.Two criteria must be met in order for a protocol-specific class to be used as a pluggable protocol: The class must implement the IWebRequestCreate interface, and it must register with the WebRequest.RegisterPrefix method. Die Klasse muss alle abstrakten Methoden und Eigenschaften von WebRequest überschreiben, um die austauschbare Schnittstelle bereitzustellen.The class must override all the abstract methods and properties of WebRequest to provide the pluggable interface.

WebRequest-Instanzen sind für die einmalige Verwendung vorgesehen. Wenn Sie eine andere Anforderung vornehmen möchten, erstellen Sie eine neue WebRequest.WebRequest instances are intended for one-time use; if you want to make another request, create a new 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.WebRequest supports the ISerializable interface to enable developers to serialize a template WebRequest and then reconstruct the template for additional requests.

IWebRequest Create-MethodeIWebRequest Create Method

Die Create-Methode ist verantwortlich für das Initialisieren einer neuen Instanz der protokollspezifischen Klasse.The Create method is responsible for initializing a new instance of the protocol-specific class. 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.When a new WebRequest is created, the WebRequest.Create method matches the requested URI with the URI prefixes registered with the RegisterPrefix method. 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.The Create method of the proper protocol-specific descendant must return an initialized instance of the descendant capable of performing a standard request/response transaction for the protocol without needing any protocol-specific fields modified.

ConnectionGroupName-EigenschaftConnectionGroupName Property

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.The ConnectionGroupName property is used to name a group of connections to a resource so that multiple requests can be made over a single connection. Um die Freigabe von Verbindungen zu implementieren, müssen Sie eine protokollspezifische Methode zum Pooling und Zuweisen von Verbindungen verwenden.To implement connection-sharing, you must use a protocol-specific method of pooling and assigning connections. Zum Beispiel implementiert die bereitgestellte ServicePointManager-Klasse die gemeinsame Nutzung von Verbindungen für die HttpWebRequest-Klasse.For example, the provided ServicePointManager class implements connection sharing for the HttpWebRequest class. Die ServicePointManager-Klasse erstellt eine ServicePoint, die eine Verbindung mit einem bestimmten Server für jede Verbindungsgruppierung bereitstellt.The ServicePointManager class creates a ServicePoint that provides a connection to a specific server for each connection group.

ContentLength-EigenschaftContentLength Property

Die ContentLength-Eigenschaft gibt die Anzahl der Datenbytes an, die beim Hochladen von Daten an den Server gesendet werden.The ContentLength property specifies the number of bytes of data that will be sent to the server when uploading data.

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.Typically the Method property must be set to indicate that an upload is taking place when the ContentLength property is set to a value greater than zero.

ContentType-EigenschaftContentType Property

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.The ContentType property provides any special information that your protocol requires you to send to the server to identify the type of content that you are sending. In der Regel ist dies der MIME-Inhaltstyp aller hochgeladenen Daten.Typically this is the MIME content type of any data uploaded.

Credentials-EigenschaftCredentials Property

Die Credentials-Eigenschaft enthält Informationen, die zum Authentifizieren der Anforderung mit dem Server erforderlich sind.The Credentials property contains information needed to authenticate the request with the server. Sie müssen die Details des Authentifizierungsprozesses für Ihr Protokoll implementieren.You must implement the details of the authentication process for your protocol. Die AuthenticationManager-Klasse ist verantwortlich für das Authentifizieren von Anforderungen und die Bereitstellung eines Authentifizierungstokens.The AuthenticationManager class is responsible for authenticating requests and providing an authentication token. Die Klasse, die die von Ihrem Protokoll benötigten Anmeldeinformationen bereitstellt, muss die ICredentials-Schnittstelle implementieren.The class that provides the credentials used by your protocol must implement the ICredentials interface.

Header-EigenschaftHeaders Property

Die Headers-Eigenschaft enthält eine beliebige Auflistung von Name/Wert-Paaren der Metadaten, die der Anforderung zugeordnet sind.The Headers property contains an arbitrary collection of name/value pairs of metadata associated with the request. Alle für das Protokoll erforderlichen Metadaten, die als Name-Wert-Paar ausgedrückt werden, können in die Header-Eigenschaft aufgenommen werden.Any metadata needed by the protocol that can be expressed as a name/value pair can be included in the Headers property. 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.Typically this information must be set before calling the GetRequestStream or GetResponse methods; once the request has been made, the metadata is considered read-only.

Sie müssen die Header-Eigenschaft nicht verwenden, um die Header-Metadaten zu nutzen.You are not required to use the Headers property to use header metadata. 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.Protocol-specific metadata can be exposed as properties; for example, the HttpWebRequest.UserAgent property exposes the User-Agent HTTP header. Wenn Sie die Header-Metadaten als Eigenschaft verfügbar machen, sollten Sie nicht zulassen, dass die gleiche Eigenschaft die Header-Eigenschaft verwendet.When you expose header metadata as a property, you should not allow the same property to be set using the Headers property.

Methode-EigenschaftMethod Property

Die Method-Eigenschaft enthält das Verb oder die Aktion, die der Server auf Anfrage ausführen soll.The Method property contains the verb or action that the request is asking the server to perform. Die Standardeinstellung für die Method-Eigenschaft muss eine Standardanforderung/-antwort aktivieren, ohne protokollspezifische Eigenschaften festzulegen.The default for the Method property must enable a standard request/response action without requiring any protocol-specific properties to be set. Die Method-Methode wird z.B. standardmäßig auf „GET“ festgelegt, womit eine Ressource von einem Webserver angefordert und die Antwort zurückgegeben wird.For example, the Method method defaults to GET, which requests a resource from a Web server and returns the response.

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.Typically the ContentLength property must be set to a value greater than zero when the Method property is set to a verb or action that indicates that an upload is taking place.

PreAuthenticate-EigenschaftPreAuthenticate Property

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.Applications set the PreAuthenticate property to indicate that authentication information should be sent with the initial request rather than waiting for an authentication challenge. Die PreAuthenticate-Eigenschaft ist nur sinnvoll, wenn das Protokoll die Authentifizierungsinformationen unterstützt, die mit der ursprünglichen Anforderung gesendet wurden.The PreAuthenticate property is only meaningful if the protocol supports authentication credentials sent with the initial request.

Proxy-EigenschaftProxy Property

Die Proxy-Eigenschaft enthält eine IWebProxy-Schnittstelle, die verwendet wird, um auf die angeforderte Ressource zuzugreifen.The Proxy property contains an IWebProxy interface that is used to access the requested resource. Die Proxy-Eigenschaft ist nur sinnvoll, wenn Ihr Protokoll Proxyanforderungen unterstützt.The Proxy property is meaningful only if your protocol supports proxied requests. Sie müssen den Standardproxy festlegen, wenn dieser von Ihrem Protokoll benötigt wird.You must set the default proxy if one is required by your protocol.

In einigen Umgebungen, z.B. hinter einer Unternehmensfirewall, benötigt Ihr Protokoll möglicherweise einen Proxy.In some environments, such as behind a corporate firewall, your protocol might be required to use a proxy. In diesem Fall müssen Sie die IWebProxy-Schnittstelle implementieren, um eine Proxyklasse zu erstellen, die für Ihr Protokoll verwendet werden kann.In that case, you must implement the IWebProxy interface to create a proxy class that will work for your protocol.

RequestUri-EigenschaftRequestUri Property

Die RequestUri-Eigenschaft enthält den URI, der an die WebRequest.Create-Methode übergeben wurde.The RequestUri property contains the URI that was passed to the WebRequest.Create method. Er ist schreibgeschützt und kann nicht geändert werden, sobald WebRequest erstellt wurde.It is read-only and cannot be changed once the WebRequest has been created. Wenn Ihr Protokoll Umleitung unterstützt, kann die Antwort aus einer durch einen anderen URI identifizierten Ressource stammen.If your protocol supports redirection, the response can come from a resource identified by a different URI. 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.If you need to provide access to the URI that responded, you must provide an additional property containing that URI.

TimeouteigenschaftTimeout Property

Die Timeout-Eigenschaft enthält die abzuwartende Zeitdauer in Millisekunden, bevor die Anforderung ein Timeout und eine Ausnahme auslöst.The Timeout property contains the length of time, in milliseconds, to wait before the request times out and throws an exception. Timeout gilt nur für synchrone Anforderungen durch die GetResponse-Methode. Asynchrone Anforderungen müssen die Abort-Methode verwenden, um eine ausstehende Anforderung abzubrechen.Timeout applies only to synchronous requests made with the GetResponse method; asynchronous requests must use the Abort method to cancel a pending request.

Das Festlegen der Timeout-Eigenschaft ist nur sinnvoll, wenn die protokollspezifische Klasse einen Timeout-Prozess implementiert.Setting the Timeout property is meaningful only if the protocol-specific class implements a time-out process.

Abort-MethodeAbort Method

Die Abort-Methode bricht eine ausstehende asynchrone Anforderung an einen Server ab.The Abort method cancels a pending asynchronous request to a server. 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.After the request has been canceled, calling GetResponse, BeginGetResponse, EndGetResponse, GetRequestStream, BeginGetRequestStream, or EndGetRequestStream will throw a WebException with the Status property set to WebExceptionStatus.

BeginGetRequestStream- und EndGetRequestStream-MethodenBeginGetRequestStream and EndGetRequestStream Methods

Die BeginGetRequestStream-Methode startet eine asynchrone Anforderung für den Datenstrom, der zum Hochladen von Daten an den Server verwendet wird.The BeginGetRequestStream method starts an asynchronous request for the stream that is used to upload data to the server. Die EndGetRequestStream-Methode schließt die asynchrone Anforderung ab und gibt den angeforderten Datenstrom zurück.The EndGetRequestStream method completes the asynchronous request and returns the requested stream. Diese Methoden implementieren die GetRequestStream-Methode mithilfe des standardmäßigen asynchronen .NET Framework-Musters.These methods implement the GetRequestStream method using the standard .NET Framework asynchronous pattern.

BeginGetResponse- und EndGetResponse-MethodenBeginGetResponse and EndGetResponse Methods

Die BeginGetResponse-Methode beginnt eine asynchrone Anforderung an einen Server.The BeginGetResponse method starts an asynchronous request to a server. Die EndGetResponse-Methode schließt die asynchrone Anforderung ab und gibt die angeforderte Antwort zurück.The EndGetResponse method completes the asynchronous request and returns the requested response. Diese Methoden implementieren die GetResponse-Methode mithilfe des standardmäßigen asynchronen .NET Framework-Musters.These methods implement the GetResponse method using the standard .NET Framework asynchronous pattern.

GetRequestStream-MethodeGetRequestStream Method

Die GetRequestStream-Methode gibt einen Datenstrom zurück, der zum Schreiben von Daten an den angeforderten Server verwendet wird.The GetRequestStream method returns a stream that is used to write data to the requested server. Der zurückgegebene Datenstrom sollte ein lesegeschützter, nicht suchender Datenstrom sein. Er soll einen unidirektionalen Datenstrom darstellen, der an den Server geschrieben wird.The stream returned should be a write-only stream that does not seek; it is intended as a one-way stream of data that is written to the server. Der Datenstrom gibt FALSE für die CanRead- und CanSeek-Eigenschaften und TRUE für die CanWrite-Eigenschaft zurück.The stream returns false for the CanRead and CanSeek properties and true for the CanWrite property.

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.The GetRequestStream method typically opens a connection to the server and, before returning the stream, sends header information that indicates that data is being sent to the server. Da GetRequestStream die Anforderung startet, dürfen die Header-Eigenschaften oder die ContentLength-Eigenschaft in der Regel nicht nach dem GetRequestStream-Aufruf festgelegt werden.Because GetRequestStream begins the request, setting any Header properties or the ContentLength property is typically not allowed after calling GetRequestStream.

GetResponse-MethodeGetResponse Method

Die GetResponse-Methode gibt einen protokollspezifischen Nachfolger der WebResponse-Klasse zurück, der die Antwort des Servers darstellt.The GetResponse method returns a protocol-specific descendant of the WebResponse class that represents the response from the server. 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.Unless the request has already been initiated by the GetRequestStream method, the GetResponse method creates a connection to the resource identified by RequestUri, sends header information indicating the type of request being made, and then receives the response from the resource.

Sobald die GetResponse-Methode aufgerufen wird, sollten alle Eigenschaften als schreibgeschützt angesehen werden.Once the GetResponse method is called, all properties should be considered read-only. WebRequest-Instanzen sind für die einmalige Verwendung vorgesehen. Wenn Sie eine andere Anforderung vornehmen möchten, erstellen Sie eine neue WebRequest.WebRequest instances are intended for one-time use; if you want to make another request, you should create a new WebRequest.

Die GetResponse-Methode ist verantwortlich für das Erstellen eines entsprechenden WebResponse-Nachfolgers, der die eingehende Antwort enthält.The GetResponse method is responsible for creating an appropriate WebResponse descendant to contain the incoming response.

Weitere InformationenSee also