Registration tool for Dynamics NAV RoleTailored client Add-ins

Update (11. Aug 2010): Updated registration tool for Add-ins libraries that reside in other directories than the RTC Add-ins folder.
(You must install this into the directory of the RoleTailored client !!!)

(Please note: “Add-ins” are supported with SP1 for Dynamics NAV 2009.)

In my last blog post on “Add-ins” for the RoleTailored client of Dynamics NAV 2009 I have shown a very simple Add-in – no support data binding, no events. But already this one requires proper registration in the database, before it can be used for development and at runtime in your Dynamics NAV business application.

Before going into further samples for Client Extensibility with data binding and events I think it is a good idea to explain the concept of this registration in a little more detail. And even better: provide a tool for point-and-click registration for Add-ins.

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

 

Add-in registration basics An Add-in must be registered in the “Client Add-in” table (2000000069) with at least its name and the public key token of its signature. Optional: The file version of the Add-in assembly Optional: A description text The registration tool The Add-in registration tool analyzes Add-in libraries, discovers Add-ins and inserts / updates the registered information in the Client Add-ins table. It provides a form in classic client which shows the list of registered Add-ins and provides a point-and-click type of file selection. And you can download it from here.

Name of the Add-in

This was the name thas had been specified as the parameter to the ControlAddIn Attribute. In this sample “SampleControl_InkEdit”.

 [ControlAddInExport("SampleControl_InkEdit")]
public interface IMyInkEditControlAddInDefinition : IObjectControlAddInDefinition
{ }

[ControlAddInExport]
public class MyInkEditContolAddIn : WinFormsControlAddInBase, IMyInkEditControlAddInDefinition
{
...
}

 

or simply:

 [ControlAddInExport("SampleControl_InkEdit")]
[Description("Edit and displays TabletPC ink")]
public class MyInkEditContolAddIn : WinFormsControlAddInBase, IObjectControlAddInDefinition
{
...
}

 

With the registration tool you don’t need to look up the Add-in names in the documentation that came with it or in the source files of your Add-in projects. It will discover the names of all Add-ins in the libraries you register automatically.

 

The Public Key Token

The requirements of signed assemblies allows Dynamics NAV to indentify exactly the assembly for an Add-in, regardless of the existence of other assemblies with the same name from other vendors. Please note: assemblies with the same name can very well reside in different subdirectories of the Add-ins directory. It also assures that only the assembly that has been signed by the same vendor like the one used for registration will be accepted at runtime.

 

The key pair for signing had been created with the Visual Studio project settings dialog or by using the signing tool manually to create a key pair and perhaps even for the actual signing in dedicated signing procedures.

But how do you get a hand on the public key token for an Add-in assembly you have received?

sn.exe -T <assembly> is the answer to this.

With the registration tool you don’t need to analyze the assembly to get the public key token. It will find it for you and add the key automatically upon registration.

The Version of the Add-in assembly

The assembly version of the dll file an Add-ins can be found is optional information. This will be very useful, as soon as several versions of Add-ins exist and need to be supported in the same NAV installation.

With the registration tool you don’t need to analyze the assembly to get the version. It will find and add the version information automatically upon registration.

The Description

Now, this information is again optional and only useful for the developer for a better understand what a certain Add-in in the table is good for. At runtime this description is not used at all.

But where is it specified?

If an Add-in developer wants to manifest a description together with his Add-in implementation, the Description attribute is the right choice - as in the sample code below:

 [ControlAddInExport("SampleControl_InkEdit")]
[Description("Edit and displays TabletPC ink")]
public class MyInkEditContolAddIn : WinFormsControlAddInBase, IObjectControlAddInDefinition
{
...
}

And of course, the registration tool will discover the description and add it automatically into the table upon registration.

 

The Registration Tool

The Add-in registration tool adds point-and-click registration to the classic client. Is is composed out of a COM object that executes the assembly analysis Form 10000 which represents the user interface below. Codeunit 10000 is used internally to executes the COM object and update relevant registrations in the Client Add-in table.

 

 

 

You can download the Registration tool here (ver 1.1, with support for Add-ins in other directories)
(You must install this into the directory of the RoleTailored client !!!)

