Recently I had the honor to give a Hands On workshop on Client Extensibility for Dynamics NAV 2013 at the Airlift event in Leipzig / Germany.

I thought I create a new workshop with a new AddIn - A Bing Map showing a customer on a map, including Geocoding. The presentation and workshop files are available for download here:

• Step by Step Presentation: Download here
• Workshop files for all steps: Download here
• AddIn registration tools for Dynamics NAV 2013: Download here

The Workshop

In order to go through the workshop you need to have

 You will also need to request your self a developer key in order to use the Bing Map API, which you can do starting from the Bing Maps Developer Portal.

The Workshop is build in 6 steps (please excuse some German terms in the slides below):

1. It starts with creating a basic AddIn using the Visual Studio templates and adds the Map WPF control and shows a Map part in the Windows Client.
    
2. Then it adds server side controlled authentication, in order to set the Bing Map Key. This is done using a custom interface method.
     
3. This step adds the capability to position the map, zoom in and out problematically and control the view. In this step a serializable .Net object is introduces that is passed for the location as a parameter
    
4. Now we add a layer for pushpins and set a pushpin for a customer. We introduce client side geocoding here.
    
5. In this step geocoding is moved server side and the position is requested first time a customer shall be located on a map. Th elocation is stored in the customer table.
    
6. Finally we introduce the concept of asynchronous geocoding on the server. Such that the response of a geocoding request is not awaited and blocks the execution any longer. As soon as the asynchronous request returns, the customer location is updated in the database. The client is using the PingPong AddIn to poll for updates.
   
   
   
    
7. The seventh steps is not included, but left for your own tinkering: Move the geocoding request into a code unit that is used in a Job Queue. This could allow automatic geocoding: for addresses where location is missing, but last geocoding did not return empty results or for addresses that have changed. With a job queue this can be then done behind the scenes, without involving the client.
   (And this is of course the only good way to do geo coding, yet for the purpose of experimentation in the workshop I have implemented it in different tiers.) 

How to just try out the final step:

1. Copy all dlls from Workshop folder e.g. below for Step 6 in a subfolder (e.g BingMap) the Client AddIns directory :
   "\Workshop\Step 6 (Serverside Async Geocoding)\MyBingMapAddIn\BingMapAddIn\bin\Debug\*.dll" => 
   "C:\Program Files (x86)\Microsoft Dynamics NAV\70\RoleTailored Client\Add-ins\BingMap\"
    
2. Copy MyBingGeocoder.dll from Workshop folder e.g. below for Step 6 in a subfolder (e.g BingMap) the Server AddIns directory :
   "\Workshop\Step 6 (Serverside Async Geocoding)\MyBingMapAddIn\BingMapAddIn\bin\Debug\MyBingGeocoder.dll" =>
   "C:\Program Files\Microsoft Dynamics NAV\70\Service\Add-ins\BingMap\"
    
3. Register AddIn. You may use the AddIn toolkit in the resources directory for that.
   Copy the AddInToolkit forlder into the Client AdIns folder:
   "\Workshop\Reources\AddInToolkit\" =>  "C:\Program Files (x86)\Microsoft Dynamics NAV\70\RoleTailored Client\Add-ins\AddInToolkit\
   Run the page 65006 "Client Add-in registration" from the objects in the fob file "AddInRegistrationTool-V7.fob"
   Click on "Check AddIn Files" and wait until list is updated. Check then the "MyBingMapAddIn" in order to register it.
    
4. Import / merge the objects from fob / text files:
   
   Part: "MyBingMapPart"
   Changes to table Customer. for Latitude,Longitude,IsGeoCoded,GeocodingFailed and trigger code to maintain those fields
   Customer list:utilize BingMapPart with sub page link
   optional: Customer card: show geolocation fields
    
5. You may update the global Text constant "BingAppKey" in the "MyBingMapPart" with a key you have requested for yourself.
   (The key contained will be disabled soon.)
    
6. Run the customer page and makew shure the BingMap part is showing. While scrolling through the list addresses will be geocoded and the
   selected customer shown on the map if address could be geocoded.
   When address changes, location will b ereset and new geocoding will be issued, as soon as customer selected again.
   Geocoding happens asynchronous. If geocoding is not possible maps zooms out to whole world.

I hope this workshop is somewhat helpful, inspiring, ...

And please keep enjoying to develop cool extensions for Dynamics NAV ! 

 Christian Abeln 
