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”)

 


  
GoldenCaller_2

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
{
...
}
 
Arrow60
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.

Arrow60
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.

Arrow60
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
{
...
}
Arrow60
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.

RegistrationTool-ScreenShot2

 

 

 

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