Walkthrough: Creating and Using a Client Control Add-in

Article
09/30/2015

This walkthrough demonstrates how to create a Microsoft Dynamics NAV control add-in and use it on a Microsoft Dynamics NAV page. A client control add-in enables you to add custom functionality to the Microsoft Dynamics NAV Windows client and the Microsoft Dynamics NAV Web client by creating a control add-in that can run on both client platforms.

Important

This walkthrough addresses the Microsoft Dynamics NAV implementation of extensibility. This makes it possible to write control add-ins for all display targets. For information about how to write control add-ins specifically for Microsoft Dynamics NAV Windows client, see Extending the Windows Client Using Control Add-ins.

In a typical business scenario, developers create control add-ins using Microsoft Visual Studio Express, or Visual Studio 2013. Implementers of Microsoft Dynamics NAV solutions then use the control add-ins on Microsoft Dynamics NAV client pages, such as the Microsoft Dynamics NAV Windows client, the Microsoft Dynamics NAV Web client, or the Microsoft Dynamics NAV Tablet client.

Prerequisites

To complete this walkthrough, you will need:

Microsoft Dynamics NAV with a developer license. For more information, see System Requirements for Microsoft Dynamics NAV 2016.
CRONUS International Ltd. demonstration database.
Microsoft Visual Studio Express or Microsoft Visual Studio 2013.
Microsoft .NET Strong Name Utility (sn.exe). This is included with Windows SDKs.
Experience using Visual Studio.

Story

Simon is a software developer working for CRONUS International Ltd. He has been told that the users of the Microsoft Dynamics NAV Web client want to see Bing Maps displayed on the Web client. He wants to use the client extensibility framework to test how to do this on a separate page first.

Creating a Control Add-in With Visual Studio

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

To create the control add-in

In Visual Studio, on the File menu, choose New, and then choose Project.
Under Installed Templates, choose Visual C#, and then choose Class Library.
In the Solution Name text box, enter the name of your solution. For example, you can enter BingMapsControlAddIn and then choose the OK button.
You will add a reference to the following assembly: Microsoft.Dynamics.Framework.UI.Extensibility.dll
In Solution Explorer, right-click your project, and then choose Add Reference.
In the Add Reference window, on the Browse tab, navigate to the location of the Microsoft.Dynamics.Framework.UI.Extensibility.dll assembly on your computer, and then choose the OK button. By default, the path of the assembly is C:\Program Files (x86)\Microsoft Dynamics NAV\90\RoleTailored Client.
Open the Class1.cs file and add the following using directive.
```
using Microsoft.Dynamics.Framework.UI.Extensibility;
```

In the BingMapsControlAddIn namespace, add the following code to declare a new interface named BingMapsControlAddIn.

namespace BingMapsControlAddIn
{
    [ControlAddInExport("BingMapsControl")]
    public interface IBingMapsControlAddIn
    {
        [ApplicationVisible]
        event ApplicationEventHandler ControlAddInReady;
        [ApplicationVisible]
        event ApplicationEventHandler MapLoaded;
        [ApplicationVisible]
        void LoadMap(double latitude, double longitude);
        [ApplicationVisible]
        void ShowMiniMap(bool show);
        [ApplicationVisible]
        void ShowPushpin(string title, string imageName);
    }
}

You will use the name BingMapsControl later in the walkthrough when you register the control add-in in Microsoft Dynamics NAV.

The assembly must now be signed to be used with Microsoft Dynamics NAV. The next steps will discuss how to sign the assembly.

To sign the assembly

In Visual Studio, on the Project menu, choose BingMapsControlAddIn properties.
In the Properties window, choose Signing, and then select the Sign the assembly check box.
In the Choose a strong name key file drop-down list, select New.
In the Key file name text box, enter BingMapsControlAddIn, and then clear the Protect my key file with a password check box.
Choose the OK button.
In Solution Explorer, notice the BingMapsControlAddIn.snk file that is added in Solution Explorer.
On the Build menu, choose Build <Your Solution> to build the project. Verify that the build succeeds.

Copying the Control Add-in Assembly to the Microsoft Dynamics NAV Development Environment

After you build the control add-in, you copy the output assembly file to the computer that is running the development environment.

To copy the control add-in assembly to the Microsoft Dynamics NAV Development Environment

On the computer, locate and copy the control add-in assembly file (.dll) file in the control add-in project’s output folder.
By default, this folder is C:\Documents\MyDocuments\Visual Studio\Projects\[Your Addin Project]\[Your Class Library]\bin\Debug.
On the computer that is running the development environment, paste the assembly in the Add-ins folder.

By default, this folder is C:\Program Files (x86)\Microsoft Dynamics NAV\90\RoleTailored Client\Add-ins.

Creating the Manifest File

