MorphX is used for developing and debugging data and business tier components, defining navigation elements, storing unified metadata and files, importing and deploying controls, storing page and list definitions, and generating proxies.

For Enterprise Portal data access purposes, the new programmable object Data Sets is added to the AOT. Data Sets in Enterprise Portal are equivalent to the Form data source for the Desktop form. You can create Data Sets with one or more joined data sources pointing to related tables in Dynamics AX. You can override or add new methods in data sets, data sources, and tables as well as define the data access logic.

You generally define the business logic in classes in the AOT. These classes are referenced either in the data set or through C# proxy classes in the presentation components in Enterprise Portal.

You can generate proxy classes either from Visual Studio or from MorphX (ToolsDevelopment ToolsWeb DevelopmentProxies). The tables and classes from which proxy files need to be generated are defined in AOTWebWeb FilesStatic FilesProxies. Web-related components are stored under AOTWeb.

The Web User Controls for the presentation tier that you develop in Visual Studio are added to the AOT under AOTWebWeb FilesWeb Controls. These controls are referenced and secured by AOTWeb ContentManaged Nodes. The Visual Studio add-in for Dynamics AX lets you add the controls from Visual Studio to the AOT directly.

Static files that Enterprise Portal uses, such as style sheets, configuration files, and aspx files, are kept under AOTWeb FilesStatic Files. Images and resources are kept at AOTResources.

The pages and lists you create in Windows SharePoint Services are exported to the AOT and stored under AOTWebWeb FilesPage Definitions and AOTWebWeb FilesList Definitions.

Enterprise Portal Web parts site definitions are kept under AOTWebWeb FilesWeb Parts and AOTWebWeb FilesSite Definitions. The Site Templates node is for any customized Windows SharePoint Services templates.

For Web sites, consistent navigation is important for users to perform their tasks quickly and easily. Site navigation in Enterprise Portal consists of a global menu bar that is displayed at the top of the site, the module-level QuickLaunch navigation, which is on the left side, and toolbars that are inside the page.

Web modules define the site hierarchy and the top-level navigation. Web menus define the menu hierarchy used by the Dynamics QuickLaunch Web part or the toolbar. Web menu items that point to the page or class are used in Web menus.

You develop and debug presentation-tier components in Visual Studio. The Visual Studio add-in for Enterprise Portal provides a project and control template for Web user interface development. You define all the user interface logic in Web User Controls using Enterprise Portal development tools, and you use the Enterprise Portal framework to access data and metadata for ASP.NET controls. The Visual Studio add-in also provides an easy way to add controls to the AOT, import controls or style sheets from the AOT, and generate proxies. It also provides a test page for previewing the user interface and debugging.

You use Windows SharePoint Services to develop Web part pages or lists and to edit master pages, which contain the common elements for all the pages. You can use the Create or Edit Page tools of Windows SharePoint Services in the browser and use one or more Enterprise Portal or any Web parts and design your Web page. You can also use the Microsoft Office SharePoint Designer 2007 tool to create or edit Web part pages or master pages.

Data sets you create in the AOT are exposed to ASP.NET through the AxDataSource control. AxDataSource abstracts the data store and the operations that can be performed on the data, from connecting to or reading/writing from the data store. You can associate ASP.NET data-bound user interface controls with AxDataSource through the DataSourceID property. Using this standard ASP.NET data binding, you can rapidly develop user interface logic without needing specific domain knowledge about how to connect to or access data from Dynamics AX. Because AxDataSource takes care of the data access from Dynamics AX, developers don’t have to worry about data access and can focus on the business aspect.

The data source control is simply a container for one or more uniquely named views (AxDataSourceView). All the logic is encapsulated in this DataSourceView-derived class. AxDataSourceView implements all the functionality to read and write data. The data-bound control can identify the set of enabled capabilities and display the right set of user interface controls and enable or disable them. You use the DataMember property of a data-bound control to select a particular view. AxDataSourceView maps to the data set view. So for each dynamic data set view based on the number of data sources and the type of join, you get an equivalent number of AxDataSourceView in the AxDataSource control to which any data-bound control can bind.

The data source control also supports filtering records within and across other data source controls and data source views. When you set the active record on the data source view within a data source control, all the child data source views are also filtered based on the active record. You can filter across data source controls through Record Context. In Record Context, one data source control acts as the provider of the context, and zero or more data source controls act as consumers. One data source can act as both provider and consumer. When the active record changes on the provider data source control, the record context is passed to other consuming data source controls, and they apply that filter as well. You use the Role and ProviderView properties of AxDataSource for this purpose. One Web User Control can contain any number of AxDataSource controls. Only one of them can have the property Role set to Provider. Any number of them can be set to Consumer.

You can use the DataSetViewRow object to access the rows in a DataSetView. The GetCurrent method returns the current row.

DataSetViewRow row = this.AxDataSource1.GetDataSourceView("View1").DataSetView.
GetCurrent();

The GetDataSet method on AxDataSourceControl specifies the data set to bind. The DataSetRun property provides the run-time instance of the data set, and you can use AxaptaObjectAdapter to call the methods. So to invoke methods defined in data sets from a Web User Control, you would use the following code.

this.AxDataSource1.GetDataSet().DataSetRun.AxaptaObjectAdapter.Call("method1");

The AxGridView control displays the values of a data source in a table format in which each column represents a field and each row represents a record. With AxGridView, you can select, sort, group, expand, filter, edit, and delete items. AxGridView extends the ASP.NET GridView control and lets you provide selection, grouping, expansion rows, filtering, context menus, and other enhanced capabilities within the Dynamics AX Enterprise Portal user interface.

