HttpServerUtility.Transfer Method

Definition

Namespace:

System.Web

Assembly:

System.Web.dll

Terminates execution of the current page and starts execution of a new page for the current request.

Overloads

Transfer(String)	For the current request, terminates execution of the current page and starts execution of a new page by using the specified URL path of the page.
Transfer(String, Boolean)	Terminates execution of the current page and starts execution of a new page by using the specified URL path of the page. Specifies whether to clear the QueryString and Form collections.
Transfer(IHttpHandler, Boolean)	Terminates execution of the current page and starts execution of a new request by using a custom HTTP handler that implements the IHttpHandler interface and specifies whether to clear the QueryString and Form collections.

Transfer(String)

For the current request, terminates execution of the current page and starts execution of a new page by using the specified URL path of the page.

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

public void Transfer (string path);

member this.Transfer : string -> unit

Public Sub Transfer (path As String)

Parameters

path

String

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

Remarks

The page transferred to should be another .aspx page. For instance, a transfer to an .asp or .asmx page is not valid. The Transfer method preserves the QueryString and Form collections.

Transfer calls End, which throws a ThreadAbortException exception upon completion.

ASP.NET does not verify that the current user is authorized to view the resource delivered by the Transfer method. Although the ASP.NET authorization and authentication logic runs before the original resource handler is called, ASP.NET directly calls the handler indicated by the Transfer method and does not rerun authentication and authorization logic for the new resource. If your application's security policy requires clients to have appropriate authorization to access the resource, the application should force reauthorization or provide a custom access-control mechanism.

You can force reauthorization by using the Redirect method instead of the Transfer method. The Redirect method performs a client-side redirect in which the browser requests the new resource. Because this redirect is a new request entering the system, it is subjected to all the authentication and authorization logic of both Internet Information Services (IIS) and ASP.NET security policy.

You can verify that the user has permission to view the resource by incorporating a custom authorization method that uses the IsInRole method before the application calls the Transfer method.

Transfer(String, Boolean)

Terminates execution of the current page and starts execution of a new page by using the specified URL path of the page. Specifies whether to clear the QueryString and Form collections.

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

public void Transfer (string path, bool preserveForm);

member this.Transfer : string * bool -> unit

Public Sub Transfer (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 QueryString and Form collections; false to clear the QueryString and Form collections.

Exceptions

ApplicationException

The current page request is a callback.

Examples

The following example executes a new page in the same directory as the current page.

Server.Transfer("Logon.aspx", true);

Server.Transfer("Logon.aspx", true)

Remarks

The page transferred to should be another .aspx page. For instance, a transfer to an .asp or .asmx page is not valid.

Transfer calls End, which throws a ThreadAbortException exception upon completion.

If you set the preserveForm parameter to true, the target page will be able to access the view state of the previous page by using the PreviousPage property.

For security purposes, you should keep the enableViewStateMac attribute set to true. ASP.NET does not verify that the current user is authorized to view the resource delivered by the Transfer method. Although the ASP.NET authorization and authentication logic runs before the original resource handler is called, ASP.NET directly calls the handler indicated by the Transfer method and does not rerun authentication and authorization logic for the new resource. If your application's security policy requires clients to have appropriate authorization to access the resource, the application should force reauthorization or provide a custom access-control mechanism.

You can force reauthorization by using the Redirect method instead of the Transfer method. The Redirect method performs a client-side redirect in which the browser requests the new resource. Because this redirect is a new request entering the system, it is subjected to all the authentication and authorization logic of both Internet Information Services (IIS) and ASP.NET security policy.

You can verify that the user has permission to view the resource by incorporating a custom authorization method that uses the IsInRole method before the application calls the Transfer method.

Transfer(IHttpHandler, Boolean)

Terminates execution of the current page and starts execution of a new request by using a custom HTTP handler that implements the IHttpHandler interface and specifies whether to clear the QueryString and Form collections.

public:
 void Transfer(System::Web::IHttpHandler ^ handler, bool preserveForm);

public void Transfer (System.Web.IHttpHandler handler, bool preserveForm);

member this.Transfer : System.Web.IHttpHandler * bool -> unit

Public Sub Transfer (handler As IHttpHandler, preserveForm As Boolean)

Parameters

handler

IHttpHandler

The HTTP handler that implements the IHttpHandler to transfer the current request to.

preserveForm

Boolean

true to preserve the QueryString and Form collections; false to clear the QueryString and Form collections.

Exceptions

ApplicationException

The current page request is a callback.

Remarks

You can write custom HTTP handlers to process specific, predefined types of HTTP requests in any language that is compliant with the Common Language Specification (CLS). Executable code that is defined in the HTTP handler classes instead of conventional ASP (also known as classic ASP) pages or ASP.NET pages responds to these specific requests. HTTP handlers allow for interacting with the low-level request and response services of a Web server that is running Internet Information Services (IIS), and they provide functionality that is similar to ISAPI extensions but with a simpler programming model.

If you set the preserveForm parameter to true, the target page will be able to access the view state of the previous page by using the PreviousPage property.

For security purposes, you should keep the enableViewStateMac attribute set to true. ASP.NET does not verify that the current user is authorized to view the resource delivered by the Transfer method. Although the ASP.NET authorization and authentication logic runs before the original resource handler is called, ASP.NET directly calls the handler indicated by the Transfer method, and does not rerun authentication and authorization logic for the new resource. If the security policy for your application requires clients to have appropriate authorization to access the resource, the application should force reauthorization or provide a custom access-control mechanism.

You can force reauthorization by using the Redirect method instead of the Transfer method. The Redirect method performs a client-side redirect in which the browser requests the new resource. Because this redirect is a new request entering the system, it is subjected to all the authentication and authorization logic of both the IIS and ASP.NET security policy.

You can verify that the user has permission to view the resource by incorporating a custom authorization method that uses the IsInRole method before the application calls the Transfer method.