KB Article K18548
Visible to All Users

eXpressApp Framework 11.2 ASP.NET Application Migration Guidelines

Description:
With the v2011 vol2 release, ASP.NET templates have been improved to use AJAX-based rendering (refer to the Improvements to AJAX and Performance in XAF ASP.NET UI (coming in v2011 vol 2) blog post for more information). If you are using a custom template, or customizing templates/controls in code, you need to make certain changes to reflect improvements. This article describes the factors you need to account for.

Answer:
Note: For general guidelines on upgrading XAF ASP.NET applications, refer to the Upgrading eXpressApp Framework ASP.NET Applications section of the Upgrade Notes help topic.
1. Custom templates must wrap dynamically updated controls with XafUpdatePanels.
All dynamically updated controls should be placed into XafUpdatePanels. The XafUpdatePanel class is declared in the DevExpress.ExpressApp.Web.Templates namespace of the DevExpress.ExpressApp.Web.v11.2 assembly. So, you will need to add a corresponding @Register directive at the beginning of the template.
YourTemplate.aspx

XML
<%@ Register Assembly="DevExpress.ExpressApp.Web.v11.2" Namespace="DevExpress.ExpressApp.Web.Templates" TagPrefix="cc3" %>

Basically, everything beside the HTML markup must be wrapped with XafUpdatePanels. For example, in case of the standard Default.aspx template, the following controls must be wrapped.
ActionContainerHolder;
ErrorInfoControl;
NavigationHistoryActionContainer;
NavigationTabsActionContainer;
QuickAccessNavigationActionContainer;
ViewImageControl;
ViewSiteControl.
To form unique identifiers for the XafUpdatePanels, you can prefix a control identifier with "UP". The following code snippet illustrates this - a "SAC" ActionContainerHolder instance is wrapped with a "UPSAC" XafUpdatePanel instance.
Default.aspx

XML
<cc3:XafUpdatePanel ID="UPSAC" runat="server"> <cc2:ActionContainerHolder runat="server" ID="SAC" Categories="Security" ContainerStyle="Links" ImageTextStyle="CaptionAndImage" CssClass="Security" SeparatorHeight="23px" ShowSeparators="True" /> </cc3:XafUpdatePanel>

Note that when updating the nested frame control template containing a toolbar, the toolbat control must also be wrapped with XafUpdatePanel.

2. Do not rely on Page.PreRender and Control.PreRender events.
ASP.NET framework does not raise PreRender events when processing callback requests. XAF provides the WebWindow.PagePreRender event that is raised immediately before rendering. Handle this event instead of Page.PreRender and Control.PreRender events. For instance, if you have a custom Controller that customizes a control by handling its PreRender event, you need to handle the WebWindow.CurrentRequestWindow.PagePreRender event instead.
3. Do not rely on the Page.ClientScript property and ScriptManager.
Client scripts will not be executed if registered via a ClientScriptManager instance (Page.ClientScript property). To register client scripts, use the RegisterStartupScript, RegisterClientScript, RegisterClientScriptInclude and RegisterClientScriptResource methods exposed by the WebWindow class. So, for instance, if you have a custom Controller that registers client scripts via the Page.ClientScript property, change the registration code to use on of the mentioned methods.

C#
protected override void OnViewControlsCreated() { base.OnViewControlsCreated(); WebWindow.CurrentRequestWindow.RegisterClientScript(scriptKey, script); }

Take special note that it is important to remove the <SCRIPT/> tags from the registered script string.
4. Do not rely on ActionStateUpdateController.
ActionStateUpdateController is not used any more. All Action Containers are updated automatically on each callback request. So, for example, if you are updating a custom List Editor's context menu via ActionStateUpdateController, you can now simply customize the server-side control and it will be updated automatically on the client.
5. Use XafCallbackManager to handle control client-side events on the server via callbacks.
The XafCallbackManager class is declared in the DevExpress.ExpressApp.Web.Templates namespace of the DevExpress.ExpressApp.Web.v11.2 assembly. To handle client-side events, you must have a class implementing the IXafCallbackHandler interface declared alongside XafCallbackManager. The interface exposes a single ProcessAction method.

C#
public interface IXafCallbackHandler { void ProcessAction(string parameter); }

To register your handler, use the XafCallbackManager.RegisterHandler(string handlerId, IXafCallbackHandler handler) method. Assign a unique identifier to the handler via the handlerId parameter. To send callback requests from the client side, use the XafCallbackManager.GetScript(string handlerId, string parameter, string confirmation, bool usePostBack) method that returns a string that contains a script that sends a request. The string specified via the parameter argument will be passed to the IXafCallbackHandler.ProcessAction method of the handler specified via the handlerId parameter.
Refer to the following Support Center tickets for examples:
How to raise XAF CallBacks from client-side events
How to implement the drill-down functionality in Web PivotGrid (ASPxPivotGrid)
How to execute some action from the client side in XAF Web application
How to automatically refresh data in a View after a certain period of time on the Web
How to I provide keyboard shortcuts for certain XAF Actions in Web UI?
6. Set the IModelActionWeb.IsPostBackRequired property to true for Actions that should be executed on postback.
For instance, the built-in Export Action is executed on postback, because postback is required to transmit or download a file to client. It is impossible to call Response.End() and Response.Complete() on callback.

Disclaimer: The information provided on DevExpress.com and affiliated web properties (including the DevExpress Support Center) is provided "as is" without warranty of any kind. Developer Express Inc disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.

Confidential Information: Developer Express Inc does not wish to receive, will not act to procure, nor will it solicit, confidential or proprietary materials and information from you through the DevExpress Support Center or its web properties. Any and all materials or information divulged during chats, email communications, online discussions, Support Center tickets, or made available to Developer Express Inc in any manner will be deemed NOT to be confidential by Developer Express Inc. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.