Networking
System
[00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ]
1.0.x.x
1.0.5000.0
2.0.0.0
4.0.0.0
All public static members of this type are safe for multithreaded operations. No instance members are guaranteed to be thread safe.
System.MarshalByRefObject
System.Runtime.Serialization.ISerializable
The following example demonstrates using to create an instance of
.
using System;
using System.Net;
public class WebRequestExample {
public static void Main() {
// Initialize the WebRequest.
WebRequest myRequest =
WebRequest.Create("http://www.contoso.com");
// Print the type of the request.
Console.WriteLine(myRequest);
}
}
The output is
System.Net.HttpWebRequest
is the abstract base class for the .NET Framework's request/response model for accessing data from the Internet. An application that uses the request/response model can request data from the Internet in a protocol-agnostic manner, in which the application works with instances of the class while protocol-specific descendant classes carry out the details of the request.
Requests are sent from an application to a particular URI, such as a Web page on a server. The URI determines the proper descendant class to create from a list of descendants registered for the application. descendants are typically registered to handle a specific protocol, such as HTTP or FTP, but can be registered to handle a request to a specific server or path on a server.
The class throws a when errors occur while accessing an Internet resource. The property is one of the values that indicates the source of the error. When is , the property contains the received from the Internet resource.
Because the class is an abstract class, the actual behavior of instances at run time is determined by the descendant class returned by method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
Use the method to initialize new instances. Do not use the constructor.
If the application that creates the WebRequest object runs with the credentials of a Normal user, the application will not be able to access certificates installed in the local machine store unless permission has been explicitly given to the user to do so.
Makes a request to a Uniform Resource Identifier (URI). This is an abstract class.
Constructor
1.0.5000.0
2.0.0.0
4.0.0.0
Use the method to initialize new instances. Do not use the constructor.
Initializes a new instance of the class.
0
Constructor
1.0.5000.0
2.0.0.0
4.0.0.0
When implemented by a descendant class, this constructor implements the interface for the descendant.
Notice that an application must run in full trust mode when using serialization.
Initializes a new instance of the class from the specified instances of the and classes.
A that contains the information required to serialize the new instance.
A that indicates the source of the serialized stream associated with the new instance.
Method
1.0.5000.0
2.0.0.0
4.0.0.0
System.Void
This method is not overridden in the derived class.
The method cancels asynchronous requests to Internet resources started with the method.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
Aborts the Request
0
Property
2.0.0.0
4.0.0.0
System.Net.Security.AuthenticationLevel
To be added.
To be added.
Gets or sets values indicating the level of authentication and impersonation used for this request.
Method
1.0.5000.0
2.0.0.0
4.0.0.0
System.IAsyncResult
This method is not overridden in the derived class.
The method starts an asynchronous request for a stream used to send data to an Internet resource. The callback method that implements the delegate uses the method to return the request stream.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, provides an asynchronous version of the method.
An that references the asynchronous request.
The delegate.
An object containing state information for this asynchronous request.
0
Method
1.0.5000.0
2.0.0.0
4.0.0.0
System.IAsyncResult
This method is not overridden in the derived class.
The method starts an asynchronous request for a response. The callback method that implements the delegate uses the method to return the from the Internet resource.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
If a WebException is thrown, use the and properties of the exception to determine the response from the server.
When overridden in a descendant class, begins an asynchronous request for an Internet resource.
An that references the asynchronous request.
The delegate.
An object containing state information for this asynchronous request.
0
Property
2.0.0.0
4.0.0.0
System.MonoTODO("Implement the caching system. Currently always returns a policy with the NoCacheNoStore level")
System.Net.Cache.RequestCachePolicy
To be added.
The current cache policy and the presence of the requested resource in the cache determine whether a response can be retrieved from the cache. Using cached responses usually improves application performance, but there is a risk that the response in the cache does not match the response on the server.
Default cache policy can be specified in the Machine.config configuration file or by setting the property for requests that use the Hypertext Transfer Protocol (HTTP) or Secure Hypertext Transfer Protocol (HTTPS) URI scheme.
A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the cache policy level for this request.
Gets or sets the cache policy for this request.
Property
1.0.5000.0
2.0.0.0
4.0.0.0
System.String
A that contains the name of the connection group for the current instance.
This property is not implemented in the derived class.
The property associates specific requests within an application to one or more connection pools.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, gets or sets the name of the connection group for the request.
0
Property
1.0.5000.0
2.0.0.0
4.0.0.0
System.Int64
A containing the number of bytes of request data being sent.
This property is not implemented in the derived class.
Data has already been written to the request stream.
This property is being set to a value less than zero.
The property contains the number of bytes of data sent to the Internet resource by the instance.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, gets or sets the content length of the request data being sent.
0
Property
1.0.5000.0
2.0.0.0
4.0.0.0
System.String
A that represents the content type of the request data.
This property is not implemented in the derived class.
The property contains the media type of the request. This is typically the MIME encoding of the content.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, gets or sets the content type of the request data being sent.
0
Method
1.0.5000.0
2.0.0.0
4.0.0.0
System.Net.WebRequest
is .
The request scheme specified in is not registered.
The URI specified in is not a valid URI.
The caller does not have permission to connect to the requested URI or a URI that the request is redirected to.
Requires permission to connect to the requested URI. See .
The method returns a descendant of the class determined at run time as the closest registered match for .
For example, when a URI beginning with http:// or https:// is passed in , an is returned by . If a URI beginning with ftp:// is passed instead, the method will return a instance. If a URI beginning with file:// is passed instead, the method will return a instance.
The pre-registered reserve types already registered include the following:
-
http://
-
https://
-
ftp://
-
file://
The .NET Framework includes support for the http://, https://, ftp://, and file:// URI schemes. Custom descendants to handle other requests are registered with the method.
The method uses the parameter to create a instance that it passes to the new .
This member outputs trace information when you enable network tracing in your application. For more information, see [<topic://conUsingNetworkTracing>].
Initializes a new instance for the specified URI scheme.
A descendant for the specific URI scheme.
The URI that identifies the Internet resource.
0
Method
1.0.5000.0
2.0.0.0
4.0.0.0
System.Net.WebRequest
is .
The request scheme specified in is not registered.
The caller does not have permission to connect to the requested URI or a URI that the request is redirected to.
Requires permission to connect to the requested URI. See .
The method returns a descendant of the class determined at run time as the closest registered match for .
For example, if you create a descendant, Handler1, to handle requests to http://www.contoso.com/text/ and another named Handler2 to handle requests to http://www.contoso.com/code/, you can use method to return the WebRequest descendant associated with either specified URI.
To return a descendant of the class based on only the scheme portion of a URI, use the method.
For example, when a URI beginning with http:// or https:// is passed in , an is returned by . If a URI beginning with ftp:// is passed instead, the method will return a instance. If a URI beginning with file:// is passed instead, the method will return a instance.
The pre-registered reserve types already registered include the following:
-
http://
-
https://
-
ftp://
-
file://
The .NET Framework includes support for the http://, https://, ftp://, and file:// URI schemes. Custom descendants to handle other requests are registered with the method.
This member outputs trace information when you enable network tracing in your application. For more information, see [<topic://conUsingNetworkTracing>].
Initializes a new instance for the specified URI scheme.
A descendant for the specified URI scheme.
A containing the URI of the requested resource.
0
Method
1.0.5000.0
2.0.0.0
4.0.0.0
System.Net.WebRequest
is .
The request scheme specified in is not registered.
The caller does not have permission to connect to the requested URI or a URI that the request is redirected to.
Requires permission to connect to the requested URI. See .
This example demonstrates the use of the and methods.
using System;
using System.Net;
public class ContosoTextRequest : WebRequest, IWebRequestCreate
{
public new WebRequest Create(Uri uri)
{
return new ContosoTextRequest();
}
}
public class CreateDefaultExample
{
public static void Main()
{
ContosoTextRequest contoso = new ContosoTextRequest();
Uri contosoUri = new Uri("http://www.contoso.com/text");
WebRequest.RegisterPrefix("http://www.contoso.com/text", contoso);
WebRequest httpContoso = WebRequest.CreateDefault(contosoUri);
Console.WriteLine("CreateDefault --> {0}", httpContoso);
WebRequest textContoso = WebRequest.Create(contosoUri);
Console.WriteLine("Create --> {0}", textContoso);
}
}
The output is
CreateDefault --> System.Net.HttpWebRequest
Create -->
ContosoTextRequest
The method returns a descendant instance based on only the scheme portion of a URI.
For example, when a URI beginning with http:// is passed in , an is returned by . If a URI beginning with file:// is passed instead, the method will return a .
This member outputs trace information when you enable network tracing in your application. For more information, see [<topic://conUsingNetworkTracing>].
Initializes a new instance for the specified URI scheme.
A descendant for the specified URI scheme.
A containing the URI of the requested resource.
0
Method
4.0.0.0
System.MonoTODO("for portable library support")
System.Net.HttpWebRequest
The method returns an instance of the class for the .
When a URI that begins with http:// or http:// is passed in the parameter, a is returned by . Another other scheme will throw an .
The method uses the parameter to create a instance that it passes to the new . If the method is successful, the property on the returned instance is set to false.
The .NET Framework includes support for the http:// and https:// URI schemes. Custom descendants to handle other requests are registered with the method. The method can be used to create a descendant of the class for other schemes.
Initializes a new instance for the specified URI string.
Returns .
An instance for the specific URI string.
A URI string that identifies the Internet resource.
Method
4.0.0.0
System.MonoTODO("for portable library support")
System.Net.HttpWebRequest
The method returns an instance of the class for the .
When a URI that begins with http:// or http:// is passed in the parameter, an is returned by . Another other scheme will throw a .
The method uses the parameter to create a new instance. If the method is successful, the property on the returned instance is set to false.
The .NET Framework includes support for the http:// and https:// URI schemes. Custom descendants to handle other requests are registered with the method. The method can be used to create a descendant of the class for other schemes.
Initializes a new instance for the specified URI.
Returns .
An instance for the specific URI string.
A URI that identifies the Internet resource.
Property
1.0.5000.0
2.0.0.0
4.0.0.0
System.Net.ICredentials
A object containing the authentication credentials
associated with the request. The default is .
This property is not implemented in the derived class.
The property contains the authentication credentials required to access the Internet resource.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, gets or sets the network credentials used for authenticating the request with the Internet resource.
0
Property
2.0.0.0
4.0.0.0
System.Net.Cache.RequestCachePolicy
To be added.
This policy is used for this request if the following conditions exist:
-
There is no property specified for this request.
-
The machine and application configuration files do not specify a cache policy that is applicable to the Uniform Resource Identifier (URI) used to create this request.
The cache policy determines whether the requested resource can be taken from a cache instead of sending the request to the resource host computer.
A copy of a resource is only added to the cache if the response stream for the resource is retrieved and read to the end of the stream. So another request for the same resource could use a cached copy, depending on the cache policy level for this request.
Gets or sets the default cache policy for this request.
Property
2.0.0.0
4.0.0.0
System.Net.IWebProxy
To be added.
The property gets or sets the global proxy. The property determines the default proxy that all instances use if the request supports proxies and no proxy is set explicitly using the property. Proxies are currently supported by and .
The property reads proxy settings from the app.config file. If there is no config file, the current user's Internet Explorer (IE) proxy settings are used.
If the property is set to null, all subsequent instances of the class created by the or methods do not have a proxy.
Gets or sets the global HTTP proxy.
Method
1.0.5000.0
2.0.0.0
4.0.0.0
System.IO.Stream
This method is not overridden in the derived class.
was not returned by a call to .
is a null reference.
This method was called previously using
-or-
No stream is available.
An error occurred while processing the request.
The method completes an asynchronous stream request that was started by the method.
To avoid timing issues with garbage collection, be sure to close the response stream by calling the method on the stream returned by after calling .
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, returns a for writing data to the Internet resource.
A to write data to.
An that references a pending request for a stream.
0
Method
1.0.5000.0
2.0.0.0
4.0.0.0
System.Net.WebResponse
This method is not overridden in the derived class.
was not returned by a call to .
is a null reference.
The property of the current instance is greater than zero but no data has been written to the request stream.
-or-
This method was called previously using
An error occurred while processing the request.
The method completes an asynchronous request for an Internet resource that was started with the method.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, returns a .
A that contains a response to the Internet request.
An that references a pending request for a response.
0
Method
2.0.0.0
4.0.0.0
System.Void
Any objects included in the are automatically tracked and serialized by the formatter.
Populates a with the data needed to serialize the target object.
The to populate with data.
A that specifies the destination for this serialization.
Method
1.0.5000.0
2.0.0.0
4.0.0.0
System.IO.Stream
This method is not overridden in the derived class.
The method initiates a request to send data to the Internet resource and returns a instance for sending data to the Internet resource.
The method provides synchronous access to the . For asynchronous access, use the and methods.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, returns a for writing data to the Internet resource.
A for writing data to the Internet resource.
0
Method
4.0.0.0
System.Threading.Tasks.Task<System.IO.Stream>
This operation will not block. The returned object will complete when the for writing data to the Internet resource is available.
When overridden in a descendant class, returns a for writing data to the Internet resource as an asynchronous operation.
Returns .
The task object representing the asynchronous operation.
Method
1.0.5000.0
2.0.0.0
4.0.0.0
System.Net.WebResponse
This method is not overridden in the derived class.
The request timed out.
-or-
An error occurred while processing the request.
The method sends a request to an Internet resource and returns a instance. If the request has already been initiated by a call to , the method completes the request and returns any response.
The method provides synchronous access to the . For asynchronous access, use the and methods.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
If a WebException is thrown, use the and properties of the exception to determine the response from the server.
When overridden in a descendant class, returns a response to an Internet request.
A containing the response to the Internet request.
0
Method
4.0.0.0
System.Threading.Tasks.Task<System.Net.WebResponse>
This operation will not block. The returned object will complete after a response to an Internet request is available.
When overridden in a descendant class, returns a response to an Internet request as an asynchronous operation.
Returns .
The task object representing the asynchronous operation.
Method
2.0.0.0
4.0.0.0
System.MonoTODO("Look in other places for proxy config info")
System.Net.IWebProxy
method reads the current user's Internet Explorer (IE) proxy settings. This process includes the IE options to automatically detect proxy settings, use an automatic configuration script, manual proxy server settings, and advanced manual proxy server settings.
If your application is impersonating several users, you can use the method to retrieve a proxy for each impersonated user.
Returns a proxy configured with the Internet Explorer settings of the currently impersonated user.
An used by every call to instances of .
Property
1.0.5000.0
2.0.0.0
4.0.0.0
System.Net.WebHeaderCollection
A containing the header name/value pairs associated
with the current instance.
This property is not implemented in the derived class.
The property contains a instance containing the header information to send to the Internet resource.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, gets or sets the collection of header name/value pairs associated with the request.
0
Property
2.0.0.0
4.0.0.0
System.Security.Principal.TokenImpersonationLevel
To be added.
The impersonation level determines how the server can use the client's credentials.
Gets or sets the impersonation level for the current request.
Property
1.0.5000.0
2.0.0.0
4.0.0.0
System.String
A containing the protocol method to use in the current instance.
This property is not implemented in the derived class.
When overridden in a descendant class, the property contains the request method to use in this request.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, gets or sets the protocol method to use in this request.
0
Property
1.0.5000.0
2.0.0.0
4.0.0.0
System.Boolean
if
authentication information will be
sent with the current request without waiting for an authentication challenge
from
the requested resource;
otherwise, .
This property is not implemented in the derived class.
With the exception of the first request, the property indicates whether to send authentication information with subsequent requests without waiting to be challenged by the server. When is false, the waits for an authentication challenge before sending authentication information.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, indicates whether to pre-authenticate the request.
0
Property
1.0.5000.0
2.0.0.0
4.0.0.0
System.Net.IWebProxy
A to use to access resources.
This property is not implemented in the derived class.
The property identifies the network proxy that the request uses to access the Internet resource. The request is made through the proxy server rather than directly to the Internet resource.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, gets or sets the network proxy to use to access this Internet resource.
0
Method
1.0.5000.0
2.0.0.0
4.0.0.0
System.Boolean
is or
is .
The following example demonstrates how to register a new
scheme.
using System;
using System.Net;
public class ftpWebRequest : WebRequest {
//implement ftp-specific protocol methods and properties
}
public class ftpCreator : IWebRequestCreate
{
public WebRequest Create(Uri uri)
{
return new ftpWebRequest();
}
}
public class RegisterPrefixExample
{
public static void Main()
{
ftpCreator creator = new ftpCreator();
WebRequest.RegisterPrefix("ftp://", creator);
WebRequest wr = WebRequest.Create("ftp://testFile");
Console.WriteLine(wr);
}
}
The output is
ftpWebRequest
The method registers descendants to service requests. descendants are typically registered to handle a specific protocol, such HTTP or FTP, but can be registered to handle a request to a specific server or path on a server.
The pre-registered reserve types already registered include the following:
-
http://
-
https://
-
ftp://
-
file://
For more information, see the and methods.
Duplicate prefixes are not allowed. returns false if an attempt is made to register a duplicate prefix.
The class is registered to service requests for HTTP and HTTPS schemes by default. Attempts to register a different descendant for these schemes will fail.
Registers a descendant for the specified URI.
true if registration is successful; otherwise, false.
The complete URI or URI prefix that the descendant services.
The create method that the calls to create the descendant.
0
Property
1.0.5000.0
2.0.0.0
4.0.0.0
System.Uri
A containing the URI
of
the resource associated with the current instance
This property is not implemented in the derived class.
When overridden in a descendant class, the property contains the instance that method uses to create the request.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
When overridden in a descendant class, gets the URI of the Internet resource associated with the request.
0
Method
1.0.5000.0
2.0.0.0
4.0.0.0
System.Void
To be added.
When overridden in a descendant class, populates a instance with the data needed to serialize the .
A , which holds the serialized data for the .
A that contains the destination of the serialized stream associated with the new .
Property
1.0.5000.0
2.0.0.0
4.0.0.0
System.Int32
A containing the length of time, in milliseconds, before the current request
will time out, or to indicate that the request does not time out.
This property is not implemented in the derived class.
The property indicates the length of time, in milliseconds, until the request times out and throws a . The property affects only synchronous requests made with the method. To time out asynchronous requests, use the method.
The class is an abstract class. The actual behavior of instances at run time is determined by the descendant class returned by the method. For more information about default values and exceptions, see the documentation for the descendant classes, such as and .
Gets or sets the length of time, in milliseconds, before the request times out.
0
Property
2.0.0.0
4.0.0.0
System.Boolean
To be added.
Set this property to true when requests made by this object should, if requested by the server, be authenticated using the credentials of the currently logged on user. For client applications, this is the desired behavior in most scenarios. For middle tier applications, such as ASP.NET applications, instead of using this property, you would typically set the property to the credentials of the client on whose behalf the request is made.
When overridden in a descendant class, gets or sets a value that controls whether are sent with requests.
0