How to: Create a Windows Client Control Add-in

Artículo
10/18/2021

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 or Microsoft Visual Studio 2010.
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\70\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\70\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 Microsoft.Dynamics.Framework.UI.Extensibility.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 Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExportAttribute.Name is used to register the control add-in in Microsoft Dynamics NAV Server. For more information, see How to: Register a Windows Client Control Add-in.
Implement the abstract base method Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.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 Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.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 Microsoft.Dynamics.Framework.UI.Extensibility.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 Microsoft.Dynamics.Framework.UI.Extensibility.IValueControlAddInDefinition.Value property to transfer data between the control add-in and the Microsoft 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 Microsoft 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 Microsoft 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.

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 Microsoft 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
    }

Compartir a través de

How to: Create 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

Tasks

Concepts

Recursos adicionales