Senior Program Manager 
Microsoft Dynamics NAV

	Dynamics NAV 2013 - Bing Map Integration Workshop: Step by Step Presentation: Download here (partly in German)
	Dynamics NAV 2013 - Bing Map Integration Workshop: Project files for all steps: Download here
	Dynamics NAV 2013 - AddIn registration tools: Download here
	Dynamics NAV 2013 - Full Source of the Lync Communication AddIn : Download here
	Dynamics NAV 2013 - Add-In templates for Visual Studio 2010 and Visual Studio 2012 (Express not supported)
	Dynamics NAV 2013 Presentation – Mastering the Visualization Add-ins (Directions EMEA 2012)
	Dynamics NAV 2009 R2 Presentation – Client Extensibility in Microsoft Dynamics NAV 2009 R2 (Directions US 2011)
	Dynamics NAV 2009 R2 Sample – Document Viewer Dynamics NAV 2009 R2 Sample – Month Day calendar Add-In showing generic data serialization (Directions US 2010)
	Dynamics NAV 2009 – Timeline visualization on Partner Source and Customer Source
	Dynamics NAV 2009 – Treemap visualization on PartnerSource and on CustomerSource
	Dynamics NAV 2009 Tool – Add-In templates for Visual Studio 2010 Dynamics NAV 2009 Tool – Add-In templates for Visual Studio 2008 Dynamics NAV 2009 Tool – Registration for Add-Ins ver 1.1 (txt version of the objects)
	Dynamics NAV 2009 - Sample objects for showing bitmaps in the NAV repeater from CAL
	Dynamics NAV 2009 R2   Recorded “Hot Topic” – Business Data Visualizations Dynamics NAV 2009 SP1 Recorded “Hot Topic” – Add-ins for the Role Tailored Client
	Dynamics NAV 2009 Presentation – Client Extensibility - Introduction, How to use Add-ins         Dynamics NAV 2009 Presentation – Client Extensibility - How to create Add-ins

Christian Abeln
Senior Program Manager
Microsoft Dynamics NAV

Originally I had built this AddIn as a showcase for a partner conference. Later we considered to add it to the shipping code in Dynamics NAV 2013, yet as an outcome of our scoping decisions we did not want add it at the end of this release cycle.

In this blog post I want to describe the supported usage scenarios and provide the steps to use the source and integrate the AddIn into a NAV database. A more technical view from an implementation standpoint can be found in this Blog Post.

Please find the download here: LyncCommunicationAddInSample.zip 

But let’s start with the user scenario, this control wants to solve:

Base scenario: Communicate from within Dynamics NAV

As an end user who gets frequently into contact with customers / vendors I like the fact that I can use a unified communication system in NAV to communicate with my customer & vendor contacts. The unified communication system brings together all the communication end points which a contact has published - like mobile & office phone number, IM address and even address for IP telephony and screen sharing.

Monitoring availability / presence

But the real value comes when I see the availability of a contact right in my screen. I can see if a contact is available and if not I can even drag a small communication card out of Dynamics NAV, pin it to my desktop and monitor the availability state. As soon as my communication contact becomes available I will ping him or start a telephone call.

In factboxes I see a smaller view of the presence field but still have the ability of monitoring presence, opening the contact card and starting a communication.

And if I am is not logged in to Lync on the local machine, the field will have the following appearance and the search button will be disabled. This state will automatically update to the standard communication appearance, if I sign into Lync.

On Task pages:

In Factboxes:

Finding a communication contact

But how do I find the communication address?

The Lync communication field provides a search functionality, that suggests search input, that is harvested from artifacts from the Dynamics NAV page - like email, Name, Company, etc. With such artifacts or with my own search input I can search for a communication contact in my and connected communication systems - depending on the federation.

But also if I simply type in the live ID address or the yahoo address for a contact that I already know, the contact will be accepted as a communication endpoint, even if the federation for search between the two communication systems has not been full enabled.

Supported communication systems

The supported communication systems on my side is Lync, and whether my company has its own installation of Lync Enterprise or we are using Office 365 with its Lync offering, we are able to communicate with whatever other communication systems have been federated with our instance. This can be for example Yahoo, Live Messenger or other companies using of Lync Enterprise of Office 365.

How to use the source code, build the AddIn, distribute it and integrate it into Dynamics NAV

Please find the download here: LyncCommunicationAddInSample.zip 

Following are the steps to build the Lync AddIn library from the Source Code

1. Download of the Lync SDK, and run the installation.
    
2. Open the solution LyncComunicationAddIn.sln in Visual Studio 2013
    