After you create an interface in Visual Studio that exposes a number of properties for the BingMapsControlAddIn, you must create a manifest file. A manifest file is written in XML and contains information such as where to look for resource files, references to external JavaScripts, and the size of the control add-in. For more information, see Manifest Overview. In the next steps, you will create a manifest file that loads a BingMaps control and you will register this manifest in the Client Add-in page.

To create the manifest file

Copy this sample manifest and paste it into any text editor.

<?xml version="1.0" encoding="utf-8"?>
<Manifest>
    <Resources>
        <Script>Script.js</Script>
    </Resources>
    <ScriptUrls>
      <ScriptUrl>http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.3</ScriptUrl>
    </ScriptUrls>

    <Script>
        <![CDATA[
           InitializeMap('controlAddIn');
           Microsoft.Dynamics.NAV.InvokeExtensibilityMethod('ControlAddInReady', null);
        ]]>
    </Script>

    <RequestedHeight>300</RequestedHeight>
    <RequestedWidth>700</RequestedWidth>
    <VerticalStretch>false</VerticalStretch>
    <HorizontalStretch>false</HorizontalStretch>
</Manifest>

Save the manifest to a file that is in same directory that the assembly is saved in, the Add-ins directory.

Name the manifest Manifest and make sure to add the .xml extension to the file, so that the file name will now be Manifest.xml.

The next step is to create a JavaScript file containing code that calls C/AL in Microsoft Dynamics NAV.

Creating a JavaScript File

Now you must create a JavaScript file to hold all of the code that calls C/AL in Microsoft Dynamics NAV.

To create the JavaScript file

Copy this sample script and paste it into any text editor.

var map = null;
    function InitializeMap(controlId) {
        map = new VEMap(controlId);
        map.HideScalebar();
        map.onLoadMap = function () {
        Microsoft.Dynamics.NAV.InvokeExtensibilityMethod ('MapLoaded', null);
        };
    }
    function LoadMap(latitude, longiture) {
        var mapOptions = new VEMapOptions();
        mapOptions.DashboardColor = "black";
        mapOptions.EnableSearchLogo = false;
        map.LoadMap(
            new VELatLong(latitude, longiture), // Center
            1,                                  // Zoom level 1-19
            VEMapStyle.Birdseye,                // Map style
            false,                              // Fixed map
            VEMapMode.Mode2D,                   // Map mode
            true,                               // Map mode switch
            0,                                  // Tile buffer
            mapOptions                          // Options
        );
    }        
    function ShowMiniMap(show) {
        if (show)
            map.ShowMiniMap();
        else
            map.HideMiniMap();
    }
    function ShowPushpin(title, imageName) {
        map.Clear(); 
        if (title != '') {
            var point = map.GetCenter();
            var pushpin = map.AddPushpin(point);
            pushpin.SetTitle(title);
        }
    }

Save and name the script Script and make sure to add the .js extension to the file, so that the file name will now be Script.js.

The next step is to create a .zip file containing the manifest and resource files and register this file with the control add-in in Microsoft Dynamics NAV.

Creating a Resource .Zip File

Before registering the control add-in in Microsoft Dynamics NAV, you must create one single file containing the manifest and any resource files. This single file is a .zip file and it will be registered in the Client Add-in page. The .zip file must contain a certain structure for it to be recognized by the Client Add-in page. In the next steps, you will create the right structure and a .zip file.

To create a resource .zip file

On your computer, in a folder of your own choice, create the following folder structure: Image, Script, and StyleSheet.
Locate the Manifest.xml file that you created in the previous steps, and copy this to the same folder structure. Then locate the Script.js file that you created in the previous steps, and copy this to the Script folder. Your folder should now look like this:
Place images, scripts, and stylesheets in the right folders, but in this walkthrough we will leave the rest of these folders empty.
In the Windows Explorer mark all of the folders and the manifest file and right-click, and then choose Send to…, and then choose Compressed (zipped) folder.
Name the .zip file BingMapsControlAddIn.

Registering the Control Add-in in Microsoft Dynamics NAV

To register a control add-in, you include it in the Control Add-in page in Microsoft Dynamics NAV. To include a control add-in in the page, you must provide the following information:

Control Add-in name.

The control add-in name is determined by the Microsoft.Dynamics.Framework.UI.Extensibility.ControlAddInExport attribute value of control add-in class definition that you specified when you created the control add-in. The name in this walkthrough is BingMapsControl.
Public key token.

This is a 16-character key that is given to the assembly when it is signed and built in Visual Studio. You can determine the public key token by running the Microsoft .NET Strong name Utility (sn.exe) on the assembly. You must run the utility from the Visual Studio command prompt. The sn.exe utility is available with Visual Studio.
Resource.

On the Control Add-in page, the Resource field is a BLOB data type and the content of the field cannot be viewed from the development environment.

