Visual Studio Code Example Extension

-->

This walkthrough will guide you through all the steps that you must follow to create a sample extension in AL. New objects and extension objects will be added to the base application for a simple reward feature for customers. Every section of this exercise includes code that serves for installing, customizing, or upgrading this sample extension. The final result can be published and installed on your tenants.

About this walkthrough

For Codespaces, install the Visual Studio Codespaces extension in VS Code, and use the Codespaces: Create New Codespace command. Docker / the Codespace should have at least 4 Cores and 6 GB of RAM (8 GB recommended) to run full build. VS Code Extension Samples This repository contains sample code illustrating the VS Code extension API. Each sample is a self-contained extension that explains one topic in VS Code API or VS Code's Contribution Points. You can read, play with or adapt from these samples to create your own extensions. You can expect from each sample. Calling CMake using Visual Studio Code extensibility. There are currently two Visual Studio Code extensions in the Visual Studio Code marketplace. The first extension provides the language service support for CMake the latter will allow for building your CMake targets. For a good CMake experience in Visual Studio Code install both extensions. Here is a list of 15 must-have Visual Studio extensions that are important for developers: Visual Studio Spell Checker; CodeMaid; VS Color Output; Visual Studio IntelliCode; Trailing Whitespace Visualizer; Magical C# Debugging—OzCode; ReSharper; Glyphfriend; SlowCheetah; File Icons; Image Optimizer; File Nesting; Roslynator; NCrunch for Visual Studio.

This walkthrough illustrates the following tasks:

Developing a sample extension with a table, a card page, and a list page.
Deploying the sample extension to your development sandbox environment.
Using the Dynamics 365 Business Central Designer to modify visual aspects of the extension.
Creating extension objects that can be used to modify page and table objects.
Initializing the database during the installation of the extension.
Upgrading and preserving data during the upgrade of the extension.

Prerequisites

To complete this walkthrough, you will need:

The Dynamics 365 Business Central tenant.
Visual Studio Code.
The AL Language extension for Visual Studio Code.

For more information on how to get started with your first extension for Dynamics 365 Business Central, see Getting Started.

Rewards extension overview

The extension enables the ability to assign one of three reward levels to customers: GOLD, SILVER, and BRONZE. Each reward level can be assigned a discount percentage. Different types of objects available within the AL development environment will build the foundation of the user interface, allowing the user to edit the information. If you look for another option to update the layout of a page, you can use the Designer drag-and-drop interface. Additionally, this exercise contains the install code that will create the base for the reward levels. The upgrade code is run to upgrade the extension to a newer version and it will change the BRONZE level to ALUMINUM. Following all the steps of this walkthrough allows you to publish the extension on your tenant and create a possible new feature for your customers.

Reward table object

The following code adds a new table 50100 Reward for storing the reward levels for customers. The table consists of three fields: Reward ID, Description, and Discount Percentage. For example, the Description field must contain a value of type text and it cannot exceed the limit of 250 characters. The second field contains three properties that are used to set the range of the discount percentage assigned to every customer. Properties can be created for every field, depending on the scope.

Tip

Type ttable followed by the Tab key. This snippet will create a basic layout for a table object.

For more information about table properties, see Table Properties.

Reward card page object

The following code adds a new page 50101 Reward Card for viewing and editing the different reward levels that are stored in the new Reward table. Pages are the primary object that a user will interact with and have a different behavior based on the type of page that you choose. The Reward Card page is of type Card and it is used to view and edit one record or entity from the Reward table.

Tip

Use the snippet tpage, Page to create the basic structure for the page object.

For more information about the types of pages in AL, see Pages Overview.

Reward list page object

The following code adds the 50102 Reward List page that enables users to view the contents of the Reward table and edit specific records by selecting them and viewing them in the Reward Card page.

Tip

Use the snippet tpage, Page of type list to create the basic structure for the page object.

After you have created the objects, update the startupObjectId in the launch.json file to 50102, the ID of the Reward List page and select the Ctrl+F5 shortcut to see the new page in your sandbox environment. You will be asked to sign in to your Business Central, if you have not already done so.

Tip

Information about your sandbox environment and other environments is stored as configurations in the launch.json file. For more information, see JSON Files.

Designer

Dynamics 365 Business Central Designer works in the browser and allows modifying the current page. It enables users to add existing table fields, move fields around, or remove fields from the page. Users can make changes to display the information they need, where they need it by using drag-and-drop components.
To show how the Designer changes the design of a page, you begin by adding two new fields to the Reward table. These fields will be used later on to exemplify the Designer's properties.

The Last Modified Date field requires constant changes to remain accurate. To keep it updated, triggers will be used. Triggers are predefined methods that are executed when certain actions happen. They are added by default when you use the ttable template, but you can also use the ttriger snippet to add them manually. Now you can add code to the triggers.

From this point, changes to the Reward Card page can be done either manually by adding the code below in Visual Studio Code or by using the Designer's functions to add the same fields. Both ways lead to the same results, but the Designer speeds up the process.