3. Update references to the Lync controls libraries from the SDK and the Dynamics NAV extensibility library (Microsoft.Dynamics.Framework.UI.Extensibility.dll) from the installed Dynamics NAV 2013 product.
    
4. The Lync libraries can be found in the Lync SDK directory, by default: 
   “C:\Program Files (x86)\Microsoft Lync\SDK\Assemblies\Desktop\”
    
5. The Dynamics NAV extensibility library is typically in the following directory:
   “C:\Program Files (x86)\Microsoft Dynamics NAV\70\RoleTailored Client\”
    
6. For the latter reference, make sure that you set the property CopyLocal to false – we do not want this library to be copied to the output directory or even copy it into the Add-Ins directory for the Lync Add-In when we copy it to an installed Dynamics NAV instance.
    
7. Compile the solution in Release build and identify the output folder under Bin/Release folder. Deploy the libraries and application objects as described below for the compiled AddIn library.

Following are the steps to use the Lync communication AddIn based on the compiled AddIn library

1. Unpack the solution to a directory on your computer.
    
2. Identify the compiled output in the bin/Release directory of the project directory.
    
3. Create a directory e.g. named “Lync” in the Client Add-Ins directory, typically “C:\Program Files (x86)\Microsoft Dynamics NAV\70\RoleTailored Client\Add-ins\” and copy the content from the output directory there.
    
4. The redistributable library from the Lync SDK can also be delivered by installing the redistributable installation, which typically can be found in the following place:
   “C:\Program Files (x86)\Microsoft Lync\SDK\Redist\LyncSdkRedist.msi”
    
5. Register the AddIn in the “Client Add-In” table with the following entry: 

Finally import the  integration objects in file LyncIntegrationObjects.fob.
These sample app changes for the Lync Integration cover the following changes:

• Field 200 SipAddress is added to the Customer, Vendor, Contact & Sales Header table.
• The cards for Customer, Vendor, Contact and Sales Order get each a Lync communication field in the communication fasttab. Code on the page will aside to the SIP address initialize the control for search candidates from other fields.
• The fact boxes for customer and vendor details also get a Lync communication field with a fact box styled rendering, such that the Lync communication is available through the details page on list places for customers and vendors.
• The page for the Item Vendor Catalog gets also the Vendor details factbox

The content of this package is composed of the Sample code, Distributable code and Third Party Distribution and the covered by the License Terms in file “Lync Communication AddIn SDK License Terms.docx”

• Sample Code are all files that are referenced by and including in the Visual Studio Solution LyncCommunicationAddIn.sln
• Distributable code is the built library LyncCommunicationAddIn.dll
• Third Party Distributionfiles are the redistributable files from the Lync SDK:
  • Microsoft.Lync.Controls.dll
  • Microsoft.Lync.Controls.Framework.dll
  • Microsoft.Lync.Model.dll
  • Microsoft.Lync.Utilities.dll
  • Microsoft.Office.Uc.dll
  • Microsoft.Lync.Controls.Framework.resources.dll (in any of the language subdirectories)
  • Microsoft.Lync.Controls.resources.dll (in any of the language subdirectories)

The redistributable library from the Lync SDK can also be delivered by installing the redistributable installation, which typically can be found in the following place:
“C:\Program Files (x86)\Microsoft Lync\SDK\Redist\LyncSdkRedist.msi”

Christian Abeln
Senior Program Manager
Microsoft Dynamics NAV

Please find the download here:

 NAV 2013 Tool – Add-In templates for Visual Studio 2010 and Visual Studio 2012

The express versions of Visual Studio unfortunately do not support those templates.

Christian Abeln      
Senior Program Manager   
Microsoft Dynamics NAV

Add-Ins in NAV 2009 where all about data binding a custom visual component through the Source Expression of the field  to a data source – a variable on a page or a field in a table. Data for a an add-in would be transferred when the page updates and changed values from the add-in would be transferred back and saved when the page saves data. The add-in could influence a little, by triggering the OnControlAddIn Trigger or requesting saving of data through the Site.

While these concepts lead the developer to a “document oriented” thinking (documents conforming to data models and possibly configuration models), it imposed also some limitations. It was not always easy (yet possible) to build a document communication model that allowed C&AL to send small signals and requests to the add-in and request values. In any case it required always serialization of a object structure into a document and deserialization on the other side, in either direction.