AxGridView also includes built-in data modification capabilities. Using AxGridView with the declarative AxDataSource, you can easily configure and modify data without writing a single line of code. AxGridView also has many properties, methods, and events that you can easily customize with application-specific user interface logic.

You can find the full set of properties, methods, and events for GridView and AxGridView on MSDN. Listed here are some of the AxGridView properties you’ll likely use most often:

Figure 7-6 shows a sample list page with the filter control and context menu set.

Figure 7-6. Enterprise Portal list page with filter control and context menu

The ContextMenu object also allows you to add menu items and separators at run time. It provides methods to remove menu items and resolve client or Enterprise Portal URLs. You can access the ContextMenu object from AxGridview.ContextMenu.

ActionMenuItemClicked, ActionMenuItemClicking, and SetMenuItemProperties are three ContextMenu events.

SelectedIndexChanged, DataBound, and Row* events are AxGridView events for which you commonly write code to specify actions to take when the selection is changed, to inspect and change styles when data is rendered, and to react when rows are modified, respectively.

If the ShowFilter property of AxGridview is set to true, AxGridView embeds AxFilterControl. AxFilterControl is displayed at the top of AxGridView. AxFilterControl reads the metadata from the AxDataSourceControl the AxGridView is binding to and displays controls dynamically to allow the user to filter the data source with any of its field that are not hidden or locked. You can access the filter control through the AxGridView FilterControl property and the filter XML through Filter.

The filter control sets the filter on AxDataSetView using AxDataSourceView, which is responsible for keeping the data in sync with the filter set by calling SetAsChanged and ExecuteQuery if data has changed. AxDataSourceView and DataSetView expose the SystemFilter and UserFilter properties and the ResetUserFilter method APIs for the filter control to set the filter programmatically.

For example, you can set the range in the data set in X++ as follows.

qbrBlocked = qbds.addRange(fieldnum(CustTable,Blocked));qbrBlocked.value(queryValue-
(CustVendorBlocked::No));qbrBlocked.status(RangeStatus::Hidden);

In the Web User Control, you can read the SystemFilter set on the data source.

this.AxDataSource1.GetDataSourceView(this.AxGridView1.DataMember).SystemFilter.ToXml()

or

this.AxDataSource1.GetDataSet().DataSetViews[this.AxGridView1.DataMember].
SystemFilter.ToXml();

returns

<?xml version="1.0" encoding="utf-16"?><filter xmlns:xsi="http://www.w3.org/2001/
XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="CustTable">-
<condition attribute="Blocked" operator="eq" value="No" status="hidden" /></filter>

DataSourceView and DataSetView have the following methods, which allow you to read the different types of filters and reset them.

Here is a code snippet to set the filter programmatically.