Using the F6 key shortcut in Visual Studio Code launches the browser and enters the Designer. You can also use the Designer from the Business Central client, by selecting Designer.

Note

Every time you start designing, you create a new extension and the changes you make in the Designer will apply to all users.

To add the same fields and customize the Reward Card page, follow the next steps:

Navigate to the Reward Card page by choosing + new.
Enter the Designer mode from the UI and select More from the Designer bar.
Select Field from the Designer bar to show the list of available fields.
Drag the Minimum Purchase and Last Modified Date fields from the list onto the page in the Reward group.
Choose the Reward in the group caption to enable the value to be edited. Change the caption to Info and press Enter.

After making these adjustments, finish up your design by choosing Stop Designing, which allows you to name the extension with an option to download code, and save the extension for the tenant. If you choose not to download the code at the end, you can still pull the changes via the Alt+F6 key shortcut from Visual Studio Code. You can also uninstall the extension by opening the Extension Management page.
For more information about Designer, see Designer.

Customer table extension object

The Customer table, like many other tables, is part of the Dynamics 365 Business Central service and it cannot be modified directly by developers. To add additional fields or to change properties on this table, developers must create a new type of object, a table extension.The following code creates a table extension for the Customer table and adds the Reward ID field.

Tip

Use the snippet ttableext to create a basic structure for the table extension object.

Customer card page extension object

A page extension object can be used to add new functionality to pages that are part of the Dynamics 365 Business Central service. The following page extension object extends the Customer Card page object by adding a field control, Reward ID, to the General group on the page. The field is added in the layout section, while in the actions section the code adds an action to open the Reward List page.

Tip

Use the shortcuts tpageext to create the basic structure for the page extension object.

At this point, reward levels can be created and assigned to customers. To do that, update the startupObjectId value in launch.json to 21 and select the Ctrl+F5 key to open the page.

Help links

This app is relatively straightforward, but we want users of your app to be able to get unblocked and learn more just like all other users of Business Central. First, configure your app to get context-sensitive links to Help, and then apply tooltips to the fields in your pages.

Configure context-sensitive links to Help

At an app level, you can specify where the Help for your functionality is published in the app.json file. Then, for each page in your app, you specify which Help file on that website is relevant for that particular page. For more information, see Configure Context-Sensitive Help.

Open the app.json file, and then change the value of the contextSensitiveHelpUrl property to point at the right location on your website. In this example, you publish Help for your app at https://mysite.com/documentation.

Next, you set the ContextSensitiveHelpPage property for the Reward Card and Reward List pages:

The following example illustrates the properties for the Reward List page after you have specified the context-sensitive Help page.

You can specify the same relative link for Reward Card, Reward List, and the customization of the Customer page, or you can specify different targets. For more information, see Page-level configuration.

Add tooltips

Even the best designed user interface can still be confusing to some. It can be difficult to predict specifically what users will find confusing, and that is why the base application includes tooltips for all controls and actions. For more information, see Help users get unblocked.

For the purposes of this walkthrough, add the following tooltip to the properties of the Reward ID field on all three pages:

The following example illustrates the tooltip:

If you now deploy the app, you will be able to read the tooltip text for the Reward ID field, and if you choose the Learn more link or press Ctrl+F1, a new browser tab opens the equivalent of https://mysite.com/documentation/sales-rewards.

Install code

After installing the extension, the Reward List page is empty. This is the result of the fact that the Reward table is also empty. Data can be entered manually into the Reward table by creating new records from the Reward List page. However, this task slows down the process, especially because the Reward table should be initialized with a standard number of reward levels when the extension is installed. To solve this, install codeunits can be used. A codeunit is an object that can be used to encapsulate a set of related functionality represented by procedures and variables. An install codeunit is a codeunit with the Subtype property set to Install. This codeunit provides a set of triggers that are executed when the extension is installed for the first time and when the same version is re-installed.

In this example, the following install codeunit initializes the Reward table with three records representing the 'GOLD', 'SILVER', and 'BRONZE' reward levels.

Tip

Use the shortcuts tcodeunit to create the basic structure for the codeunit.

For more information about install code, see Writing Extension Install Code.

Upgrade code

When you upgrade an extension to a newer version, if any modifications to the existing data are required to support the upgrade, you must write upgrade code in an upgrade codeunit. In this example, the following upgrade codeunit contains code that changes the BRONZE reward level to customer records to ALUMINUM. The upgrade codeunit will run when you run the Start-NAVAppDataUpgrade cmdlet.

Important

Remember to increase the version number of the extension in the app.json file.

For more information about writing and running upgrade code, see Upgrading Extension.

Instrumenting your app with telemetry

Business Central emits telemetry data for several operations that occur when extension code is run. Create an Application Insights resource in Azure if you don't have one. For more information, see Create an Application Insights resource. Now, add the Application Insights Key to the extension manifest (app.json file):

Replace <instrumenation key> with your key.

You can configure your extension to send this data to a specific Application Insights resource on Microsoft Azure. For more information, see Sending Extension Telemetry to Azure Application Insights.

Conclusion