In NAV 2013 we have introduced Custom Interfaces for client add-ins. These are basically select methods, properties and events that dynamically extend the C/AL programming interface of the respective field on the page. An Add-In developer simply declares any public Method or Property or Event of the Add-In class with the new Attribute [ApplicationVisible], and as soon as an Add-In get assigned to a page, the field has those Methods and Properties available, even through the Symbol Editor (F5). Events that have been equipped with the attribute above will be represented as new server side triggers in the C/AL code code written in those  triggers will be called as soon as the Add-In calls the event on the client.

For the restless reader (“in a few words”)

- Add-In developer can expose “custom interfaces” to C/AL : public methods, properties and events with the [ApplicationVisible] attribute.

- Application Visible methods and properties are available for C/AL code at design and runtime, provided the Add-In library can be found.

- Application Visible events will be represented as new triggers for the respective fields on the page

- The Lync communication Add-In is a sample that shows how to use this technology

- Soon: Download of the the Lync Add-In: I am working on making it possible to share that.

A sample: Lync communication Add-In with custom interfaces

An add-in for Lync communication is sample for how custom Add-In interfaces may be used custom interfaces for different purposes:

This Lync communication Add-In shall support the following behaviors:

• Consume a SIP address under which Lync client through its Lync server will try to identify a communication contact from the own or any federated directory of communication contacts.
• Shows the presence of the communication contact - as far as available through federation
• Provides UI entry points to any available communication channel and shows general communication contact information that can be pinned to the desktop
• Allows the user to search for a communication contact

 
• Provides search suggestions as defined by C/AL code

• Has different appearances, like honoring the layout specifics for task pages and fact boxes

For this purpose we design the Add-In interface in the following way:

• Use data binding with the Source Expression to receive the SIP address from the underlying field
• Provide custom interfaces that allow the C/AL developer to set the display characteristics, also by a set of predefined styles (Option field like)

/// <summary>
/// Adjusts the control for usage in taskpage / factboxes
/// </summary>
/// <param name="context">The context.</param>
[ApplicationVisible]
public void SetAddInControlContext(AddInControlContext context)
{
     ...
}
  

• Provide a method to set a list of search candidates to the Add-In. This takes actually a .NSTR string collection as a parameter which will be created in C/AL code and passed over without the need for serialization.

/// <summary>
/// CAL method: sets the search candidates
/// </summary>
/// <param name="candidates">The search candidates</param>
[ApplicationVisible]
public void SetSearchCandidates(StringCollection candidates)
{
      ...
}

• Expose an event from the Add-In, where in the corresponding trigger it is save to initialize the Lync control Add-In. Please note the type of the Event: MethodInvoker. Typically event types in .NET like to use one parameter for the sender of the event. With Add-Ins this is not feasible, because it would be the client side instance of the Add-In – depending on what object the Add-In would send. When sending over this object in a client-server event, the call would internally involve serialization, which is not supported by must .NET types and must be prevented in order to be display target independent. C/AL shall have only access to the field and such the ApplicationVisible exposed elements of the interface.

/// <summary>
/// Event will be fired when the Add-In is ready for communication through its API
/// </summary>
[ApplicationVisible]
public event MethodInvoker AddInReady;
  

Relation of .NET interop and Custom interfaces of Add-Ins

On the first glance writing C/AL with .NET interop objects and Add-Ins appears to be rather similar.  But there are important differences:

• While Add-Ins appear as if they
• One difference is that .Net interop objects are always instantiated with one of its constructors (or a factory method which call the constructor). Yet the instance of the Add-Ins (or it’s server side representation of the custom interface) is just there, as soon as the page has been fully created. Unfortunately there is not default place in code where the instance of the server side representation of the Add-In can be assumed to exit. Therefore for Add-Ins, where the server side use case typically requires a signal to now when the Add-In has been created on the client, the above suggested introduction of the AddInReady event is  good solution.

Structure of the Lync AddIn

The LyncCommunicationControl is a WPF composition of multiple controls from the Lync control SDK with customized templates and interactions.

The LyncCommunicationAddIn, the the router between NAV and the WPF control.

Typical Call flow with an AddIn with custom interfaces

In order to take care of the right sequence for initialization it a good idea to let an Add-in expose an event like AddInReady as shown in this sample and publish this with [ApplicationVisible]. The event shall be called as soon as the control has been given a parent. The ParentChanged event of the control can be used for this.

What’s going to happen if …

What is going to happen if the Add-In has been changed in the interface since it had been used on a page ?