this.AxDataSource1.GetDataSourceView(this.AxGridView1.DataMember).SystemFilter.AddXml-
(@"<filter name='CustTable'><condition attribute='CustGroup' status='open' value='10'
operator='eq' /></filter>");

AxForm displays a single record from a data source, where each data row represents a field in the record. The first column in the row often displays the name of the field, and the second column displays the value of the field for the record. The AxForm control allows you to view, create, and update a single record.

AxForm is a data-bound control with built-in data modification capabilities. When you use AxForm with the declarative AxDataSource control, you can easily configure it to display and modify data without needing to write any code. It also provides a rich set of properties, methods, and events you can customize with application-specific user interface logic.

The DataSourceID, DataMember, and DataKeyNames properties define the data-binding capabilities of the AxForm control. AxForm also provides properties to autogenerate action buttons, setting their text and the mode. You set the UpdateOnPostback property if you want the record cursor to be updated at post back so that other controls can read the change. AxForm also provides events for all the actions that can be taken on the form before and after that action is completed. You can write code in these events for user interface or application-specific logic before or after the action is completed.

The AxForm control is a container for a collection of controls. If your form contains many fields and requires visually grouping the related fields, allowing them to be expanded or collapsed, you use the AxMultiSection control inside the AxForm control. If your form is simple and has only a few fields, you can use the AxGroup control.

AxMultiSection allows you to define a collection of AxSection controls, where each AxSection control contains child controls. By default, all sections are in expanded mode and rendered vertically, one after the other. Users can keep any number of them in expanded or collapsed mode. You can also configure AxMultiSection so that only one section is expanded at any point. In this mode, expanding a second section causes the first one to collapse, keeping just one section active. Set the ActiveMode property to true to enable that behavior. You use the ActiveSectionIndex property to get or set the active section. The AxMultiSection component can contain only AxSection components.

AxSection is a generic control container. Any control can be a child of AxSection. All AxSection controls are rendered vertically, one after the other. Each AxSection includes a header that contains the title of the section and an image button that allows the user to expand or collapse the section. AxSection provides properties to display or hide the header and border. You can also set a security key on AxSection so that it’s visible only to users who have access to that security key in Dynamics AX. You can also write code when the section is expanded or collapsed through the events exposed by AxSection.

The AxGroup control contains the bound fields collection that displays the record information. You add AxGroup controls as descendents of AxSection controls. Typically, the immediate child of an AxSection control is a table control or an HTML table with AxGroup controls within the table cells. Figure 7-7 shows a sample task page in Enterprise Portal.

Figure 7-7. An Enterprise Portal task page with section and group controls

Following are some high-level control hierarchies for different form layouts.

Here is a form with a list of fields that are displayed one below the other.

<AxForm>
    <AxGroup><Fields>BoundFields or TemplateFields...</Fields> </AxGroup>
</AxForm>

This form has two expandable sections, with fields displayed one below the other.

<AxForm>
    <AxMultiSection>
        <AxSection>
              <AXGroup><Fields>BoundFields or TemplateFields...</Fields> </AxGroup>
        </AxSection>
        <AxSection>
              <AxGroup><Fields>BoundFields or TemplateFields...</Fields> </AxGroup>
              <AxGroup><Fields>BoundFields or TemplateFields...</Fields> </AxGroup>
        </AxSection>
    </AxMultiSection>
</AxForm>

The following form has two expandable sections, with fields displayed one below the other. In the second section, the groups are displayed in two columns.

<AxForm >
    <AXMultiSection>
        <AxSection>
            <AXGroup><Fields>BoundFields or TemplateFields...</Fields> </AXGroup>
        </AXSection>    <AxSection>
            <table>
                <tr><td>
                    <AXGroup><Fields>BoundFields or TemplateFields...</Fields> </AXGroup>
                </td><td>
                    <AXGroup><Fields>BoundFields or TemplateFields...</Fields> </AXGroup>
                </td></tr>
            </table>
        </AXSection>
    </AxMultiSection>
</AxForm>

Here is a wizard with two steps.

<AxForm>
    <asp:Wizard>
        <asp:WizardSteps>
            <asp:WizardStep>
                <AXGroup><Fields>BoundFields or TemplateFields...</Fields> </AXGroup>
            </asp:WizardStep>
           <asp:WizardStep>
                <AXGroup><Fields>BoundFields or TemplateFields...</Fields> </AXGroup>
            </asp:WizardStep>
        </asp:WizardSteps>
    </asp:Wizard>
</AxForm>

AxLookup is used in data entry pages to help the user pick a valid value for a field that references keys from other tables. In Enterprise Portal, lookups are metadata driven by default and are automatically enabled for fields based on the relationship defined in metadata in the AOT. An example is the customer group lookup on the customer creation page. The extended data type (EDT) and table relationship metadata in the AOT define a relationship between the customer table and the customer group table, so a lookup is rendered to pick a customer group on the customer group field when creating a customer record. You don’t need to write any code to enable this behavior—it happens automatically.

In some application scenarios, however, the automatic behavior isn’t sufficient, and you might be required to customize the lookup. The lookup infrastructure of Enterprise Portal is designed to offer flexibility and customization options in both X++ and in C# for developers to tailor the lookup user interface and the data retrieval logic to their needs.

In the AOT Data Set node, you can override the dataSetLookup method of the field in the data source to control the lookup behavior. For example, if you want to filter the values displayed for a zip code field based on what has been entered for a country, state, or county, you override dataSetLookup, as shown in the following code.

void dataSetLookup(SysDataSetLookup sysDataSetLookup)
{
    ;
    if (custTable.CountryRegionId)
sysDataSetLookup.parmQuery().dataSourceNo(1).addRange(
fieldnum(AddressZipCode,CountryRegionId)).value(queryValue(
custTable.CountryRegionId));
    if (custTable.State)
sysDataSetLookup.parmQuery().dataSourceNo(1).addRange(
fieldnum(AddressZipCode,State)).value(queryValue(custTable.State));
    if (custTable.County)
sysDataSetLookup.parmQuery().dataSourceNo(1).addRange(
fieldnum(AddressZipCode,County)).value(queryValue(custTable.County));
}

In the preceding example, addRange is used to restrict the value. For some scenarios, you might want to build the entire list dynamically. In that case, you can override the dataSetLookup method and build the entire query yourself.

...
...

Query               query;
List                _list;
_list = new List(Types::String);
query = new Query();
query.addDataSource(tablenum(ReturnReasonCode));
_list.addEnd(fieldstr(ReturnReasonCode,ReasonCodeId));
_list.addEnd(fieldstr(ReturnReasonCode,ReasonCodeGroupId));
_list.addEnd(fieldstr(ReturnReasonCode,Description));
sysDataSetLookup.parmLookupFields(_list);
sysDataSetLookup.parmQuery(query);
...
...

SysDataSetLookup in X++ provides many properties and methods to control the behavior of the lookup.

You can also customize the lookup in C# in the Web User Control by writing code in the Lookup event of bound fields or by using the AxLookup control for fields that don’t have data binding. To use AxLookup to provide lookup values for any ASP.NET control that isn’t data bound, you should set the TargetControlID property of the AxLookup to the ASP.NET control. You can base AxLookup on the EDT, the data set, the custom data set, or the custom User Control by specifying the LookupType property. You can also control what fields are displayed in the lookup and which one is a select field, either through the markup or through code. You can write code to override the Lookup event and control the lookup behavior, as shown in the following code.

protected void AxLookup1_Lookup(object sender, AxLookupEventArgs e)
    {
        AxLookup lookup = (AxLookup)sender;
        // Specify the lookup fields
        lookup.Fields.Add(AxBoundFieldFactory.Create(this.AxSession, lookup.
LookupDataSetViewMetadata.ViewFields["CustGroup"]));
        lookup.Fields.Add(AxBoundFieldFactory.Create(this.AxSession, lookup.
LookupDataSetViewMetadata.ViewFields["Name"]));
}

The AxToolbar control provides an intuitive and consistent way to organize and display functions that the user performs frequently on your application’s Web pages. Typically, toolbars are displayed at the top of the page or grid control. AxToolbar extends the Windows SharePoint Services toolbar controls. AxToolbarMenu, used within AxToolbar, is derived from Microsoft.SharePoint.WebControls.Menu. The AxToolbar control is used to render a toolbar button with a drop-down menu that is rendered when the menu is clicked via a callback. In other words, AxToolbarMenu lets you modify the menu item properties before the menu items are rendered.

AxToolbarButton, used within the AxToolbar control, is derived from SPLinkButton. It is used to render top-level buttons.

Depending on your application, you can use either the AxToolbar ASP.NET control or the Dynamics Toolbar Web part to display the toolbar menu items on top of the list, overview, or task page. Generally, you use the Dynamics Toolbar Web part to control the display of toolbar menu items. But if you have a task page that contains master/detail information, such as a Purchase Requisition header and line items, you should use the AxToolbar ASP.NET control inside your Web User Control above the detail AxGridview control to allow the user to add and manage the line items.

You can use AxToolbar bound to AxDataSource or as an unbound control. When the controls are bound, the menu item context is automatically based on the current item selected on the grid view. When the controls are unbound, you have to write code to manage the toolbar context.

You can point the toolbar to Web Menus in the AOT through the WebMenuName property. The AOT Web Menus allow you to define multilevel menu structure with the SubMenu, MenuItem, and MenuItem reference nodes. Each top-level submenu in a Web menu is rendered by the AxToolbar control using AxToolbarMenu as a drop-down menu. Each top-level menu item is rendered using AxToolbarButton as a link button. If you have a submenu within a submenu, the second and further levels are displayed as flyout menus.

SetMenuItemProperties, ActionMenuItemClicking, and ActionMenuItemClicked are AxToolbar control-specific events. You use SetMenuItemProperties to change the behavior of drop-down menus, such as showing or hiding menu items based on the currently selected record, setting or removing context, and so on. An example of changing the menu item context in the SetMenuItemProperties event is shown in the following code.

void Webpart_SetMenuItemProperties(object sender, SetMenuItemPropertiesEventArgs e)
    {
        // Do not pass the currently selected customer record context, since this menu
is for creating new (query string should be empty)
     if (e.MenuItem.MenuItemAOTName == "EPCustTableCreate")
              ((AxUrlMenuItem)e.MenuItem).MenuItemContext = null;
    }

If you have user interface logic defined in a Web User Control and want to call this function instead of the one defined in the AOT when a toolbar item is clicked, you use ActionMenuItemClicking and ActionMenuItemClicked. For example, you can prevent the menu item from executing the action defined in the AOT by using the ActionMenuItemClicking event and defining your own action in C# using the ActionMenuItemClicked event in the Web User Control, as shown here.

void webpart_ActionMenuItemClicking(object sender, ActionMenuItemClickingEventArgs e)
    {
        if (e.MenuItem.MenuItemAOTName.ToLower() == "EPCustTableDelete")
        {
            e.RunMenuItem = false;
        }
    }
    void webpart_ActionMenuItemClicked(object sender, ActionMenuItemEventArgs e)
    {
   if (e.MenuItem.MenuItemAOTName.ToLower() == "EPCustTableDelete")
        {
                int selectedIndex = this.AxGridView1.SelectedIndex;
                if (selectedIndex != -1)
                {
                    this.AxGridView1.DeleteRow(selectedIndex);
                }
        }
    }

AxPopup controls are used to open a page in a pop-up browser window, to close a popup page, and to pass data from the pop-up page back to the parent page and trigger an OnPopupClosed server event on the parent. This functionality is encapsulated in two controls: AxPopupParentControl to use on the parent page and AxPopupChildControl to use on the pop-up page. Both controls derive from AxPopupBaseControl. These controls are AJAX compatible, so you can create them conditionally as part of a partial update. AxPopupParentControl allows a page, typically a Web part page, to open in a pop-up window. You can open a pop-up window from a client-side script by using the GetOpenPopupEventReference method. The returned string is a JavaScript statement that can be assigned, for example, to a button’s onclick attribute or to a toolbar menu item. The following code shows how a developer can open a pop-up window using client-side scripting by modifying the OnClick event.

  protected void SetPopupWindowToMenuItem(SetMenuItemPropertiesEventArgs e)
  {
      AxUrlMenuItem menuItem = new AxUrlMenuItem("EPCustTableCreate");
     //Calling the JavaScript function to set the properties of opening Web page on
clicking the menuitems.
        e.MenuItem.ClientOnClickScript = this.AxPopupParentControl1.GetOpenPopupEventR
eference(menuItem);
    }

You can also open a pop-up window from a server method by calling the OpenPopup method. Because pop-up blockers can block server-initiated pop-up windows, use OpenPopup only when absolutely necessary, for example, when only the server code can decide whether a pop-up window needs to be opened.

When placed on a pop-up page, AxPopupChildControl allows the page to close. You can close the pop-up page from a client-side script by using the GetClosePopupEventReference method, as shown in the following example.

this.BtnOk.Attributes.Add("onclick",
this.popupChild.GetClosePopupEventReference(true, true) + "; return false;");

You can close a pop-up window from the server event by using the ClosePopup method. Use the server method when additional processing is needed upon closing, such as performing an action or calculating values to be passed back to the parent page. There are two parameters to the ClosePopup and OpenPopup methods:

Data can be passed from the pop-up page back to the parent page using AxPopupField objects. You expose these objects via the Fields property of the AxPopupBaseControl, from which both AxPopupParentControl and AxPopupChildControl are derived.

AxPopupParentControl and AxPopupChildControl have fields with the same names. When the pop-up page closes, the value of each field of AxPopupChildControl is assigned (via a client-side script) to the corresponding field in AxPopupParentControl.

AxPopupField can optionally be associated with another control, such as TextBox or any other control, by assigning its TargetId property to the ID property of the target control. This is useful, for example, when the pop-up page has a TextBox control. To pass the user input to the parent page upon closing the pop-up page—and to do it entirely on the client to avoid a round-trip—you need to associate a field with the TextBox control. When AxPopupField isn’t explicitly associated with a target control, it gets implicitly associated with a HiddenField control automatically created by AxPopupParentControl or AxPopupChildControl.

You can then set the value of the field on the server via the SetFieldValue method. Typically, you call SetFieldValue on AxPopupChildControl, and you can call it at any point of user interaction with the pop-up page, including the initial rendering or the closing of the page. The value of the field can be retrieved via the GetFieldValue method. Typically, it is called on AxPopupParentControl during the processing of the PopupClosed event. You can clear the values of nonassociated fields by calling the ClearFieldValues method.

You can also set or retrieve values of AxPopupFields on the client by manipulating the target control value. You can retrieve target control, whether explicitly or implicitly associated, by using the TargetControl property.

BoundField controls are used by data-bound controls (such as AxGridView, AxGroup, ASP.NET GridView, and DetailsView) to display the value of a field through data binding. They are displayed differently depending on the data-bound control in which they are used. For example, the AxGridView control displays a BoundField object as a column, whereas the AxGroup control displays it as a row.

The Enterprise Portal framework provides a number of enhanced AxBoundField controls that are derived from ASP.NET-bound field controls but integrated with the Dynamics AX metadata.

Table 7-1 describes the AxBoundField controls.

Depending on the field type, BoundFieldDesigner automatically groups fields under the correct BoundField type. The BoundField type displays text that allows you to control the lookup behavior through the LookupButtonDisplaySettings property and the lookup event.

Web parts are pluggable and reusable Windows SharePoint Services components that generate HTML and provide the foundation for the modular presentation of data. Web parts are easily integrated to assemble a Web page and support customization and personalization. Enterprise Portal comes with a standard set of Web parts, including the following, that expose the business data from Dynamics AX:

Figure 7-8 shows the Add Web Parts dialog box in Enterprise Portal.

Figure 7-8. Add Web Parts dialog box in Enterprise Portal

ASP.NET AJAX allows the developer to create ASP.NET Web pages that can update data on the Web page without completely reloading the page. ASP.NET AJAX provides client-side and server-side components that use the XMLHttpRequest object along with JavaScript and DHTML to enable portions of the page to update asynchronously, again without reloading the entire page. With ASP.NET AJAX, you can develop Enterprise Portal Web pages, just as you would any regular ASP.NET page, and you can declaratively mark the components that need to be rendered asynchronously.

Using the UpdatePanel server control, you can enable sections of the Web page to be partially rerendered without an entire page postback. The Dynamics User Control Web part contains the UpdatePanel internally, and ScriptLibrary is included in the master page, so any control that you use in the Web User Control instantly leverages AJAX without you needing to write any explicit markup or code.

For example, if you add a text box and button, writing code for the button’s click event on the server, without AJAX, when you click the button, the entire page refreshes. But when you load the same control through the Dynamics User Control Web part, it leverages AJAX and updates the text box without refreshing the entire page.

<asp:TextBox ID="TextBox1" runat="server"></asp:TextBox><asp:Button ID="Button1"
runat="server" onclick="Button1_Click" Text="Button" />

And in the code-behind, update the text box with the current time after 5 seconds.

protected void Button1_Click(object sender, EventArgs e)
    {
     System.Threading.Thread.Sleep(5000);
     TextBox1.Text = System.DateTime.Now.ToShortTimeString();
    }

If you want to override the AJAX behavior and force a full postback, you can use the PostBackTrigger control in your Web User Control, as shown here.

<%@ Register assembly="System.Web.Extensions, Version=3.5.0.0, Culture=neutral, PublicK
eyToken=31bf3856ad364e35" Namespace="System.Web.UI" TagPrefix="asp" %>
<asp:UpdatePanel ID="UpdatePanel1" runat="server">
    <ContentTemplate>
        <asp:TextBox ID="TextBox1" runat="server"></asp:TextBox>
        <asp:Button ID="Button1" runat="server" onclick="Button1_Click" Text="Button" />
    </ContentTemplate>
    <Triggers>
        <asp:PostBackTrigger ControlID="Button1" />
    </Triggers>
</asp:UpdatePanel>

All the Web parts in a Web page share the same session in Dynamics AX. Once the page is served, the session is torn down. To optimize performance, you can control the time frame for tearing down the session through a web.config setting. For example, add the Microsoft.Dynamics sectionGroup to web.config as in the following code.

<sectionGroup name="Microsoft.Dynamics">
<section name="Session" type="System.Configuration.SingleTagSectionHandler, System,
Version=1.0.5000.0, Culture=neutral,PublicKeyToken=b77a5c561934e089" />
</sectionGroup>

Add the <Microsoft.Dynamics> element under </system.web> and then add the following text to the file.

<Microsoft.Dynamics>
     <Session Timeout="15" />
</Microsoft.Dynamics>

Many of the methods you use in the Enterprise Portal framework to add code to User Controls require access to the Session object. You need to pass the Session object when using proxy classes. You can access the Session object through the Web part hosting the User Control, as shown here.

AxBaseWebPart webpart = AxBaseWebPart.GetWebpart(this);
return webpart == null ? null : webpart.Session;

Context is a data structure used to share data related to the current environment and user actions taking place with different parts of a Web application. Context lets you know what’s happening in one control so you can react to it via another control or Web part, or pass that information to a new page. Generally, information about the current record the user is working on forms the context. For example, when the user selects a row in a grid view, other controls might need to get information about the newly selected row to react.

AxContext is an abstract class that encapsulates the concept of the context. AxTableContext and AxViewContext derive from and implement AxContext. AxTableContext is for table-based context, and AxViewContext is for data set view context. A view can contain more than one table, so it contains an AxTableContext object for each table in the view in the TableContextList collection. The RootTableContext property returns the TableContext of the root table in that data set view. AxViewDataKey uniquely identifies the AxViewContext, and it contains the TableDataKeys collection. AxTableDataKey uniquely identifies AxTableContext. An event is raised whenever the context changes. If the context is changed within the Web User Control, the CurrentContextChanged event is raised. If the context changes from other Web parts that are connected to it, the ExternalContextChanged event is raised.

You can write code in these events on the AxBaseWebPart from your Web User Control and use the CurrentContextProviderView or ExternalContextProviderView and ExternalRecord properties to get the record associated with the context. You can fire all these events programmatically from your application logic by calling FireCurrentContextChanged or FireExternalContextChanged so that all other connected controls could react to the change you made through your code.

Following is sample code to fire the CurrentContextChanged event.

void CurrentContextProviderView_ListChanged(object sender, System.ComponentModel.
ListChangedEventArgs e)
    {
/* The current row (which is the current context) has changed -
 update the consumer webparts.Fire the current context change event to refresh
 (re-execute the query) the consumer webparts
*/
AxBaseWebPart webpart = this.WebPart;
webpart.FireCurrentContextChanged();
   }

Sample code for getting the record from the connected Web part follows. First subscribe to the ExternalContextChanged event in the consumer Web User Control, as here.

protected void Page_Load(object sender, EventArgs e)
    {
   //Add Event handler for the ExternalContextChange event. Whenever selecting
//the grid of the provider Web part changes, this event gets fired.

        (AxBaseWebPart.GetWebpart(this)).ExternalContextChanged += new
EventHandler<Microsoft.Dynamics.Framework.Portal.UI.AxExternalContextChangedEventArgs>
(AxContextConsumer_ExternalContextChanged);
}

Then get the record passed through the external context, as shown here.

    void AxContextConsumer_ExternalContextChanged(object sender, Microsoft.Dynamics.
Framework.Portal.UI.AxExternalContextChangedEventArgs e)
    {
        //Get the AxTableContext from the ExternalContext passed through web part
connection and construct the record object
        //and get to the value of the fields
        IAxaptaRecordAdapter currentRecord = (AxBaseWebPart.GetWebpart(this)).
ExternalRecord;
        {
   if (currentRecord != null)
            {
   lblCustomer.Text = (string)currentRecord.GetField("Name");
            }
        }
    }

The Enterprise Portal ASP.NET controls access and manipulate data through data binding to AxDataSource. You can also access the data through the APIs directly. The Microsoft.Dynamics.Framework.Data.Ax namespace contains several classes that work together to retrieve data.

For example, use the following code to get the current row from the DataSetView.

private DataSetViewRow CurrentRow
    {
        get
        {
            try
            {
                DataSetView dsv = this.ContactInfoDS.GetDataSet().DataSetViews[this.
ContactInfoGrid.DataMember];
                return (dsv == null) ? null : dsv.GetCurrent();
            }
            // CurrentRow on the dataset throws exception in empty data scenarios
            catch (System.Exception)
            {
                return null;
            }
        }
    }

To set the menu item with the current records context, use the following code.

...
...
DataSetViewRow currentContact = this.dsEPVendTableInfo.GetDataSourceView(gridConatcts.
DataMember).DataSetView.
GetCurrent();
     using (IAxaptaRecordAdapter contactPersonRecord = currentContact.GetRecord())
                {
   ((AxUrlMenuItem)e.MenuItem).MenuItemContext = AxTableContext.Create(AxTableDataKey.
Create(this.BaseWebpart.Session, contactPersonRecord, null));
                }

The Enterprise Portal framework provides a rich set of APIs to access the metadata from the AOT in managed code. The Microsoft.Dynamics.Framework.Metadata.Ax namespace contains several classes that work together to retrieve metadata from the AOT. Enterprise Portal controls use the metadata for retrieving formatting, validation, security, and other information from the AOT and apply it on the Web user interface automatically. Developers can also use these APIs to retrieve the metadata in their user interface logic.

MetadataCache is the main entry point to accessing metadata and provides static methods. For example, to get the EnumMetadata, you use MetadataCache.GetEnumMetadata, as shown here.

/// <summary>
/// Loads the dropdown with the Enum values.
/// </summary>
private void LoadDropdownList()
    {
   EnumMetadata salesUpdateEnum = MetadataCache.GetEnumMetadata(this.AxSession,
EnumMetadata.EnumNum(this.AxSession, "SalesUpdate"));
        foreach (EnumEntryMetadata entry in salesUpdateEnum.EnumEntries)
        {
   ddlSelectionUpdate.Items.Add(new ListItem(entry.GetLabel(this.AxSession), entry.
Value.ToString()));
        }
    }

To get the label value for a table field, use the following code.

...
...
TableMetadata tableSalesQuotationBasketLine = MetadataCache.GetTableMetadata(
                            this.AxSession, "CustTable");
TableFieldMetadata fieldItemMetadata = tableSalesQuotationBasketLine.FindDataField-
("AccountNum");
String s = fieldItemMetadata.GetLabel(this.AxSession);
...
...

Figure 7-9 shows some key object access hierarchy for metadata. Not all APIs are included in this figure.

Figure 7-9. Metadata object hierarchy

Dynamics AX uses a localizable text resource file, the label file, to provide messages to the user and for user interface text, Help text in the status bar, captions, and so on. You can use labels to specify the user interface text in Web User Controls and for the AOT Web node element properties. You can add labels by setting the Label property in the AOT or by using X++ code.

When you use data-bound controls such as AxGridView or AxForm for the user interface, the bound fields automatically pick the label associated with the field in the AOT and render it in the user’s language at run time.

If you want to show a label in your Web User Control for non-data-bound scenarios, use the AxLabel expression.

AxLabel is a standard ASP.NET expression that looks up the labels defined in the AOT and renders them in the user’s language when the page is rendered. To add the AxLabel expression, you can use the expression editor available in the design view of the User Control by clicking the button that appears on the (Expressions) property. Alternatively, you can type the expression directly in the markup, like this.

<asp:Button runat="server" ID="ButtonChange" Text="<%$ AxLabel:@SYS70959 %>"
OnClick="ButtonChange_Click" />

You can also add labels through code using the Labels class, as shown here.

string s = Microsoft.Dynamics.Framework.Portal.UI.Labels.GetLabel("@SYS111587");

Enterprise Portal caches the labels for all 41 languages for better performance. So if you add or change a label in the AOT, you need to clear the cache on the Enterprise Portal site by using the Refresh AOD admin option.

Dynamics AX is a truly global product, supporting multiple languages and used in many countries. Displaying data in the correct format for each localized version is a critical requirement for any global product. Through metadata, the Enterprise Portal framework recognizes the user’s current locale and system settings and automatically displays data in the correct format in the data-bound controls.

If you’re not using data-bound controls and want your unbound ASP.NET controls to be formatted just like Enterprise Portal controls, you can leverage the AxValueFormatter class in the Enterprise Portal framework. This class implements ICustomFormatter and the IFormatProvider interface and defines a method that supports custom, user-defined formatting of an object’s value and provides a mechanism for retrieving an object to control formatting. For the various data types, specific ValueFormatter classes derived from AxValueFormatter are implemented: AxStringValueFormatter, AxDateValueFormatter, AxDateTimeValueFormatter, AxTimeValueFormatter, AxRealValueFormatter, AxNumberValueFormatter, AxGuidValueFormatter, and AxEnumValueFormatter.

You use AxValueFormatterFactory to create AxValueFormatter objects. You can create any of the preceding formatters, or you can create a formatter based on an EDT in Dynamics AX. The data type for the extended data is retrieved from the metadata object for the EDT, and the culture information comes from the context. The various rules for languages and countries, such as number formats, currency symbols, and sort orders, are aggregated into a number of standard cultures. The Enterprise Portal framework identifies the culture based on the user’s language setting in Dynamics AX and makes this information available in the context. Formatter objects have a Parse method you can use to convert a string value back into the underlying data type. For example, the following code formats the data based on a given EDT.

private string ToEDTFormattedString(object data, string edtDataType)
    {
   ExtendedDataTypeMetadata edtType = MetadataCache.GetExtendedDataTypeMetadata(
            this.AxSession,
            ExtendedDataTypeMetadata.TypeNum(this.AxSession, edtDataType)
        );
        IAxContext context = AxContextHelper.FindIAxContext(this);
        AxValueFormatter valueFormatter = AxValueFormatterFactory.
CreateFormatter(this.AxSession, edtType, context.CultureInfo);
        return valueFormatter.FormatValue(data);
    }Validation

You use ASP.NET validator controls to validate user input on the server as well as (optionally) on the client (browser). The Enterprise Portal framework has ASP.NET validators specific to Dynamics AX: AxBaseValidator derives from BaseValidator, and AxValueFormatValidator derives from AxBaseValidator. Both are metadata driven and are used intrinsically by bound fields, but you can also use them in unbound scenarios.

ASP.NET validators are automatically validated when a postback that causes validation occurs. For example, an ASP.NET Button control causes validation on the client and the server when clicked. All validators registered on the page are validated. If any validator is found to be invalid, the page becomes invalid, and Page.IsValid returns false.

The importance of Page.IsValid is best highlighted with an example. Let’s say you add an ASP.NET button in which some business logic is performed in OnClick before it is redirected. As mentioned, the button causes validation by default, so validators are executed before the OnClick event is fired. If you don’t check whether the page is valid in your OnClick, you will be redirected even though a validation error that requires the user’s attention occurs.

Enterprise Portal controls such as AxForm and AxGridView won’t perform the requested action if validation fails and navigates away from the page. The Dynamics AX validator controls automatically write any validation errors to the Infolog.

Best Practices

When you’re using ASP.NET controls directly rather than using Enterprise Portal controls, as a best practice, make sure the Pages.IsValid flag is checked before any actions, such as navigating away from the current page, are completed. You want to do this because, in case any errors occur, you want to keep the current page with Infolog displaying the errors for the users so that they will notice them and take corrective action.

In Enterprise Portal, .NET Business Connector (including proxies), the metadata, and the data layer all throw exceptions in case of error conditions. The Enterprise Portal ASP.NET controls automatically handle these exceptions, taking appropriate actions and displaying the errors in Infolog.

Exceptions in Enterprise Portal are divided into three categories. These exception categories are defined in the enumeration AxExceptionCategory:

If your code directly calls methods in data or metadata layers from Enterprise Portal or with proxy class calling X++ methods, it must handle these exceptions. The following code shows how to use AxControlExceptionHandler in the try-catch statement to handle exceptions.

Try
{
    // Code that may encounter exceptions goes here.
}
catch (System.Exception ex)
{   AxExceptionCategory exceptionCategory;
    // Determine whether the exception can be handled.
    if (AxControlExceptionHandler.TryHandleException(this, ex, out exceptionCategory)
== false)
    {
        // The exception was fatal and cannot be handled. Rethrow it.
        throw;
    }
    if (exceptionCategory == AxExceptionCategory.NonFatal)
    {
   // Application code to properly respond to the exception goes here.
    }
}

AxControlExceptionHandler tries to handle Dynamics AX exceptions based on the three exception categories just mentioned. It returns true if the exception is NonFatal.

The Web is stateless, which means that each request for a page is treated as a new request, and no information is shared. When loaded, each ASP.NET page goes through a regular page life cycle, from initialization and page load onward. When a user interacts with the page, causing the need for the server to process some control events, ASP.NET posts the values of the form to the same page for processing the event on the server. A new instance of the Web page class is created each time the page is requested from the server. When postback happens, ASP.NET uses the ViewState feature to preserve the state of the page and controls so that any changes made to the page during the round-trip are not lost. The Enterprise Portal framework leverages this feature, and Enterprise Portal ASP.NET controls automatically save their state to ViewState. The ASP.NET page reads the view state and reinstates the page and control state in its regular page life cycle. So you don’t need to write any code to manage the state if you’re using Enterprise Portal controls. But if you want to persist any values in memory variables, you can write code to add or remove items from StateBag in ASP.NET. If you need to save the state of an X++ data set, you can use the pack and unpack design pattern to store the state, as shown here.

public int Counter
{
    get
     {
        Object counterObject = ViewState["Counter"];
        if (counterObject == null)
        {
            return 0;
        }
       return (int)counterObject;
     }
    set
     {
        ViewState["Counter"] = value;
    }
}

The Enterprise Portal framework uses the EPStateStore table in Dynamics AX to store the state of AxDataSourceControl. The states of all other controls are stored in the ASP.NET view state for added security. This storage is per user, and each user can read only his or her information. Writes and deletes are protected with AOS methods, and read is protected via code access permission.

When an Enterprise Portal page runs, it goes through a life cycle in which it performs a series of steps and raises events at various states so developers can write code to control the behavior of the page and its controls, create dynamic controls, and write user interface logic. Understanding the sequence of the page processing and events helps you write the user interface logic at the appropriate level.

If you need to call X++ classes or table methods or enums in your Web User Control, the Enterprise Portal framework provides an easy way of creating managed wrappers for these X++ objects and using them in your Web User Control. A proxy file internally wraps the .NET Business Connector calls and provides a simple, easy-to-use, typed interface for C# applications. The proxies file under WebWeb FilesStatic Files in the AOT contains information about all the X++ objects for which a proxy file needs to be generated. The proxy generation tool uses this file when the Enterprise Portal site is deployed. The proxy files are automatically created and deployed to the App_Code folder of the IIS Web site. Table 7-2 describes the various command line options for the proxy generator.

For example, to generate a proxy file for the SampleProxy class, add the following code to the WebWeb FilesStatic FilesProxies node in the AOT.

warn:2 /references+ /methods- /namespace:Microsoft.Dynamics.Portal.Application.Proxy

/class:SampleProxy
  /method:SampleProxy.sampleProxiesNoParameters
  /method:SampleProxy.sampleProxiesStaticMethod

The first line of the preceding code provides the generation options for the proxy file. The second line provides information about the X++ class for which the proxy file needs to be generated. When Enterprise Portal is deployed, a SampleProxy.cs is created; it contains two methods and is deployed to the App_Code folder of the IIS Web site.

From Visual Studio, you can right-click the App_Code folder in a Dynamics AX Web project and choose the Generate Proxies option. The Visual Studio add-in generates the proxy files defined in the Proxies file and adds them to the Visual Studio project.

To use the proxy from C# code in the Web User Controls, first add a using statement to the proxy namespace, like this.

using Microsoft.Dynamics.Portal.Application.Proxy;

Then you can access these X++ methods as if they were in C#. You can access some items in the proxy, such as enums, directly, without any additional code. Accessing methods from the proxy requires passing the IAxaptaAdapter object together with the method call. So you need to get the session and pass it to the constructor to create the C# proxy object, as shown here.

protected string NoParamProxyCall_Click(object sender, EventArgs e)
    {
        AxBaseWebPart webpart = AxBaseWebPart.GetWebpart(this);
        SampleProxy sampleProxy = null;
        sampleProxy = new SampleProxy(webpart.Session.AxaptaAdapter);
        string s = sampleProxy.sampleProxiesNoParameters();
        return s;
    }