When this field is filled in, Microsoft Dynamics NAV identifies the registered control add-in as a type of control add-in that works on all display targets.

To determine the public key token for the control add-in

On the Windows taskbar, choose Start, choose All Programs, choose Microsoft Visual Studio 2013, choose Visual Studio Tools, and then choose Developer Command Prompt for VS2013 to open the command prompt.
At a command prompt, change to the directory that contains the assembly that you copied. For example, C:\Program Files (x86)\Microsoft Dynamics NAV\90\RoleTailored Client\Add-ins.
Type the following command: sn –T <assembly>

Replace <assembly> with the assembly name, such as BingMapsControlAddIn.dll.
Press Enter and note the public token key that is displayed.

To include the control add-in in the Control Add-in page

Open Microsoft Dynamics NAV.
In the Search box, enter Control Add-ins and then choose the related link.
In the Control Add-ins window, choose New, and then in the Control Add-in Name column, enter the control add-in name. In the Public Key Token column, enter the public key token that you obtained earlier.

With the Control Add-in window still open, you will now import the .zip file for the BingMapsControlAddIn add-in.

To include the .zip file in the Control Add-in page

Choose Import.
In the Import Control Add-in Resource window, locate the BingMapsControlAddIn.zip file that you saved earlier, and then choose Open.
Choose the OK button to close the Control Add-in page.

Creating a Page to Display the Control Add-in

You have set up the prerequisites for using a control add-in from a page. Now you need a way to display the BingMapsControlAddIn control. In this section, you will create a new page called Bing Maps that contains two fields to control the coordinates of the map and one field that contains the map control. This involves the following tasks:

Creating a new page called Bing Maps.
Setting variables and properties.
Adding C/AL triggers.

To create the Bing Maps page

In the Microsoft Dynamics NAV Development Environment, in Object Designer, choose Page, and then choose New.
In the New Page dialog, choose Create blank page and then choose the OK button.
In Page Designer, on the first line, in the Name column, enter Control1, and go to the next line.
In the Type column, choose Group, and in the Caption column, enter Coordinates.
On a new line, in the Type column, choose Field. In the Name column, enter LatitudeControl, and in the Caption column, enter Latitude.
On a new line, in the Type column, choose Field. In the Name column, enter LongitudeControl, and in the Caption column, enter Longitude.
On a new line, choose Group, and in the Caption column, enter Map.
On a new line, under the Map group, for the Type column set to Field, in the Name column, enter Bing Maps Control.

Your page design should now look like this.
Save and compile the page. Name the page Bing Maps.

Now you have created a page skeleton. The next step is to add code and call the control add-in from a control on the page.

To add variables and properties

In the Microsoft Dynamics NAV Development Environment, in Object Designer, choose Page, and then choose the Bing Maps page.
On the Tools menu, choose View, and then C/AL Globals.
On the Variables tab, enter Latitude in the Name column, and set the DataType to Decimal.
Create a new variable. Enter Longitude in the Name column, and set the DataType to Decimal.
Create a new variable. Enter MiniMap in the Name column, and set the DataType to Boolean.
Close the C/AL Globals window.
In Page Designer, on LatitudeControl, set SourceExpr to Latitude in the C/AL Symbol Menu.
On LongitudeControl, set SourceExpr to Longitude in the C/AL Symbol Menu.
Select the BingMapsControl field, and then on the View menu, choose Properties.
In the Properties window, locate the ControlAddIn property and choose the Up Arrow. Select the BingMapsControl control add-in from the Client Add-in window.
Choose the OK button to close the Client Add-In window. The public key token is inserted into the Value field. Close the Properties window.

To add C/AL triggers

With the Bing Maps page open in Object Designer, on the View menu, choose C/AL Code.
In the Page Bing Maps – C/AL Editor window, locate the BingMapControl::ControlAddInReady() trigger, and add the following line of code.
```
CurrPage.BingMapControl.LoadMap(Latitude, Longitude);
```
In the Page Bing Maps – C/AL Editor window, locate the BingMapControl::MapLoaded() trigger, and add the following line of code.
```
CurrPage.BingMapControl.ShowMiniMap(MiniMap);
```
Finally, locate the OnInit() trigger, and add the following line of code.
```
Latitude := 40.689467;
Longitude :=  74.044444;
```
Save and compile the Bing Maps page.

After you have saved and compiled the Bing Maps page, you can run the page directly from the development environment to verify that it works on the Microsoft Dynamics NAV Web client. For more information, see Opening a Page in the Microsoft Dynamics NAV Web Client by Using a URL.

Next Steps

Now you have created a Client Control Add-in that runs on the Microsoft Dynamics NAV Windows client, the Microsoft Dynamics NAV Web client, and the Microsoft Dynamics NAV Tablet client. A next step could be to implement a control add-in on an existing page or on the Role Center to display a Bing Map of where customers are located.