Microsoft Dynamics Ax 2009 : Programming Enterprise Portal Controls (part 3) - Labels, Formatting, Error Handling

Labels

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.

Formatting

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.

Error Handling

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:

• NonFatal The exception handling code should respond appropriately and allow the request to continue normally.

• AxFatal Indicates that an unrecoverable error has occurred in Enterprise Portal. Enterprise Portal content will not display. Content not related to Enterprise Portal should display as expected.

• SystemFatal Indicates that a serious error, such as out of memory, has occurred and the request must be aborted. Errors of this kind often cause an HTTP error code 500.

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.