HttpServerUtility.TransferRequest Method

Definition

Namespace:

System.Web

Assembly:

System.Web.dll

Performs an asynchronous execution of the specified URL.

Overloads

TransferRequest(String)	Performs an asynchronous execution of the specified URL.
TransferRequest(String, Boolean)	Performs an asynchronous execution of the specified URL and preserves query string parameters.
TransferRequest(String, Boolean, String, NameValueCollection)	Performs an asynchronous execution of the specified URL using the specified HTTP method and headers.
TransferRequest(String, Boolean, String, NameValueCollection, Boolean)	Performs an asynchronous execution of the specified URL using the specified HTTP method, headers, and path, and optionally preserves form values and the user identity.

Remarks

TransferRequest was introduced in the .NET Framework version 3.5. For summary information about the .NET Framework, see Versions and Dependencies.

TransferRequest(String)

Performs an asynchronous execution of the specified URL.

public:
 void TransferRequest(System::String ^ path);

public void TransferRequest (string path);

member this.TransferRequest : string -> unit

Public Sub TransferRequest (path As String)

Parameters

path

String

The URL path of the new page on the server to execute.

Exceptions

PlatformNotSupportedException

The request requires the integrated pipeline mode of IIS 7.0.

HttpException

The server is not available to handle the request.

ArgumentNullException

The path parameter is null.

ArgumentException

The path parameter is invalid.

Remarks

This method overload calls the TransferRequest overload with the preserveForm parameter set to false, the method parameter set to null, the headers parameter set to null, and the preserveUser parameter set to true. For more information, see the "Remarks" section in TransferRequest(String, Boolean, String, NameValueCollection) overload.

TransferRequest(String, Boolean)

Performs an asynchronous execution of the specified URL and preserves query string parameters.

public:
 void TransferRequest(System::String ^ path, bool preserveForm);

public void TransferRequest (string path, bool preserveForm);

member this.TransferRequest : string * bool -> unit

Public Sub TransferRequest (path As String, preserveForm As Boolean)

Parameters

path

String

The URL path of the new page on the server to execute.

preserveForm

Boolean

true to preserve the Form collection; false to clear the Form collection.

Exceptions

PlatformNotSupportedException

The request requires the integrated pipeline mode of IIS 7.0.

HttpException

The server is not available to handle the request.

ArgumentNullException

The path parameter is null.

ArgumentException

The path parameter is invalid.

Remarks

This overload calls the TransferRequest overload with the preserveForm parameter set to the value passed in, the method parameter set to null, the headers parameter set to null, and the preserveUser parameter set to true. For more information, see the "Remarks" section in TransferRequest(String, Boolean, String, NameValueCollection).

TransferRequest is introduced in the .NET Framework version 3.5. For more information, see Versions and Dependencies.

TransferRequest(String, Boolean, String, NameValueCollection)

Performs an asynchronous execution of the specified URL using the specified HTTP method and headers.

public:
 void TransferRequest(System::String ^ path, bool preserveForm, System::String ^ method, System::Collections::Specialized::NameValueCollection ^ headers);

public void TransferRequest (string path, bool preserveForm, string method, System.Collections.Specialized.NameValueCollection headers);

member this.TransferRequest : string * bool * string * System.Collections.Specialized.NameValueCollection -> unit

Public Sub TransferRequest (path As String, preserveForm As Boolean, method As String, headers As NameValueCollection)

Parameters

path

String

The URL path of the new page on the server to execute.

preserveForm

Boolean

true to preserve the Form collection; false to clear the Form collection.

method

String

The HTTP method to use in the execution of the new request.

headers

NameValueCollection

A NameValueCollection of request headers for the new request.

Exceptions

PlatformNotSupportedException

The request requires IIS 7.0 running in integrated mode.

HttpException

The server is not available to handle the request.

ArgumentNullException

The path parameter is null.

ArgumentException

The path parameter is invalid.

Remarks

This method is used when running with the integrated pipeline mode in IIS 7.0 to allow request processing to be transferred from one resource type to another while executing the target request with the correct request context. For example, you can use the TransferRequest method to transfer a request for an ASPX page to a request for an XML page.

The TransferRequest method performs an asynchronous child execution of the specified URL with the following conditions:

• If the path parameter specifies a query string, it will be used as the new query string. If no query string is included, the query string of the request will be re-used.

• If the method parameter is specified, it will be used. If it is null, the HTTP method of the original request will be used.

• If the preserveForm parameter is true, the current entity body of the request will be available to the target request. This allows form posts and uploads to be transferred.

• If the user identity is currently set on the original request, the identity will be transferred to the new request. This allows authenticated requests to re-use the result of the authentication for the new request. If you do not want the user to be transferred, set the user to null on the original request before transferring.

• If the headers parameter is specified, the new request will execute with the specified headers. This can be used to modify the request headers and cookies for the new request, or add a special header that specifies where the original request was received.

  This method calls the TransferRequest(String, Boolean, String, NameValueCollection, Boolean) method overload with the preserveUser parameter set to true.

TransferRequest(String, Boolean, String, NameValueCollection, Boolean)

Performs an asynchronous execution of the specified URL using the specified HTTP method, headers, and path, and optionally preserves form values and the user identity.

public:
 void TransferRequest(System::String ^ path, bool preserveForm, System::String ^ method, System::Collections::Specialized::NameValueCollection ^ headers, bool preserveUser);

public void TransferRequest (string path, bool preserveForm, string method, System.Collections.Specialized.NameValueCollection headers, bool preserveUser);

member this.TransferRequest : string * bool * string * System.Collections.Specialized.NameValueCollection * bool -> unit

Public Sub TransferRequest (path As String, preserveForm As Boolean, method As String, headers As NameValueCollection, preserveUser As Boolean)

Parameters

path

String

The path.

preserveForm

Boolean

true to preserve the Form collection; false to clear the Form collection.

method

String

The HTTP method to use in the new request.

headers

NameValueCollection

A NameValueCollection object that contains request headers for the new request.

preserveUser

Boolean

true to preserve the user identity; otherwise, false. The other method overloads of this method call this overload with this parameter set to true.

Exceptions

PlatformNotSupportedException

The request requires the integrated pipeline mode of IIS 7.0.

HttpException

The server is not available to handle the request.

ArgumentNullException

The path parameter is null.

ArgumentException

The path parameter is invalid.

Remarks

For more information, see the "Remarks" section in TransferRequest(String, Boolean, String, NameValueCollection).