NoteNote

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.

You develop RoleTailored 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 are done developing a control add-in, you build and sign and assembly before you install it on the computer running the RoleTailored client.

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

To create the RoleTailored client control add-in

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

  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 control add-ins.

    • System.Windows.Forms

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

    Add additional references as required.

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

    C#  CopyCode imageCopy Code 
    using Microsoft.Dynamics.Framework.UI.Extensibility;
using Microsoft.Dynamics.Framework.UI.Extensibility.WinForms;
using System.Windows.Forms;

    Add additional references as required.

  4. 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:

    C#  CopyCode imageCopy Code 
    [ControlAddInExport("MyCompany.MyProduct.MyAddin")]
public class MyFieldPopupAddin : WinFormControlAddInBase, IObjectControlAddinDefinition
      CopyCode imageCopy Code 
    [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. 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 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 RoleTailored Client Control Add-in.

  5. Implement the abstract base method Microsoft.Dynamics.Framework.UI.Extensibility.WinForms.WinFormsControlAddInBase.CreateControl and add code that defines the control add-in.

    C#  CopyCode imageCopy Code 
    protected override Control CreateControl()
	 {
		 /// Include control add-in code here.
	 }

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

    For example, a field control on a RoleTailored page 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) as follows:

    C#  CopyCode imageCopy Code 
    public override bool AllowCaptionControl
{
get 
{ 
 return false;
}

    The caption will span the caption column and the data column of the page.

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

    C#  CopyCode imageCopy Code 
    	 public object Value
		{
			get
			{
				throw new NotImplementedException();
		}
			set
			{
				throw new NotImplementedException();
		}
	}
    NoteNote

    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 RoleTailored Client Control Add-in to the Database.

  8. To define events that call the OnControlAddin C/AL trigger of a page field control, add the following code to declare an event handler.

    C#  CopyCode imageCopy Code 
       public event ControlAddInEventHandler ControlAddIn;

    Add code to raise the event where appropriate.

    For more information, see Calling C/AL Triggers from a RoleTailored Client Control Add-in.

  9. 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 RoleTailored client, it must be signed. Signing gives the assembly a public token key, which is a unique identity that is used to ensure 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 RoleTailored 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 signing assemblies, see How to: Sign Assemblies and Strong-Name Signing for Managed Applications.

To sign the RoleTailored client add-in assembly

  1. Open the project's properties.

  2. On the Properties window, click the Signing tab.

  3. Select the Sign the assembly check box.

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

  5. Click OK.

For information about determining the public token key, see How to: Determine the Public Key Token of the RoleTailored Client Control Add-in.

Example

The following code illustrates a control add-in that implements the Microsoft digital ink control on a RoleTailored 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.

C#  CopyCode imageCopy Code 
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 the user is drawing.
					if (data != null && !this._loaded)
					{
						this._inkControl.Ink.Load(data);
						this._loaded = true;
				}
			}
		}
	}

		#endregion
}

See Also