It might be necessary to remove and reassign the Add-In to the field in order to have the code regenerated that interfaces with the  Add-In custom interfaces. This is especially the case for C/AL Triggers that represent the custom events. Typically though a compilation error can be expected, until the interfacing C/AL code has been updated.

What happens with the C/AL Code that interfaces with custom interfaces if the Add-In is removed from a field?

If you remove an Add-In which has introduced Triggers for ApplicationVisible events, the a warning dialog will be shown in the development environment, indicating that those triggers together with the code that has been written in them will be deleted.

What happens if a display target runs a page that does not support Add-Ins at all ?

The Web Client of Dynamics NAV 2013 does not yet support Add-Ins. But what happens if a user runs still somehow opens such a page in the Web client?

A display target that does not support Add-Ins yet, (like the Web Client) will simply not at all show a field that has an Add-In assigned  -as if this field was not visible. But if the C/AL code on the page calls into the custom interface of an Add-In the developers of the Add-In and the C/AL have to take special care:

E.g. by exposing an event like AddInReady from the Add-In which the Add-In will call as soon as it is ready to operate (e.g. after the control which he Add-In provides has been given a parent). In C/AL code in the corresponding AddInReady trigger would remember whether that trigger has been called, and otherwise not try to call into the Add-In custom interface. On a display target that does not  support Add-Ins such trigger would never be called.

What’s next ?

In the next blog post of this series I will take a closer look at the Sizing support for Add-In fields and present an update of the Registration and troubleshooting tools for Add-Ins.

Christian Abeln
Senior Program Manager
Microsoft Dynamics NAV

With NAV 2009 R2 The ControlAddIn event had been introduced. An Add-In can raise this event and the C/AL OnControlAddIn trigger will be called.

When you use the Add-In templates for Visual Studio and create an Add-In that supports this event you might want to remember to do a simple check whether the Event had been subscribed before calling it.

        protected void RaiseControlAddInEvent(int index, string data)
        {
            if (this.ControlAddIn != null)
            {
                this.ControlAddIn(index, data);
            }
        }

        public event ControlAddInEventHandler ControlAddIn;

The method RaiseControlAddInEvent is a sample for this. It will be created when you use some of the Add-In templates for Visual Studio and is already part of some of the base classes for specialized Add-Ins – like the classe StringControlAddInBase.

And when we let an Add-In for Dynamics NAV 2013 expose custom events we will remember to use a similar approach for each individual exposed event!

To understand the necessity for this, you should know that the client can decide to subscribe and unsubscribe from the exposed events any time, based on the initialization / de-initialization or other states of a page. The Add-In can simply check whether an event can be received & processed by the client at any time by checking that it is asigned.

Thank you, Bert K. (Tectura) for pointing this out! This is certainly something to be aware  of when creating Add-Ins.

Christian Abeln
Senior Program Manager
Microsoft Dynamics NAV

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:

1. Use the base class for the display target – until now the WinForms based Windows RoleTailored client, which is the class WinFormsControlAddInBase.
2. 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.
3. 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.

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

From the first design of AddIns for NAV R2 we had taken care of the fact that AddIns that have been built for R2 (DataBinding with Text, BigText or Blob) and the OnControladdIn trigger we had planned that AddIns built for a previous version would also load in the next versions of NAV. From the internal interface and implementation perspective this also supported in the design.

The only remaining tweak to make this work is to tell the .NET system that it is shall load AddIns built for R2 and bind them against the newer versions of the libraries Microsoft.Dynamics.Framework.UI.Extensibility and Microsoft.Dynamics.Framework.UI.WinForms.Controls. This is done by a configuration entry in the config file for the Role Tailored client (Microsoft.Dynamics.Nav.Client.exe.config):

<runtime>
  <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
    <dependentAssembly>
      <assemblyIdentity name="Microsoft.Dynamics.Framework.UI.Extensibility" 
                        publicKeyToken="31bf3856ad364e35" culture="neutral"/>  
      <bindingRedirect oldVersion="0.0.0.0-6.9.9.9" newVersion="7.0.0.0"/>
    </dependentAssembly>
    <dependentAssembly>
      <assemblyIdentity name="Microsoft.Dynamics.Framework.UI.WinForms.Controls"
                        publicKeyToken="31bf3856ad364e35" culture="neutral"/>
      <bindingRedirect oldVersion="0.0.0.0-1.4.9.9" newVersion="1.5.0.0"/>
    </dependentAssembly>
  </assemblyBinding>
</runtime>

This configuration will instruct the .NET runtime to use the version 7.0 of the Extensibility assembly if a library that gets loaded has been compiled against an earlier version. The same for the version 1.5 of the WinForms.Controls assembly which is needed indirectly too.

