Share This Post

D365 Business Central .NET Control Add-Ins

It is recommended that you convert your existing D365 Business Central .NET Control Add-Ins and Javascript Add-Ins to native AL D365 Business Central Control Add-Ins that are supported both on-premises and in the cloud.

In Dynamics 365 Business Central on-premises you can use existing .NET and Javascript control add-ins from the AL Language through .NET interoperability.

To declare the usage of a .NET or Javascript add-in in AL, you need three critical pieces of information about the .NET type that represent the interface of the add-in. These are the name of the assembly having the add-in, the name of the D365 Business Central Control Add-Ins and the name of the class that implements the control add-in.

We will show how to retrieve this information for the Microsoft.Dynamics.Nav.Client.PingPong control add-in that ships with Business Central.

The name of the assembly can be retrieved from the AssemblyName element in the .csproj file associated with the .NET project that shows the control add-in. In this case the name of the assembly is Microsoft.Dynamics.Nav.Client.PingPong.

D365 Business Central .NET Control Add-Ins Object

The control add-in object allows you to add custom functionality to Dynamics 365 Business Central. A control add-in is a visual element for displaying and modifying data or a custom control within an iframe or a page.

For example, a control add-in can show the content of a webpage, visualize data as a chart or on a map, or host a custom web application. The D365 Business Central Control Add-Ins can interchange the data with the MS D365 server on many data types and can respond to user interaction to raise events that execute additional AL code.

Control Add-in Properties

In the control add-in definition, you must setup the Scripts property to include scripts in the control add-in. The scripts could be local files in the package or references to the external files utilizing the HTTP or the HTTPS protocol.

With the StartupScript property, you can call a special script that runs when the page you have implemented the control add-in on, is loaded. These settings initialize the control add-in. With the Imagesand StyleSheet properties, you can specify additional styling to the control add-in.

Control Add-in Considerations

Designing control add-ins that provide the best possible experience can require some additional planning, design, and implementation. The following considerations will help you design add-ins that look and feel seamlessly integrated with Dynamics 365 Business Central.

  • Respond to touch events so that mobile users or those on devices supporting touch input can also use the add-in.
  • Design content that is responsive and is able to flow, resize, or reorganize naturally based on the available space.
  • Consider the accessibility needs of users, for example by implementing keyboard access and support for screen readers.
  • Use the Style guidelines to apply a choice of colors, typefaces, and font sizes that match that of Microsoft Dynamics 365 Business Central.
  • Provide language translation and other localization’s that match the current user language in Dynamics 365 Business Central.

The following code sample contains the stub definition of the Microsoft.Dynamics.Nav.Client.PingPong.NET add-in.

namespace Microsoft.Dynamics.Nav.Client.PingPong
{

/// <summary>
/// Add-in for pinging the server from the client. The client will respond with a pong.
/// </summary>
[ControlAddInExport(“Microsoft.Dynamics.Nav.Client.PingPong”)]
public class PingPongAddIn : WinFormsControlAddInBase
{

/// <summary>
/// Event will be fired when the AddIn is ready for communication through its API
/// </summary>
[ApplicationVisible]
public event MethodInvoker AddInReady;

/// <summary>
/// Event will be fired when the specified time by the ping has elapsed.
/// </summary>
[ApplicationVisible]
public event MethodInvoker Pong;

/// <summary>
/// Starts the ping process.
/// </summary>
/// <param name=”milliseconds”>Number of milliseconds before ponging.</param>
/// <remarks>If a milliseconds are less than the minimum then the MinimumValue is used.</remarks>
[ApplicationVisible]
public void Ping(int milliseconds)
{

}
}

}

The next needed piece of information is the namespace-qualified name of the type annotated with the ControlAddInExport attribute.

This is the type that provides the implementation of the control add-in and which exposes members annotated with the ApplicationVisible attribute to the AL runtime. Here it is Microsoft.Dynamics.Nav.Client.PingPong.PingPongAddIn.

The ControlAddInExport attribute’s constructor takes as an argument the name of the D365 Business Central Control Add-Ins as represented in the runtime, and in existing C/AL code. The name of the control add-in in this example is Microsoft.Dynamics.Nav.Client.PingPong.

This was the last component needed to construct a declaration for this .NET control add-in in AL. The name of the assembly is used in creating the assembly construct, the namespace-qualified name of the type is used as the first element in the type declaration and the name of the D365 Business Central Control Add-Ins is utilized as the alias of the type.

You complete the declaration by setting the IsControlAddIn property to true. This property is used to tell the AL compiler to treat the given type declaration as a .NET control add-in declaration.

dotnet
{
assembly(“Microsoft.Dynamics.Nav.Client.PingPong”)
{
type(“Microsoft.Dynamics.Nav.Client.PingPong.PingPongAddIn”; “Microsoft.Dynamics.Nav.Client.PingPong”)
{
IsControlAddIn = true;
}
}
}

You can now use the Microsoft.Dynamics.Nav.Client.PingPong from AL, just as you use a native control add-in.

page 50100 MyPage
{
layout
{
area(Content)
{
usercontrol(PingPongControl; PingPongAddIn)
{
trigger Pong()
begin
Message(‘Pong received.’);
end;

trigger AddInReady()
begin
Message(‘Ready’);
end;
}
}
}
}

Remarks

Only members of the .NET type implementing the control add-in that are annotated with the ApplicationVisibleAttribute will be accessible from AL. Usages of .NET control add-ins in C/AL are automatically converted to AL by the Txt2Al conversion tool, but the code will only compile, if you manually insert the declaration of the control add-in, as shown above.

If inside the same project you have a native AL control add-in and a .NET add-in with the same name, the .NET add-in will be the one used. For more details on D365 Business Central Control Add-Ins, please contact us.

Share This Post

Leave a Reply

avatar
  Subscribe  
Notify of
Skip to toolbar