Walkthrough: Creating and Using a RoleTailored Client Control Add-in


The content in this topic only applies to Microsoft Dynamics NAV 2009 SP1. For Microsoft Dynamics NAV 2009 content, see Developer and IT Pro Help for Microsoft Dynamics NAV 2009.

The following walkthrough demonstrates how to develop a RoleTailored client add-in and use it on a RoleTailored client page. Add-ins are Microsoft .NET assemblies that allow you to add custom functionality to the RoleTailored client. An application programming interface (API) lets you develop add-ins without having to access the Microsoft Dynamics NAV 2009 source code.

In a typical business scenario, .NET developers create add-ins using Microsoft Visual Studio Express, Visual Studio 2005, or Visual Studio 2008. Implementers of Microsoft Dynamics NAV solutions then use the add-ins on RoleTailored client pages.

About This Walkthrough

This walkthrough illustrates the following tasks:

  • Creating an add-in with Visual Studio 2005 or Visual Studio 2008.

  • Copying the add-in assembly to the computer running the RoleTailored client.

  • Registering the add-in in Microsoft Dynamics NAV.

  • Setting Up the add-in on a page.


This walkthrough demonstrates tasks performed by the following user roles:

  • Microsoft .NET developer.

  • Microsoft Dynamics NAV developer and IT Pro.


To complete this walkthrough, you need:

  • Microsoft Dynamics NAV 2009 with a developer license.

  • All Microsoft Dynamics NAV 2009 requirements met. For more information, see Microsoft Dynamics NAV 2009 SP1 Requirements.

  • Microsoft Visual Studio Express, 2005 or 2008.

  • Microsoft .NET Strong Name Utility (sn.exe). This is included with Visual Studio 2005 or Visual Studio 2008 SDKs.

  • Experience with Visual Studio 2005 or Visual Studio 2008.


Simon is a software developer working for CRONUS International Ltd. He has been told that users of the RoleTailored client would like a way to see the entire content of page fields when the content extends beyond the field size. He decides to create an add-in that can be applied on a field that allows the user to double-click the field to display its full content. Fields applied with add-in are displayed as blue. When the user double-clicks the field, a popup window opens that shows the field's content. The following figure illustrates the add-in on a Customer Card page.

Add-in that opens popup window on Card page field

Creating an Add-in with Visual Studio 2005 or 2008

Microsoft Dynamics NAV 2009 includes the Microsoft.Dynamics.Framework.UI.Extensibility.dll assembly that defines the model for creating RoleTailored client add-ins. The API provides the binding mechanism between the RoleTailored client add-in and the Microsoft Dynamics NAV 2009 framework.

To create the add-in

  1. In Visual Studio Express, Visual Studio 2005 or Visual Studio 2008, create a Visual C# project type using the Class Library template.

    Name the solution MyCompany.MyProduct.RtcAddins.

  2. In the project, add references to the following assemblies:

    • Microsoft.Dynamics.Framework.UI.Extensibility.dll assembly

      By default, the path to the assembly is C:\Program Files\Microsoft Dynamics NAV\60\RoleTailored Client. This reference is required for all RoleTailored client add-ins.

    • System.Windows.Forms

      Contains classes for creating user interfaces for Windows-based applications.

    • System.Drawing

      Provides access to basic graphics functionality.

  3. Open the Class1.cs file and add the following using directives:

    using Microsoft.Dynamics.Framework.UI.Extensibility;
    using Microsoft.Dynamics.Framework.UI.Extensibility.WinForms;
    using System.Windows.Forms;
    using System.Drawing;
  4. Declare a new class for the add-in that uses the Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute attribute and derives from the Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.StringControlAddInBase class and Microsoft.Dynamics.Framework.UI.Extensibility.IStringControlAddInDefinition interface as follows:

    public class MyFieldPopupAddin : StringControlAddInBase

    The Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute attribute declares the class in the assembly to be a control add-in that is identified by its Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute.Name property, which in this case is MyCompany.MyProduct.FieldPopupAddin. Because an assembly can contain more than one control add-in, the RoleTailored client uses the Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute attribute to differentiate each control add-in that is found an assembly.


    You will use the name MyCompany.MyProduct.FieldPopupAddin later in the walkthrough when you register the add-in in Microsoft Dynamics NAV 2009. When naming the control add-in, it is good practice to follow the .NET Framework naming convention for classes, which is CompanyName.ProductName.ControlName.

    The Microsoft.Dynamics.Framework.UI.Extensibility.IStringControlAddInDefinition interface determines how data transfers to and from the add-in and how events are raised to call triggers on Microsoft Dynamics NAV Server.

  5. Implement the abstract Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.WinFormsControlAddInBase.CreateControl method and add the code that defines the add-in functionality as follows:

    /// Defines the text box control.
        protected override Control CreateControl()
            TextBox control = new TextBox();
            control.MinimumSize = new Size(50, 0);
            control.MaximumSize = new Size(500, Int32.MaxValue);
            control.BackColor = Color.LightBlue;
            control.Font = new Font("Tahoma", 9, FontStyle.Bold);
            control.DoubleClick += control_DoubleClick;        
            return control;
    /// Raises an event when the user double-clicks the text box.
        private void control_DoubleClick(object sender, EventArgs e)
            int index = 0;
            string data = this.Control.Text;
            this.RaiseControlAddInEvent(index, data);


    If you want to create an add-in that spans both the caption column and the data column of the page, override the Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.IWinFormsControlAddIn.AllowCaptionControl property and return false (default value is true).

  6. Sign the add-in assembly. An assembly must be signed to be used in the RoleTailored client. Open the project's properties.

  7. On the Properties window, click Signing, and then select the Sign the assembly checkbox.

  8. In the Choose a strong name key file box, select <New…>.

  9. In the Key file name box, type RtcAddins.

    You can choose whether to use a password. For more information, see Strong-Name Signing for Managed Applications.

  10. Click OK.

  11. Build the solution.

