Extending Microsoft Dynamics NAV. A control add-in is a custom control, or visual element, for displaying and modifying data on pages in the Microsoft Dynamics NAV Windows client. Control add-ins are delivered as Microsoft .NET Framework?based assemblies. Microsoft Dynamics NAV includes the client extensibility API for creating your own control add-ins. All of our /NET components can be used as Control add-ins in Microsoft Dynamics NAV.

In order to use the control on Microsoft Dynamics NAV, you need:

• Microsoft Dynamics NAV
• Microsoft Visual Studio
• Source Code Version of the Exontrol Component /NET

Run the Microsoft Visual Studio and follow the next steps:

• Open the source's solution ( for instance, "C:\Program Files\Exontrol\ExG2antt.NET\Source\project\exg2antt\exg2antt.sln" )
• Add the Microsoft.Dynamics.Framework.UI.Extensibility.dll reference to the project ( for instance, "C:\Program Files\Microsoft Dynamics NAV\80\Service\Add-ins\Microsoft.Dynamics.Framework.UI.Extensibility.dll" )
• Search the "public partial class" into entire solution to locate the main component definition in the assembly, ( for instance, "public partial class exg2antt : Control, exontrol.DataSetProvider.IEBinderConsumer" )

  By default, you will find something like:

      [
          Browsable(true),
          ToolboxItem(true),
          System.ComponentModel.ComplexBindingProperties("DataSource", "DataMember",
          DefaultProperty("DataSource"
      ]
      public partial class exg2antt : Control, exontrol.DataSetProvider.IEBinderConsumer

• Add the ControlAddInExport attribute to the main class as follows:

      [
          Browsable(true),
          ToolboxItem(true),
          System.ComponentModel.ComplexBindingProperties("DataSource", "DataMember",
          DefaultProperty("DataSource",
          Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExport("exontrol.exg2antt")
      ]
      public partial class exg2antt : Control, exontrol.DataSetProvider.IEBinderConsumer

• Implement the IWinFormsControlAddIn interface:

  Add the IWinFormsControlAddIn interface

      [
          Browsable(true),
          ToolboxItem(true),
          System.ComponentModel.ComplexBindingProperties("DataSource", "DataMember",
          DefaultProperty("DataSource",
          Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExport("exontrol.exg2antt")
      ]
      public partial class exg2antt : Control, exontrol.DataSetProvider.IEBinderConsumer, 
          Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.IWinFormsControlAddIn

and its implementation such as:

#region Microsoft Dynamics NAV
        void Microsoft.Dynamics.Framework.UI.Extensibility.IControlAddIn.Initialize( 
			Microsoft.Dynamics.Framework.UI.Extensibility.IControlAddInSite controlAddInSite)
        {
		RuntimeKey = "your runtime license key";
        }

        bool Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.IWinFormsControlAddIn.AllowCaptionControl
        {
            get
            {
                return false;
            }
        }

        System.Windows.Forms.Control Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.IWinFormsControlAddIn.Control
        {
            get
            {
                return this;
            }
        }
#endregion Microsoft Dynamics NAV

where "your runtime license key" can be found on the registration email once you purchased the component. The Initialize method can be used to initialize the control, such as changing its visual appearance, and so on. The GetType().Asssembly.Location property gives the location where the assembly is loaded by the Microsoft Dynamics NAV.

For instance, you can use a code like:

        void Microsoft.Dynamics.Framework.UI.Extensibility.IControlAddIn.Initialize( 
			Microsoft.Dynamics.Framework.UI.Extensibility.IControlAddInSite controlAddInSite)
        {
		RuntimeKey = "your runtime license key";

         	this.Height = 256;

          	this.Columns.Add("Column A");
          	this.Columns.Add("Column B");
        }

to specify a different height for the control-addin, and add two columns: Column A and Column B.

• Rebuild the entire solution, so no error occurs, and the exontrol.<component>.dll is generated ( for instance "C:\Program Files\Exontrol\ExG2antt.NET\Source\project\exg2antt\exg2antt\bin\Release\exontrol.exg2antt.dll" )

See Also: Handle Events / OnControlAddin Trigger

The Create the Control-AddIn, or prepare the control to be used on Microsoft Dynamics NAV shows how to implement the IWinFormsControlAddIn interface. The same way you need to implement the IEventControlAddInDefinition interface to provide events/triggers for Control-AddIn in Microsoft Dynamics NAV environment.

Run the Microsoft Visual Studio and follow the next steps:

• Open the source's solution ( for instance, "C:\Program Files\Exontrol\ExG2antt.NET\Source\project\exg2antt\exg2antt.sln" )
• Search the "public partial class" into entire solution to locate the main component definition in the assembly, ( for instance, "public partial class exg2antt : Control, exontrol.DataSetProvider.IEBinderConsumer" )
• Implement the IEventControlAddInDefinition interface:

  Add the IEventControlAddInDefinition interface

      [
          Browsable(true),
          ToolboxItem(true),
          System.ComponentModel.ComplexBindingProperties("DataSource", "DataMember",
          DefaultProperty("DataSource"),
          Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExport("exontrol.exg2antt"
      ]
      public partial class exg2antt : Control, exontrol.DataSetProvider.IEBinderConsumer, 
          Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.IWinFormsControlAddIn,
          Microsoft.Dynamics.Framework.UI.Extensibility.IEventControlAddInDefinition

and its implementation such as:

#region Microsoft Dynamics NAV
        public event Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInEventHandler ControlAddIn;
#endregion Microsoft Dynamics NAV

and so you have defined the ControlAddIn event/member that can be fired/called any time you want to have a trigger on the NAV's page.

• Call the ControlAddIn event/member. For instance, let's say we need to trigger the Click event, so all we need is to look up for "DISPID_CLICK" and you will find something like:

  case -600: /*DISPID_CLICK - event Click () */
      {
          if (Click != null)
              Click(this);
          break;
      }

  and you need to replace with:

  case -600: /*DISPID_CLICK - event Click () */
      {
          if (Click != null)
              Click(this);
          if (ControlAddIn != null)
              ControlAddIn(-600, "Click");
          break;
      }

  and so you trigger the ControlAddIn(-600,"Click") when user clicks the Control-AddIn into the NAV's page.

• Rebuild the entire solution, so no error occurs, and the exontrol.<component>.dll is generated ( for instance "C:\Program Files\Exontrol\ExG2antt.NET\Source\project\exg2antt\exg2antt\bin\Release\exontrol.exg2antt.dll" )

See Also:

• Install the Control-AddIn (assembly) to NAV's Add-In folder
• Remove the Temp folder, in case you are updating the Control-AddIn/assembly

Now that you have copied the new dll to the NAV's AddIn folder, you should handle the OnControlAddin trigger of the Control-AddIn in the NAV's page:

• Open the NAV's page that hosts the Control-AddIn, in design mode
• Go to the field that hosts the Control-AddIn
• Right-Click the field, and choose "C/AL Code"
• Locate the "OnControlAddIn(Index : Integer;Data : Text)" for the field
• Add the Message(Data) as in the following sample:

  Name - OnControlAddIn(Index : Integer;Data : Text)
    MESSAGE(Data);

• Save and Close the page
• Run the Page, and click the Control-AddIn, and so the message box "Click" is displayed.

The Microsoft.Dynamics.Framework.UI.Extensibility.IControlAddIn.Initialize method while Create the Control-AddIn, or prepare the control to be used on Microsoft Dynamics NAV can be used to initialize the assembly using data from the NAV's field.

• Replace the Initialize method with

          void Microsoft.Dynamics.Framework.UI.Extensibility.IControlAddIn.Initialize( 
  			Microsoft.Dynamics.Framework.UI.Extensibility.IControlAddInSite controlAddInSite)
          {
  		RuntimeKey = "your runtime license key";
  		
  		string[] rgColumns = controlAddInSite.Caption.Split(',');
         		foreach( string sColumn in rgColumns )
         			this.Columns.Add(sColumn);
          }

The code takes the Caption property of the NAV's field, splits it and adds a new column for each element being found.

• Open the NAV's page that hosts the Control-AddIn in design mode
• Locate the Field that hosts the Control-AddIn, and change the Caption field
• Save, and Close the Designer

On the computer running the RoleTailored client, copy the assemblies/files that contain the control add-ins to the Add-ins folder of the RoleTailored client installation.
By default, the path to this folder is C:\Program Files\Microsoft Dynamics NAV\80\Service\Add-ins. You can also place assemblies in a subfolder of the Add-ins folder. This can be useful when you have multiple assemblies and dependencies.

• Go To Microsoft Dynamics NAV's Add-ins folder and create a new folder ( for instance "Exontrol.ExG2antt" )
• Copy the new generated dll ( for instance "C:\Program Files\Exontrol\ExG2antt.NET\Source\project\exg2antt\exg2antt\bin\Release\exontrol.exg2antt.dll" ) , and any reference the control may use. Also in the same folder you can copy any EBN, XML files the control may use to change the visual appearance. ( for instance "exontrol.exg2antt.dll" )

In case you are making changes to the assembly dll, and you replace the DLL in the NAV's Add-In folder, you have to be sure that you are removing the associated folder in the C:\Users\<USER>\AppData\Local\Temp\Microsoft Dynamics NAV\Add-Ins, else the same assembly will be used.

( Source: https://msdn.microsoft.com/en-us/library/dd983803.aspx)

In order to Register the Control-AddIn to NAV's "Client Add-in." table you need to provide the Control Add-In Name and Public Key Token for the assembly, and so you can do the following:

• The Control Add-In Name, is determined by the ControlAddInExport attribute, as defined in Create the Control-AddIn, or prepare the control to be used on Microsoft Dynamics NAV ( for instance "exontrol.exg2antt" )
• The Public Key Token of the assembly can be determined using any of the following ways:
  • Using the FullName property of the System.Reflection.Assembly.
    • Create a new Microsoft Visual Project, 
    • Add the Microsoft.Dynamics.Framework.UI.Extensibility.dll reference to the project ( for instance, "C:\Program Files\Microsoft Dynamics NAV\80\Service\Add-ins\Microsoft.Dynamics.Framework.UI.Extensibility.dll" )
    • Adds the exontrol.exg2ant to a form
    • Call the MessageBox.Show(exg2antt1.GetType().Assembly.FullName) on form's Load event, and you should get a message like:
      
    • Press the CTRL+ C to copy the message, paste to Notepad, and copy PublicKeyToken indicates the Public Key Token of the assembly
  • Using the sn.exe tool of Microsoft SDK (source: https://msdn.microsoft.com/en-us/library/dd983825.aspx)
    • Locate the sn.exe file.
    • The default folder for the Microsoft .NET Framework SDK is C:\program files\microsoft sdks\windows\v7.0\Bin.
    • At the command prompt, change to the directory that contains the sn.exe utility.
    • Type the following command:
      sn.exe -T <assembly>
    • Replace <assembly> with the add-in assembly's path and file name, such as Program Files\Microsoft Dynamics NAV\60\RoleTailored Client\Add-ins\MyCompany.MyProduct.RtcAddins.dll.
    • Press ENTER and note the public token key that is displayed.

Once you Determine the Control Add-In Name and Public Key Token for the assembly, you need to register the Control-AddIn to NAV's "Client Add-in." table by doing the following:

• Open the Classic client.
• On the Tools menu, click Object Designer.
• Click Tables, and then locate the table with ID 2000000069 and name Client Add-in.
• Click the table, and then click Run.
• On a blank line in the Client Add-in table, fill in the Control Add-In Name and Public Key Token fields.
• Close the Client Add-in table.

(source: https://msdn.microsoft.com/en-us/library/dd983818.aspx)

Once you Register the Control-AddIn to NAV's "Client Add-in." table you can extend your page by doing the following:

• To set the ControlAddIn property on the field
• In Object Designer, click Page.
• Select the page with ID 21 and name Customer Card, and then click Design.
• Select the Name field, and then on the View menu, click Properties.
• In the ControlAddIn property value, click the lookup button, and then select the exontrol.exg2antt from the Client Add-in window.
• Click OK
• Close the Properties window.

Running the page you should get:

(source: https://msdn.microsoft.com/en-us/library/dd983804.aspx#SetupAddin)

In case you are making changes to the assembly dll, and you replace the DLL in the NAV's Add-In folder, you have to be sure that you are removing the associated folder in the C:\Users\<USER>\AppData\Local\Temp\Microsoft Dynamics NAV\Add-Ins, else the same assembly will be used.

If you are doing multiple changes, updates, you can copy and paste the assembly dll directly into associated folder on  C:\Users\<USER>\AppData\Local\Temp\Microsoft Dynamics NAV\Add-Ins folder.

All of our controls are royalty-free and run-time license-fee free. This means that when you purchase our products (one copy per developer on your project), you may distribute the component you purchased with your applications without paying any run-time fees to us.

• 1 x License of Source Code Version of the Exontrol Component /NET
• Additional licenses for Single / Team / Site version, depending on the number of the developers are working on the project. For instance, if you have three developers working on the project, you need additional 2 x Single License. If you have four developers, you need additional 1 x Team License, and so on.

Related to the Source Code Version, If you are running the Microsoft Dynamics NAV on a:

• 32-bit machine, you need only 1 x License of Source Code Version of the Exontrol Component /NET for 32-bit
• 64-bit machine, you need only 1 x License of Source Code Version of the Exontrol Component /NET for /ANY. The Microsoft.Dynamics.Nav.Client.exe is running as 32-bit on a 64-machine, while the Microsoft.Dynamics.Nav.Server.exe is running as 64-bit