Development Tutorial: Extensibility: Adding a table display/edit method and showing it on a form in PU11

In my previous post I described the capabilities of the Dynamics 365 FOE platform update 10, when it comes to working with display/edit methods.

In Platform Update 11 a few improvements came out, which I will describe below (with an example).

Let's use the same example as in my previous post, and add a new display method showing the internal product name for a selected product - we'll compose it by appending some text to the product search name.

Step 1 - Create a table extension and add a new display method to it - New recommended approach

All the approaches described in the previous post are still applicable, but are, in my opinion, not as intuitive as the below, so I'd recommend to always use the below approach.

[ExtensionOf(tableStr(EcoResProduct))]
public final class MyPU11_EcoResProductExtensionOfTable_Extension
{
    [SysClientCacheDataMethod]
    public display Name myInternalProductName()
    {
        return "PU11: " + this.SearchName;
    }

    // This is same as in PU10
    [SysClientCacheDataMethod]
    public static display Name myInternalProductNameStatic(EcoResProduct _ecoResProduct)
    {
        return "PU11 static: " + _ecoResProduct.SearchName;
    }
}
K/code>

OK, so what do we have here?
A simple instance method, no redundant arguments, access to table fields and methods through this.
Just as with overlayering, there's really no difference.

Note. The logic of the method is not really important - you'd have your fields used here, most probably, but for the sake of the example I just use SearchName field.

Step 2 - Add the method to a form through a table field group

So now let's see another thing, which was not possible before PU11.

Let's create an extension for the metadata changes of the EcoResProduct table, and add a new Field Group. After that we'll put our new display method in it, as shown below.

Select the new display method as the source for the new field group field.

As you can see from the image above, you can now use the drop-down, and it will show you all the display/edit methods created in Extension/Augmentation classes as well as the standard ones.

The syntax is the same as described last time:

• :: for static methods
• . for instance methods (new)

All that's left is to add the new field group onto a form.

Step 3 - Add the methods to a form through extension

Same as before, we create a form extension, and add the new fields to it.

With field groups it is as easy as with overlayering - you can just drag and drop the new field group from the DataSources\EcoResProduct node onto the Design of the form, and it will create the new group and sub-controls, and set the appropriate properties on them, as shown below:

Add new field group onto the form extension

As easy as that.

You can also add the fields bound to the new display methods directly, as shown before. Except now you can also use the instance display/edit methods, which wasn't available earlier.

Add an instance extension display method to a form

Limitations

• The drop-down for display methods does not show the extension methods, as with field groups. This should be addressed in one of the upcoming updates.
• You are still not able to declare the display method on the form itself, or on the form data source.

Conclusion

Some last words: The future is bright! :) 

The tooling is getting better with every release, and thanks to the monthly updates and binary compatibility of the releases, new innovation from Microsoft is just a month away!

Links

You can download the project from the example from my OneDrive.

To review the list of features included in Platform update 11, see the What's new or changed topic and refer to the KB article for details about the customer found bug fixes included in this update.

Development Tutorial: Extensibility: Adding a table display/edit method and showing it on a form in PU10

One of the super common tasks for an application developer working to address customer requirements is adding display methods showing some additional customer-specific information on existing forms.

Usually you would overlayer the corresponding table and form and insert the missing method. Overlayering is not an option soon, however it is possible to do the same using only Extensions.

As an example, let us add a new display method showing the internal product name for a selected product - we'll compose it by appending some text to the product search name.

Step 1 - Create a table extension and add a new display method to it - Option 1

As you know, there are two ways to create extension classes now, so let's see both ways in action.
Here we'll look at the "old" way, where we create an actual extension class (as in .NET), so it must be static, and the display method must be static as well, and take the record as the first argument.

Here's how it looks for my example:

/// 

/// Extension class for EcoResProduct table.
/// 
public static class MyPU10_EcoResProductTable_Extension
{
    [SysClientCacheDataMethod]
    public static display Name myInternalProductName(EcoResProduct _ecoResProduct)
    {
        return 'IntName: ' + strReplace(_ecoResProduct.SearchName, ' ', '');
    }
}