Copying the Add-in Assembly to the Computer Running the RoleTailored Client

After you build the add-in, you copy the output assembly file to the computer running the RoleTailored client.

To copy the add-in assembly to the RoleTailored client

  1. On the development computer, locate the add-in assembly file in the add-in project's output folder.

    By default, this folder is C:\My Documents\Visual Studio\Projects\[Addin Project]\bin\Debug.

  2. On the computer running the RoleTailored client, copy the assembly to the RoleTailored client\Add-ins folder in the Microsoft Dynamics NAV 2009 installation folder.

    By default, the path to this folder is C:\Program Files\Microsoft Dynamics NAV\60\RoleTailored Client\Add-ins.

Registering the Add-in in Microsoft Dynamics NAV

To register an add-in, you include it in the Client Add-in table in Microsoft Dynamics NAV. To include an add-in in the table, you must provide the following information:

  • Add-in name

    The add-in name is determined by the Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute attribute value of add-in class definition that you specified when creating the control add-in. The name in this walkthrough is MyCompany.MyProduct.FieldPopupAddin, as shown in the following code snippet from interface definition:

    public class MyFieldPopupAddin : StringControlAddInBase
  • Public key token

    This is a 16-character key that is given to the assembly when it is signed and built in Visual Studio. To determine the public token key, run the Microsoft .NET Strong Name Utility (sn.exe) on the assembly. The sn.exe utility is available with the Visual Studio 2005 and Visual Studio 2008 SDKs.

To determine the add-in's public key token

  1. At a command prompt, change to the directory that contains the sn.exe utility.

    For example, the default directory for Microsoft Visual Studio 2008 is C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin.

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

  3. Press ENTER and note the public token key that is displayed.

To include the add-in in the Client Add-in table

  1. Open the Classic client.

  2. On the Tools menu, click Object Designer.

  3. Click Tables, and then locate the table with ID 2000000069 and name Client Add-in.

  4. Click the table, and then click Run.

  5. On a blank line in the Client Add-in table, fill out the Control Add-In Name and Public Key Token fields.

    In this walkthrough, the name is MyCompany.MyProduct.FieldPopupAddin.

  6. Close the Client Add-in table.

Setting Up the Add-in on a Page

In this section, you will modify the Customer Card page to use the new add-in on the name field. This involves the following tasks:

To set the ControlAddIn property on the field

  1. In Object Designer, click Page.

  2. Select the page with ID 21 and name Customer Card, and then click Design.

  3. Select the Name field, and then on the View menu, click Properties.

  4. In the ControlAddIn property value, click the lookup button, and then select the MyCompany.MyProduct.FieldPopupAddin from the Client Add-in window.

  5. Click OK.

  6. Close the Properties window.

To set the add-in trigger in the C/AL Code

  1. On the View menu, click C/AL Code.

  2. In the C/AL Editor, locate the following trigger:

    Name - OnControlAddIn(Index : Integer;Data : Text[1024])
  3. Add the following code:

  4. Close the C/AL Editor.

  5. On the File menu, click Save, select Compiled, and then click OK.

To test the add-in

  • To test the add-in, in Object Designer, select the Customer Card page, and then click Run.

See Also


How to: Create a RoleTailored Client Control Add-in
How to: Determine the Public Key Token of the RoleTailored Client Control Add-in
How to: Install a RoleTailored Client Control Add-in Assembly
How to: Register a RoleTailored Client Control Add-in
How to: Set up a RoleTailored Client Control Add-in on a Page


RoleTailored Client Control Add-in Overview
Developing RoleTailored Client Control Add-ins
Client Extensibility API Overview
Binding a RoleTailored Client Control Add-in to the Database
Calling C/AL Triggers from a RoleTailored Client Control Add-in
Installing and Configuring RoleTailored Client Control Add-ins on Pages