Creating a Windows Client Control Add-in

Article
11/28/2017

You develop Microsoft Dynamics NAV Windows client control add-ins using the API that is defined in the Microsoft.Dynamics.Framework.UI.Extensibility assembly. A control add-in is defined as a class in a Visual C# solution. You can include more than one control add-in a single solution. When you have finished developing a control add-in, you build and sign an assembly before you install it on the computer that is running the Microsoft Dynamics NAV Windows client.

To create a control add-in, you need the following prerequisites:

Microsoft Visual Studio 2005, Microsoft Visual Studio 2008, Visual C# 2008 Express Edition, Microsoft Visual Studio 2010, or Microsoft Visual Studio 2012.
Microsoft.Dynamics.Framework.UI.Extensibility.dll assembly.

The assembly is installed with the Microsoft Dynamics NAV Windows client. By default, the path of the assembly is C:\Program Files\Microsoft Dynamics NAV\110\RoleTailored Client. For more information, see Deployment.
Windows Forms library (System.Windows.Forms.dll).

To create the Microsoft Dynamics NAV Windows client control add-in

In Visual Studio, create a Visual C# project type by using the Class Library template.
In the project, add references to the following assemblies:
- Microsoft.Dynamics.Framework.UI.Extensibility.dll assembly
  
  By default, the path of the assembly is C:\Program Files\Microsoft Dynamics NAV\110\RoleTailored Client. This reference is required for all control add-ins.
- System.Windows.Forms
  
  Contains classes for creating user interfaces for Windows-based applications.
  
  Add additional references as required.

Open the class.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;

Add additional references as required.

Declare a class for the control add-in that uses the [Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute] attribute. Derive the class from an abstract base class and implement the control add-in definition interface, as shown in the following examples.
```
[ControlAddInExport("MyCompany.MyProduct.MyAddin")]  
public class MyFieldPopupAddin : WinFormsControlAddInBase, IObjectControlAddInDefinition  
```
```
[ControlAddInExport("MyCompany.MyProduct.MyAddin")]  
public class MyFieldPopupAddin : StringControlAddInBase  
```
For information about the base classes and interfaces, see Client Extensibility API Overview.

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 [ControlAddInExportAttribute.Name] property, which in this case is MyCompany.MyProduct.MyAddin in C#. Because an assembly can contain more than one control add-in, the Microsoft Dynamics NAV Windows client uses the [Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute] attribute to differentiate each control add-in that is found in an assembly. The [ControlAddInExportAttribute.Name] is used to register the control add-in in Microsoft Dynamics NAV Server.

Tip

If you give the control add-in the same name as the assembly, then you do not have to install the assembly on the client computer. In this case, you only install the assembly on the computer that is running Microsoft Dynamics NAV Server. When a client requests the control add-in, Microsoft Dynamics NAV Server will automatically deploy the assembly to the client.

For more information, see How to: Register a Windows Client Control Add-in.

Implement the abstract base method [WinFormsControlAddInBase.CreateControl] and add code that defines the control add-in.

protected override Control CreateControl()  
       {  
           /// Include control add-in code here.  
       }

Add code to override additional base class members as required for your control add-in.

For example, a field control on a Microsoft Dynamics NAV Windows client can have a caption. If you do not want a caption, then override the [WinFormsControlAddInBase.AllowCaptionControl] property and return false (the default value is true).
```
public override bool AllowCaptionControl  
{  
get   
{   
 return false;  
}  
```
The caption will span the caption column and the data column of the page.
To bind the control add-in to data in the Microsoft Dynamics NAV database, add the following code that gets or sets the [IValueControlAddInDefinition.Value] property.
```
/// Gets a value indicating whether the Value property has  
/// changed its value.  
public bool HasValueChanged { get; set; }  

/// Gets or sets the Value Property.  
public object Value  
{  
    get  
    {  
        // Include value handling code here.  
        return null;  
    }  
    set  
    {  
        // Include value handling code here.  

    }  
}  
```
Note

The [Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.StringControlAddInBase] class already overrides the [IValueControlAddInDefinition.Value] property to transfer data between the control add-in and the Dynamics NAV database.

For more information, see Binding a Windows Client Control Add-in to the Database.
To define events that call the OnControlAddin C/AL trigger of a page field control, add the following C# code to declare an event handler.
```
public event ControlAddInEventHandler ControlAddIn;  
```
Add code to raise the event where appropriate.