As you can see, we can define the above method and it will compile even though normally declaring a static display method is not allowed by the compiler.
We can also decorate the method with attribute, like I have done here by applying the display method caching attribute.
The logic of the method is not really important - you'd have your fields used here, most probably, but for the sake of the example I just use SearchName field.

Step 2 - Create a table extension and add a new display method to it - Option 2

So, another "new" way to extend a table is through an augmentation class, using the ExtensionOf attribute. This is shown below for my example:

/// 

/// Extension class for EcoResProduct table.
/// 
[ExtensionOf(tableStr(EcoResProduct))]
final class MyPU10_EcoResProductExtensionOfTable_Extension
{
    public static display Name myInternalProductName(EcoResProduct _ecoResProduct)
    {
        return "Alt: " + _ecoResProduct.SearchName;
    }
}

As you can see, this again is a static method - declaring it as an instance method will compile and would allow you to reference the record through this, but you will not be able to use it as a display method on the form as of today.
The method also needs to take the record as the argument.
It, of course, can also be decorated with the SysClientCacheDataMethod attribute, as in the first example.

Step 3 - Add the methods to a form through extension

Note - Limitation

You cannot as of today add the newly created display methods to a field group on the table. It will compile, but the control will not show up on the form if you add the field group to it.

First off, we'll need to create an extension of the EcoResProductDetails form in the desired model.

Then we'll add a new tab page to it and place two new String controls into it.

Now, the trick is with how to specify the display method name in Properties.

See the example below:

Specify properties for form string control to bind it to a table data method

As you can see, the trick is to specify the full name, including the class name and the method name with the static method delimiter in the format:

<class name>::<static method name>

This is only supported for table methods, so you won't be able to do the same for a Form Data Source, for example.

Result

Here's how our new awesome display methods look at run-time:

Additional information shown through display methods on Product details form

Download the project

You can download it from my OneDrive here.

What's next

In an upcoming platform update we hope to provide a much more intuitive way of adding display methods, however the above approach will keep being supported.

Stay tuned for an update!

Development Tutorial: FormObservable or how to handle display methods in the new Dynamics AX

In the new Dynamics AX the approach to how display/edit methods are refreshed by the kernel has changed to much less aggressive, meaning that after migrating your application to the latest version you might find that after opening the form the data is correct, but after performing actions and editing data the display/edit methods data is not refreshed.

This blog post is going to explain, how to handle such cases now.

I want to stress the importance of reading about this, since this is completely new (among many other things) in AX '7', and without full understanding of these mechanics you will not be able to write efficient and correctly working user interface code.

To summarize, here's a quick set of rules:

• If your display method depends on form state or some data event, you might need to use one of the following two approaches:
• The FormObservable attribute to flag an existing form or class variable
• A new variable of the type FormObservableLink
• If your display method depends on another data source, you might need to use the following approach:
• The datasource.observe() method

As you can see from the names of these types, they are relying on the Observer pattern, subscribing to notifications about data changes, so as to invoke the refresh of the display/edit method data.


When I decided to finally write this blog post, I found out there's already somebody who beat me to it, so instead of repeating the same, here's a link, where you can read in more detail about each of the 3 above options:

FormObservable in Dynamics AX7

Enjoy, and kudos to the author of that blog.

Tutorial: Caching display methods

Overview

Caching is an important part of the Microsoft Dynamics AX application. It allows us to significantly speed up certain processes by avoiding redundant round trips to the server and the database. Display/Edit methods are a good example of where caching is helpful, as it significantly increases the overall responsiveness of a form.
In AX 2012 R3 there are a number of ways you can specify that a display method needs to be cached. Below is a list, as well as a brief description and an xpo with a tutorial form to show the various options.

• Invoke cacheAddMethod(MethodName) in the init() method of the data source

