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

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

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.

Roles

This walkthrough demonstrates tasks performed by the following user roles:

Microsoft .NET developer.
Microsoft Dynamics NAV developer and IT Pro.

Prerequisites

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.

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

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

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

C#	Copy Code
using Microsoft.Dynamics.Framework.UI.Extensibility; using Microsoft.Dynamics.Framework.UI.Extensibility.WinForms; using System.Windows.Forms; using System.Drawing;

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:

C#	Copy Code
[ControlAddInExport("MyCompany.MyProduct.FieldPopupAddin")] 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.

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

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

C#	Copy Code
/// 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); } }

C#

Copy Code

/// 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);
	
}
}

Note
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`).

Sign the add-in assembly. An assembly must be signed to be used in the RoleTailored client. Open the project's properties.
On the Properties window, click Signing, and then select the Sign the assembly checkbox.
In the Choose a strong name key file box, select <New…>.
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.
Click OK.
Build the solution.

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

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

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:
C# Copy Code
[ControlAddInExport("MyCompany.MyProduct.FieldPopupAddin")] 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.

C#	Copy Code
[ControlAddInExport("MyCompany.MyProduct.FieldPopupAddin")] public class MyFieldPopupAddin : StringControlAddInBase

To determine the add-in's public key token

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.
Type the following command:
Copy Code
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.

	Copy Code
sn.exe -T <assembly>

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

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 out the Control Add-In Name and Public Key Token fields.

In this walkthrough, the name is MyCompany.MyProduct.FieldPopupAddin.
Close the Client Add-in table.

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:

Setting the ControlAddin Property of the field to the add-in.
Setting the OnControlAddin Trigger trigger.

In the C/AL Editor, you set the trigger that is called when a user double-clicks the field to open a popup window. When a field is double-clicked, the add-in raises the Microsoft.Dynamics.Framework.UI.Extensibility.IEventControlAddInDefinition.ControlAddIn event which in turn calls the trigger.

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 MyCompany.MyProduct.FieldPopupAddin from the Client Add-in window.
Click OK.
Close the Properties window.

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

On the View menu, click C/AL Code.

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

	Copy Code
Name - OnControlAddIn(Index : Integer;Data : Text[1024])

Add the following code:
Copy Code
Message(Data);
Close the C/AL Editor.
On the File menu, click Save, select Compiled, and then click OK.

	Copy Code
Message(Data);

To test the add-in

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

Tasks

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

Concepts

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

About This Walkthrough

Roles

Prerequisites

Story

Creating an Add-in with Visual Studio 2005 or 2008

To create the add-in

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