For more information, see Exposing Events and Calling Respective C/AL Triggers from a Windows Client Control Add-in.
To add an event that will be represented by a new trigger in C/AL code of a Dynamics NAV page object, use the managed attribute [ApplicationVisibleAttribute] and add code for C# methods and properties.
```
[ApplicationVisible]  
     public void DrillDown(int nodeId)  
     {  
      …  
     }  

     public int SelectedNode  
     {  
      get {…}  
      set {…}  
     }  
```
The methods and properties must be public. For more information, see Exposing Methods and Properties in a Windows Client Control Add-in.
To add a method or property that can be called from the C/AL code of a Dynamics NAV page object, use the managed attribute [ApplicationVisibleAttribute] and add code for C# methods and properties.
```
/// <summary>  
/// Event will be fired when the AddIn is ready for communication through its API  
/// </summary>  

[ApplicationVisible]  
public event MethodInvoker AddInReady;  
```
The methods and properties must be public. For more information, see Exposing Methods and Properties in a Windows Client Control Add-in.
Build and sign the solution.

Signing an Assembly That Contains a Control Add-in

To use an assembly that contains a control add-in with the Microsoft Dynamics NAV Windows client, it must be signed. Signing gives the assembly a public token key, which is a unique identity that is used to make sure that the control add-in runs code from a trusted assembly. When you register a control add-in in Microsoft Dynamics NAV Server, you provide the public token key. At run time, the Microsoft Dynamics NAV Windows client uses the public token key to load the appropriate control add-in.

Assemblies are signed with a key file that contains the public key token and an optional password. You can sign an assembly that contains a control add-in by creating a new key file or using an existing one. For more information about how to sign assemblies, see How to: Sign Assemblies and Strong-Name Signing for Managed Applications.

To sign the Microsoft Dynamics NAV Windows client add-in assembly

Open the project's properties.
On the Properties window, choose the Signing tab.
Select the Sign the assembly check box.
In the Choose a strong name key file box, select New to create a new key file or Browse to use an existing key file.
Choose the OK button.

For information about how to determine the public token key, see How to: Determine the Public Key Token of the Windows Client Control Add-in and .NET Framework Assembly.

Example

The following code illustrates a control add-in that implements the Microsoft digital ink control on a Microsoft Dynamics NAV Windows client page field. For example, you could use this control add-in on a sales order page to allow customers to sign their sales orders with a tablet PC. The control add-in is designed to bind with a table field in the Dynamics NAV database to store and retrieve signatures. Because the signatures are transferred as binary data, the example implements the [Microsoft.Dynamics.Framework.UI.Extensibility.IObjectControlAddInDefinition]interface.

using System;  
using System.Collections.Generic;  
using System.Text;  
using Microsoft.Ink;  
using System.Drawing;  
using Microsoft.Dynamics.Framework.UI.Extensibility;  
using Microsoft.Dynamics.Framework.UI.Extensibility.WinForms;  
using System.Windows.Forms;  

namespace NavInkControl  
{  
    [ControlAddInExport("MyCompany.MyProduct.MyNavInkControlAddin")]  
    public class NavInkContol : WinFormsControlAddInBase, IObjectControlAddInDefinition  
    {  
        InkPicture _inkControl;  
        private bool _loaded = false;  

        /// Creates the control for displaying and adding signatures.  
        protected override Control CreateControl()  
        {  
            _inkControl = new InkPicture();  
            _inkControl.BorderStyle = System.Windows.Forms.BorderStyle.Fixed3D;  
            _inkControl.MinimumSize = new Size(40, 50);  
            _inkControl.MaximumSize = new Size(Int16.MaxValue, 100);  

            return _inkControl;              
        }  

        #region IObjectControlAddInDefinition Members  

        public event ControlAddInEventHandler ControlAddIn;  

        /// Gets a value indicating whether the Value property instance has changed. true if this instance has changed its value; otherwise, false.  
        public bool HasValueChanged  
        {  
            get { return _inkControl.Ink.Dirty; }  
        }  

        /// Gets or sets the value.  
        public object Value  
        {  
            get  
            {  
                return this._inkControl.Ink.Save();  
            }  
            set  
            {  
                if (value is byte[])  
                {  
                    byte[] data = (byte[])value;  

                /// Specifies that the data loads only once so that data cannot load while the user is drawing.  
                    if (data != null && !this._loaded)  
                    {  
                        this._inkControl.Ink.Load(data);  
                        this._loaded = true;  
                    }  
                }  
            }  
        }  

        #endregion  
    }

Share via

Creating a Windows Client Control Add-in

To create the Microsoft Dynamics NAV Windows client control add-in

Signing an Assembly That Contains a Control Add-in

To sign the Microsoft Dynamics NAV Windows client add-in assembly

Example

See Also

Additional resources