This is the only option that was available in older versions of Dynamics AX.
All cached data methods are calculated and cached in executeQuery of the data source they belong to. That is why it is important to call the above method in the init() of the data source, once the data source is initialized, but the data hasn't been retrieved yet. The optional second parameter controls whether or not the display method value should be refreshed when data is written to DB

• Add the SysClientCacheDataMethodAttribute attribute on the display method

Now that attributes are available, caching a display method is as easy as adding an attribute on the method. It has an optional parameter same as the above method. Note, that marking a display method with this attribute will mean that it is cached on all forms the method is used on. So make sure that is what you want to happen before adding it.

• Set the “Cache data method” property on the display method form control to Yes

This is, again, a new capability in the latest version of AX, that is pretty much identical to calling the cacheAddMethod, just much easier.

• Set the “Cache data method” property on the display method form control to Auto, where the data source is read-only

Now, this is something that is done automatically by the kernel. If the data source which the display method belongs too is read-only, and Cache data method property on the corresponding control is set to Auto, the kernel will cache this method. This is smart, as the value can’t really change. You can still change the property to No, if there’s a reason why you want the display method not to be cached.

Additional info

On top of the above, I would also like to mention a few other things.

• There are 2 kernel-defined methods, called titleFields and parentTitleFields, which are always being cached automatically by the kernel. The titleFields method corresponds to the 2 Title Fields that you can set on the table level. Then, if you have this table as your TitleDatasource on the form design, the 2 fields selected will be shown in the caption of the form. parentTitleFields is very similar, only it displays the title fields of the parent data source table, which is relevant in a header-lines (dynalinked datasources) kind of scenario. As a fallback, it shows the titleFields.
• There are methods for managing the cached methods, one of them being cacheCalculateMethod, which asks the server to re-calculate the method value and update the cache for the current record. Note that it will only take effect if the method has previously been cached. In the tutorial project I am using this method in the form method runHack to refresh the value of 2 of the display methods. 

Example

You can download the xpo project with the tutorial from my OneDrive.
Upon opening the form in the project, some data will be pulled into the form. More specifically, the first 3 items/customers/vendors/sites/warehouses. For each of them a display method is present, and one of the above approaches is used to cache it.

Step 1

None of the display methods are cached. As you can see, nothing extra was done in executeQuery of the main data source, but itemName was cached for all 3 records for the read-only data source, as the control has "Cache data method" property set to Auto. This happens even though the tab page is not the active one, so it wasn't really yet necessary to calculate these values. Maybe the user won't even navigate to that tab page. You should consider this carefully when designing a form, and always aim at increasing the overall responsiveness of a form by only executing the appropriate display methods.

Step 2 and 3

inventSiteName and vendName were cached (through one of the options above). As you can see, now their values are calculated once for each of the records shown. InventLocationName and custName are still not cached.
Clicking on Refresh result button will show any extra calls to the display methods since the form started. As you’ll quickly notice, the non-cached methods are being called every time something hints at covering up the value of the control, or rather every time AX thinks it needs to recalculate the value, which is VERY OFTEN. That should make it pretty clear how useful caching is for display methods.

Step 4

Now inventLocationName was also cached, and the only method that is remaining and not cached is custName. You can see how more and more methods are executed in one batch on the server as part of the executeQuery method on the data source.

Step 5

As the last step, I have added 2 standalone controls that show the Title fields of the main data source table, and started logging the time method caption is invoked. As I have written above, titleFields and parentTitleFields are cached automatically, but you can't really see it, as it is not possible to override it. caption is the closest you can get to it, so I figured it's worth showing that. You can see the method is evaluated right after all data source queries have executed (as it relies on the currently selected record). It is evaluated first time based on the selected data source record, and then again when focus actually goes to the grid, so that the first record is explicitly selected. It will be invoked again whenever the active record changes. Note that unlike custName method, it does not get constantly refreshed.

Play around with the form and let me know if you have any questions or comments.
Thanks