This walkthrough demonstrated how an extension can be developed. The main AL objects and extension objects were used to store the reward levels, to view, and to edit them. The Designer was introduced as an alternative to modify visual aspects of page objects and to customize them from the web client instead of using code. Up to this point, the table and the page objects were empty, but the install codeunits were added and allowed to initialize the Reward table with a standard number of reward levels when the extension was installed. An upgrade code section was also included in this exercise to create a full picture of all processes involved when an extension is built. As a result, a user is enabled to assign one of the three reward levels to a customer and to change this scenario by upgrading the version of the extension.

Tip

To try building a more advanced Customer Rewards sample extension, see Building an Advanced Sample Extension.

Prerequisites

Node.js installed on your machine following How To Install Node.js and Create a Local Development Environment.

Installing the Tools

The Visual Studio Code team created a generator for creating extensions, which generates all of the necessary starter files to begin creating your extension.

To get started, you’ll need to have Yeoman installed, which is a scaffolding tool. You can install Yeoman by running

With Yeoman installed, now you need to install the specific generator for Visual Studio Code extensions:

Creating Your First Extension

You are now ready to create your first extension. To do so, run the following command.

You will then answer several questions about your project. You will need to choose what kind of extension you are creating and between TypeScript and JavaScript. We will be choosing JavaScript in this tutorial.

Then you’ve got a few more questions.

name
identifier
description
type checking (yes)
do you want to initialize a git repository (yes)

After this process is complete, you’ve got all of the files you need to get started. Your two most important files are:

package.json
extension.js

Open package.json and let’s take a look. You’ll see the name, description, and so on. There are two more sections that are very important.

activationEvents: this is a list of events that will activate your extension. Extensions are lazy loaded so they aren’t activated until one of these activation events occur.
commands: list of commands that you provide the user to run via your extension.

We will come back to these shortly.

You can also take a look at the extension.js file. This is where we are going to write the code for our extension. There’s some boilerplate code in here, so let’s break it down.

In the highlighted line below is where our command is being registered with VS Code. Notice that this name extension.helloworld is the same as the command in package.json. This is intentional. The package.json defines what commands are available to the user, but the extension.js file registers the code for that command.

In this Hello World example, all this command will do is display a Hello World message to the user.

Debugging Your Extension

Now that we have all of the necessary files installed, we can run our extension.

The .vscode folder is where VS Code stores configuration files of sorts for your project. In this case it includes a launch.json that contains debug configurations.

From here, we can debug. Open the debug tab on the left on the left of your screen, and then click play.

This will open up a new (debug) instance of VS Code.

With this debug instance of VS Code open, you can open the command palette with Cmd + SHIFT + P on Mac or CTRL + SHIFT + P on Windows and run 'Hello world'.

You’ll see a hello world message pop up in the lower right hand corner.

Editing Your Extension

Before we work on code, let’s take one more look at the activationEvents section in the package.json file. Again, this section contains a list of events that will activate our extension whenever they occur. By default, it is set to activate when our command is run.

In theory, this event could be anything, and more specifically * anything. By setting the activation event to * this means your extension will be loaded when VS Code starts up. This is not required by any means, just a note.

We’ve got the necessary files and we know how to debug. Now let’s start building our extension. Let’s say we want this extension to be able to create an HTML file that already has boilerplate code in it and is added into our project.

Let’s first update the name of our command. In extension.js, update the name of the command from extension.helloworld to extension.createBoilerplate.

Now, update the package.json file accordingly witht he change in command.

Now, let’s write our functionality. The first thing we’ll do is require a couple of packages. We are going to use the fs (file system) and path modules.

We also need to get the path to the current folder. Inside of the command, add the following snippet:

We will also need to store our boilerplate HTML code into a variable so that we can write that to a file. Here’s the boilerplate HTML:

Now we need to write to the file. We can call the writeFile function of the file system module and pass in the folder path and HTML content.

Notice that we use the path module to combine the folder path with the name of the file we want to create. Then inside of callback, if there is an error, we display that to the user. Otherwise, we let the user know that we created the boilerplate file successfully:

Here’s what the full function looks like:

Go ahead and debug your newly developed extension. Then, open up the command palette and run “Create Boilerplate” (remember we changed the name).

After running the command, you’ll see the newly generated index.html file and a message to let the user know:

Visual Studio Code Extension Development

Conclusion

C++ Visual Studio Code Example

To learn more about what APIs there are to use and how to use them, read through the Visual Studio Code Extension API documentation.

Warloading672

Visual Studio Code Example Extension

About this walkthrough

Prerequisites

Rewards extension overview

Reward table object

Reward card page object

Reward list page object

Designer

Customer table extension object

Customer card page extension object

Help links

Configure context-sensitive links to Help

Add tooltips

Install code

Upgrade code

Instrumenting your app with telemetry

Conclusion

See Also

Tutorial

Introduction

Prerequisites

Installing the Tools

Creating Your First Extension

Debugging Your Extension

Editing Your Extension

Visual Studio Code Extension Development

Conclusion

C++ Visual Studio Code Example