Please note: In released NAV 2013 this settings will probably ship in the standard configuration file.

But in order to allow the page previewer in NAV 2013 development environment also to show R2 AddIns and to allow .NET interop components from the same AddIn assembly to be used in the NAV development environment and on the server at runtime, you will need to ad the same settings to the respective config files for finsqle.exe and the service executable Microsoft.Dynamics.Nav.Server.exe.

While in general it is a good idea to use of serializable .NET interop objects for data models for communication with more complex AddIns, like business data visualizations, I strongly suggest to not blend those data model objects into the AddIn assembly but keep them as separate assemblies without any dependencies to NAV product libraries.

Christian Abeln
Senior Program Manager
Microsoft Dynamics NAV

Just have released a new improved release of the Timeline visualization for DynamicsNAV 2009 R2
on Partner Source and Customer Source!

It is already a while ago since Microsoft DynamicsNAV R2 has shipped. On the DVD image there two Business Data Visualizations shipping: The Treemap visualization and this now updated Timeline visualization. The latter can be used for example to visualize the projected inventory of an item over time.

This visualizations shows the inventory level for one item / variant over time and lets the user compare scenarios of the core transactions only, taking into account forecast and changes suggested by the planning engine (“Action messages”) or the planner himself. The user can edit in the latter scenario and apply his own changes to supply transactions interactively in the chart: He drags data points to change supply quantity or moves them in time to suggest a rescheduling action.
Changes are transmitted back to app code and can be processed, validated and applied or rejected.
Further interactivity options cover zooming, scrolling, creation & deletion of supply, reverting of supply changes and automating adjustment for individual supply to balance the inventory until the next planned supply.

What is new in this update:

Precision for the measure Render a unit of measure API control for which of the three scenarios to show In place description label for selected point Tab order based selection of movable points Keyboard control for moving of point (Shift+Arrow key)

The Add-in API

In earlier releases this visualization was communicating over XML ports with the business logic to get and modify the transactions and the rows in the planning journal. This communication has been replaced with a more robust .Net interop object, which the visualization provides to the business logic. This removes certain encoding problems that might have been observed before. This object is actually great to walk through the features of the visualization Add-in:

It is the TransactionDataDocument which is exposed by the Add-in assembly itself:  Microsoft.Dynamics.Visualizations.InteractiveTimeline.AddIn.TransactionDataDocument.

An instance of this document class is instantiated, populated and serialized by the business logic, in order to compose the data document that the visualization Add-In need to receive over the data binding of the respective field’s source expression .

Add-in API: Properties

If we look at the Interface find the following properties that C/AL business logic may set:

Add-in API: Methods

And we have the following methods for the application developer:

AddSpecialValue (decimal value, string title, Color color):
Adds a constant value which is drawn as colored horizontal lines with label attached.

AddSpecialDate (DateTime date, string title)
Adds a date which is highlighted and labeled in the background of the visualization.

Serialize()
Serializes the document into XML, which will be used to fill the document variable for databinding.

Add-in API: Triggers

The visualization sends also the following OnControlAddIn trigger events to the business logic :

 Add-in API: Xml commands

The visualization supports the following XML commands which can be sent through data binding. The purpose of these command is to give the business application developer similar modification control like the end user has. This comes handy for example, when the user can alternatively edit transaction changes in a list, and the business application developer wants to synchronize the visualization without sending over a complete transaction document.

If you want to find a good example on how this API can be used from business application code, I suggest you study the application objects that come with the Add-In. They implement the visualization in and End 2 End scenario for Projected Item Availability monitoring.

Important: You need to install one of the recent hofixes for DynamicsNAV 2009 R2 / SP1, in order to get the integration code working. Some updates to the .NET interop from the Hotfix builds is required. (The necessary hotfix has been applied in KB 2492239, which was released in March 2011 and comes with the NAV build number: 6.0.32146.)

Christian Abeln
Senior Program Manager
Microsoft Dynamics NAV

If you want to experiment with the creation of an interactive control Add-in that visualizes and can change a state of an entity on a task page, the attend!

If you want to experiment with easy charts integrated with your custom application code, then attend!

We have actually rewritten the whole Hand On Lab, to make it easier to follow. We use the Add-in templates and have some control code ready for you, which you even can take home – if you like.

See you at Directions EMEA 2011!!

Christian Abeln
Senior Program Manager
Microsoft Dynamics NAV