Add-Ins in Dynamics NAV 2013 (1#3) – Interfaces for data binding and the OnControlAddIn trigger
Introduction
With the arrival of Dynamics NAV 2013 later this year we will introduce a few improvements on our Client Add-In story which we believe will be a great productivity improvement for partners who are in the business of creating and shipping Add-Ins as part of their solutions and projects.
The new additions are found in the following areas, which each will be covered in it’s own blog post:
- Data binding through the Source Expression to more data types (covered in this blog post)
- Add-ins exposing custom interfaces to C/AL
- Improved layout support, upgrade support, current limitations,
Along the way I will provide my updated Add-in tools – the new Visual Studio Templates, Add-In registration tools and we will experiment with some new samples.
For the restless reader (“in a few words”)
NAV 2013 support data binding for all CAL data types by mapping CAL data to one of the .NET data types: Object, string, Boolean, Char, DateTime, Decimal, Guid, Int32, Int64, TimeSpan
Data binding and firing of the OnControlAddIn C/AL trigger are enabled by implementing respective Interfaces.
A set of new NAV 2013 templates for Visual Studio 2010 make it easy to create a Visual Studio project with add-ins with the selected binding and event support. (Find the templates for NAV 2009 here)
Data binding and eventing basics
Data binding with the SourceExpr of the field that holds the add-in has one great advantage: the data are transferred together with the other data on the page. You do not need to find the right place in C/AL triggers and write any code in order to exchange data with the add-in. The add-in will be updated automatically and changed data be saved like for all other fields.
(In a follow up post, I will talk about custom methods, properties and events exposed by the add-in in order to allow a very rich interaction on code level.)
Already in NAV 2009 R2 we had two interfaces to support data binding over the field’s source expression and eventing through the OnControlAddIn trigger in C/AL.
Please note: A valid add-in class is any class derived from the base class for the respective display target and optionally implements one or both of the interfaces IValueControlAddInDefinition<T> and IEventControlAddInDefinition.
The basic steps in the creation process of an add-in are:
- Use the base class for the display target – until now the WinForms based Windows RoleTailored client, which is the class WinFormsControlAddInBase.
- Add and implement the interface IValueControlAddInDefinition<T> for T being one one of the supported .NET types, in order for your AddIn to be able to exchange the data which the hosting field has been conned to though the C/AL property SourceExpr.
- Add and implement the interface IEventControlAddInDefinition if you like your AddIn to be able to fire the OnControlAddIn trigger in C/AL, which every field already has by default.
The addition in NAV 2013 is that now the data binding can be cover all most C/AL data types, not just Text types and Blob. for this purpose the set of data types supported when you implement the interface IValueControlAddInDefinition<T> has been increased to the following set of .NET data types: Object, string, Boolean, Char, Datetime, Decimal, Guid, Int32, Int64, Timespan
But watch out! If you dare to use a data type not in that list, you may very well experience an error like the following at runtime, when you try to load the add-in:
(Here I had created a class named ‘CooleKlasse’ and tried to use this when declaring the add-in class.)
In order to exchange a data for a data model maintained in a class over the Source Expression of a field, you should use an add-in that implements the interface IValueControlAddInDefinition<system.string>. Write a little code in C/AL and the add-in Value property getter / setter in order to serialize / de-serialize the data model to an from string.
Creating an add-in class with the Visual Studio 2010 templates for NAV 2013
The Templates for Visual Studio 2010 and the new Add-In Builder make it very easy to create a basic AddIn class:
Convenience interfaces in NAV 2013
Already in NAV 2009 R2 we had introduced a number of convenience interface and classes which combine above for typical use cases.
In NAV 2013 though we have completed the set C/AL data types an add-in bind to. For that purpose the below list of interfaces are ready to use in order to create an add-in that supports firing the OnControlAddIn trigger as well as binding from a C/AL data type to a corresponding .NET data type in the add-in code.
Interface |
Use |
IObjectControlAddInDefinition |
Event support and data binding with type System.Object maps to binary C/AL BLOB data |
IStringControlAddInDefinition |
Event support and data binding with type System.String maps well to C/AL string types.
|
IBooleanControlAddInDefinition |
Event support and data binding with type System.Boolean maps well to binary C/AL Boolean data |
IByteControlAddInDefinition |
Event support and data binding with type System.Byte maps well to binary C/AL Byte data |
ICharControlAddInDefinition |
Event support and data binding with type System.Char maps well to binary C/AL Char data. Please note: with NAV 2013 this is a Unicode character type. |
IDateTimeControlAddInDefinition |
Event support and data binding with type System.DateTime maps well to binary C/AL DateTime data |
IDecimalControlAddInDefinition |
Event support and data binding with type System.Decimal maps well to binary C/AL Decimal data |
IGuidControlAddInDefinition |
Event support and data binding with type System.Guid maps well to binary C/AL Guid data |
IInt32ControlAddInDefinition |
Event support and data binding with type System.Int32 maps well to binary C/AL Integer data |
IInt64ControlAddInDefinition |
Event support and data binding with type System.Int64 maps well to binary C/AL BigInteger data |
ITimeSpanControlAddInDefinition |
Event support and data binding with type System.TimeSpan maps well to binary C/AL Duration data |
These interfaces make it little easier to declare a Control add-in, that is fully supported by NAV 2013.
If you utilize the Visual Studio templates and select both support for the OnControlAddIn trigger and data binding, the template wizard will be smart enough to pick the right interface.
Further steps
In order to return the control instance to the Windows RoleTailored client you will implement the method CreateControl, like in your add-ins for NAV 2009 R2.
In order to have the add-in respect the settings of the field context you will need to override the methods like OnCaptionChanged from the WinFormsControlAddInBase. Again no changes here compared to developing add-ins for NAV 2009 R2.
For the control of the size you had in NAV 2009 R2 make the control to return a proper MinimumSize, MaximumSize and PreferredSize and would sometimes also set the Dock property of the control. In NAV 2013 we have introduced the ApplySize method, which allows you to define the default sizing behavior on the add-in class. I will describe this in a follow up post, as well as the most interesting topic: custom interfaces exposed by add-ins to C/AL code.
Christian Abeln
Senior Program Manager
Microsoft Dynamics NAV
Comments
- Anonymous
August 29, 2012
Nice post Christian!One question though:You mentioned support for mapping of all C/AL datatypes to .NET datatypes. In the list above the first .NET type is "object". What kind of C/AL type would we map on this? (fields or records or .. ?) - Anonymous
September 02, 2012
Hi Mark,in NAV 2009 Addins could use only the types 'object' and 'string' for its value property. The type 'object' was used to communicate the values of the NAV data type 'BLOB'. In NAV2013 we have added more .NET types for data binding that better match C/AL data types.Yet the type 'object' is still used for the NAV BLOB type.Hope this helps, Christian - Anonymous
September 23, 2012
Hi Christian,thank you very much for your nice posts!I noticed a strange behavior in my nav2013 addin:when I click on it the addin rises a C/AL event in which an addin "ApplicationVisible" property is changed and the addin changes his look.This works good until I click on "Show more fields" or "Show fewer fields": at this point It seems that a new addin instance is created, so there are two instances: the first is referenced by C/AL and the second referenced by the "graphical" page.So, the second instance keep on rising events to C/AL but C/AL cannot change the addin look because It uses the first "invisible" addin instance.Maybe I've done something wrong... :)Bye,Henry - Anonymous
September 24, 2012
Hi Henry,Yes, whenever the additional fields are collapsed, all fields in that group of additional fields will be disposed, including AddIns which those fields carry. When the additional fields are shown Again, the fields (and respective AddIns) will be created again.For AddIns that use only DataBinding, this does not impose a problem, because fields (and AddIns) will be created on demand and fed with data.For AddIns with a custom method interface the safest advice is to not use those on fields markes as "Additional".We will look at this further and see if we can provide a better workaround or need a platform fix.Thank you for your feedback! Best, Christian - Anonymous
October 13, 2012
Hi Christian,I think the problem occurs with any value of "Importance" property.Bye,Henry - Anonymous
January 23, 2013
Hi Christian,thank you for this tutorial to configure an addin for Dynamics NAV 2013!i have downloaded 1856.DynamicsNAV2013ClientAddIns.vsix and installed it to Visual Studio 2010. When i start a new Projekt i can´t choose "DynamicsNAV2013 Add-In Builder" as shown in your first screenshot. I only can choose "DynamicsNAV2013 WinForms Add-In Project" or "DynamicsNAV2013 WPF Add-In Project". When i take one of them there´s no Wizard i can configure Step-by-Step. Only the ProjectFolder opens in Visual Studio. Do you have a practicable Tip for me to reach the Wizard easily. I wan´t to practice your Example.Thank your for your Help!Greetings, Tobi - Anonymous
January 23, 2013
Hello Tobi,You have so far created a solution that has a project for AddIns with the help of the wizard in Visual Studio. The project compiles to a library, which may contain AddIns, but at that stage is still empty.Right click on the new project in solution explorer and select 'Add item'. Now you will find again the choice of AddIn templates, including the wizard based one.Best,Christian - Anonymous
May 22, 2014
Have you thought about writing a tutorial for a read/write add-in? It would be useful to be able to create an add-in with two-way data binding (I'm particularly interested in writing an add-in which only affects the display of the field and retains the functionality of a standard field).