I hope this is somewhat helpful to you.

Christian Abeln
Senior Program Manager
Microsoft Dynamics NAV

Comments

• Anonymous
  April 30, 2010
  Hi, This looks like a great tool. But it seems like it does not work with add-ins created with Visual Studio 2010. NAV raises this error:

---

Error

Could not load file or assembly 'C:Program FilesMicrosoft Dynamics NAV60RoleTailored ClientAdd-inszDemo.dll' or one of its dependencies. This assembly is built by a runtime newer than the currently loaded runtime and cannot be loaded.

OK  

Could you update your tool or give a hint to what else I could do?

• Anonymous
  May 01, 2010
  Hi Lars, The error you experience occurs if you try to dynamically load an assembly that has been built for .Net 4.0 but in an application based on a lower version of the .NET framework. Dynamics NAV 2009 SP1 is built upon .NET Framework version 3.5. And I suppose you have created a RTC Add-in with VS2010 that is built for .NET 4.0. Therefore the RTC will not be able to load an Add-in that has been built with a .NET 4.0 profile. The Registration tool from this Blog makes use of the same loading behavior like the RTC of 2009 SP1 and also is 3.5 based. It gives more detailed error message though :-) The RTC in thi situation will simply respond with: "Could not locate the add-in library for..." So there is no point in providing a .NET 4.0 based registration tool, because RTC will still fail in loading the .NET 4.0 Add-in, but not give a good error message. How to fix your Add-in: In VS 2010 goto the project options and change the Target Framework to ".NET Framework 3.5 Client Profile". Best regards, Christian Abeln

• Anonymous
  August 10, 2010
  Hi Chris,this looks great in theory, but when trying to register the assembly with your tool the system complains about not being able to load the assembly or one of its dependencies "Microsoft.Dynamics.Framework,UI.Extensibility, Version 1.3.0.0, Culture=neutreal, PKT=31bf3856ad364e35"Shouldn"t this assembly being registered already when installing the RTC?

• Anonymous
  August 10, 2010
  Hi ThomasB,Have you placed your Add-in assembly directly in the Add-ins folder?If you have chosen to use a subdirectory instead, try copying the Extensibility assembly from also into the Add-ins folder (this is due to a limit in the registration tool only).

• Anonymous
  August 11, 2010
  That was the problem, I had it in the sub folder "test".  Now it is working !!!What should be the proposed way to create a setup for such an Add-In to identify the correct folder to place the DLLs in? Imagine the user did not use the default path to install Navision RTC client !

• Anonymous
  August 11, 2010
  The comment has been removed

• Anonymous
  November 24, 2010
  Hi Chris,I have noticed that there is a "navhtmleditor.dll" in your "Select AddIn assembly file" screenshot and I'm currently looking for a possibility to edit HTML BigText inside the role tailored client. Unfortunately, I haven't been able to find this via Bing/Google, so I guess this isn't available for the.. eh.. crowd. Is this AddIn an official one for the RTC or is it just a private test?Looking forward to hearing from you,Bastian

• Anonymous
  November 25, 2010
  Bastian, this was a showcase sample we had created, to demo how simple it is, to integrate existing controls that you accuire from somewhere (e.g. a Html edit control) with an Add-in into NAV RTC.Because we do not have the distribution rights for this specific control, we could demo the building of the Add-in but not make this available as a sample for download.

• Anonymous
  August 10, 2012
  Hallo,ich habe eine Assembly erstellt, die aus mehreren Klassen besteht. Nur eine davon hat das [ControlAddInExport] Attribut. Leider wird das AddIn nicht erkannt (No Add-In class has been found in this assembly). Muss das AddIn eine eigene assembly sein? Oder sollte es auch so gehenGruß David

• Anonymous
  August 12, 2012
  Hallo David,in einem assembly können beliebig viele Klassen und auch Klassen für AddIns enthalten sein.Damit eine Klasse als gültiges AddIn akzeptiert wird, muss sie als public deklariert sein, das [ControlAddInExport] Attribut tragen und von einer der AddIn Basisklasses abgeleitet sein oder die entsprechenden Interfaces für AddIns implementieren.Gruss, Christian