We recently announced the availability of the ALAppExtensions Repository on GitHub. The repository enables our partners and customers to collaborate with Microsoft, or other partners, to develop extensions in the AL language for Microsoft Dynamics 365 Business Central.

This article is to follow up that announcement with a step-by-step walkthrough that will help you “Git” going with the code in the ALAppExtensions repository. We will look at how to:

1. Set up a development environment
2. Clone a repository in GitHub
3. Use the ALAppExtensions repository as a baseline for an extension
4. Use GitHub to submit changes

Setting up an Environment

There are two things to do to get your environment ready:

• Set up a virtual machine and create an online sandbox
• Connect GitHub and Visual Studio Code

Set up a virtual machine and a sandbox

We’ll use a virtual machine running Windows 10 with Microsoft Edge installed, but we can also use other operating systems or browsers if we prefer.

We also need a sandbox environment. To create a sandbox, follow these instructions. In this walkthrough we’ll use an online sandbox, and not the container-based sandbox (also known as Docker). After we have followed the steps we have what we need in order to develop extensions for Business Central. To learn more about developing extensions, visit our documentation.

Note: We can create an online sandbox from our production tenant. To do that, in Business Central, search for Sandbox Environment, and then choose Sandbox Environment (Preview). You can also reopen or reset your existing sandbox.

Connect Git and Visual Studio Code

The next step is to integrate Git and Visual Studio Code. To do that, open Visual Studio Code and notice the notification. Choose Download Git.

Note: This message displayed earlier when we were setting up our sandbox. If we chose Don’t Show Again, we might have to get and install Git manually. To do that, go to https://git-scm.com/downloads and choose a version.

The next time we open Visual Studio Code we can verify that it installed by looking at the Git version. To get the version, run git --version in the integrated terminal (you can open the integrated terminal with Ctrl+` or from the View menu).

Cloning a Repository

In the integrated terminal, we’ll run some commands and clone the project with extensions from Git to our machine.

Note: We don’t need to have a Git account to create a local clone of the repository. You need an account only if you want to contribute to our ALAppExtensions repository. We’ll look at that later in this article.

Let’s switch to the default location of our folder for extensions, which is C:UsersvmadminDocumentsAL, by running cd C:usersvmadminDocumentsAL.

Now we’ll run the following command to clone the ALAppExtension repositiory to the AL folder git clone https://github.com/Microsoft/ALAppExtensions.git.

Opening the Extension in Our Sandbox

We now have the ALAppExtension folder, which contains a subfolder for each available extension. To work on, build, and publish an extension we need to open its folder. When we decide to download updates from GitHub we will work with a complete project that includes all extensions.

Let’s open the EssentialBusinessHeadlines extension. To do that, in Visual Studio Code we’ll choose File, Open Folder, and then choose C:UsersvmadminDocumentsALALAppExtensionsEssentialBusinessHeadlines.

Visual Studio Code will discover that we are missing symbols and suggest that we add them by connecting to a server. Choose a Microsoft Cloud Sandbox configuration. This creates a launch.json file in the .vscode folder. We might have to enter our credentials for our sandbox.

After we download symbols we can package our extension in an app file. We’ll do that in the Command Pallet. We can open the Command Pallet by pressing Ctrl+Shift+P, or from the View menu by choosing Command Pallet, and then choosing or typing AL:Package (Ctrl+Shift+B).

Note: Do not try to publish (AL:Publish) the package at this stage.

So far so good! We have now:

• Connected our extension to an online sandbox
• Downloaded the symbols we need
• Packaged our extension in an app file in the C:UsersvmadminDocumentsALALAppExtensionsEssentialBusinessHeadlines folder.

Working with a Repository

This section covers the following steps:

• Set up .gitignore files
• Create a Branch of the AlApp repository
• Stage and commit changes to our branch.

We’ve installed the development tools we’ll need, including Visual Studio Code, the AL Language Extension, Git, and created a cloud sandbox. We also cloned a project locally and packaged an app.

Now the Source Control icon on the Activity Bar displays the number 5, which means we have five changes ready to commit. These changes are the result of downloading symbols. To see our changes, we’ll choose the Source Control icon (or press Ctrl+Shift+G).

Git suggests that we commit a launch.json, a packaged extension, and a number packages that represent downloaded symbols.

However, we don’t need to track changes in these files because:

• json is environment specific and should not be distributed with an extension
• We can download symbols anytime
• We can also package extension whenever. We don’t store build outputs in source controls systems

To notify Git that we don’t want to track these files we’ll right-click the launch.json file and choose Add File to .gitignore.

Scroll to the bottom, where a new line was added:

EssentialBusinessHeadlines/.vscode/launch.json

Git will now ignore the launch.json file that is stored in C:UsersDocumentsALALAppExtensionsEssentialBusinessHeadlines.vscode.

Tip: Our repository contains more than one extension though. Rather than exclude each one individually, we can use wildcards, like “*.” To cover all launch.json files for all extensions we can specify:

**/launch.json

We can do the same for all app files.

Committing a Local Change

In the previous section we decided to ignore several app files because there is no reason to track them. Others can benefit from our change, so let’s contribute it.

Step 1 is to save our changes in our local repository. We’re working in our local master branch, but we really should be using a feature branch so that we can keep our local master branch in sync with the ALAppExtension/master remote branch on GitHub.

Let’s create a feature branch named GitIgnore by running Git checkout -b GitIgnore in the integrated terminal.

This transfers all files from our working folder, including those that we’ve changed, to the new branch. We can verify this by running git status.

Git detects that we changed the .gitignore file and suggests that we run git add to add it to the files we’re about to commit. We can also use the + icon next to the file name in the Source Control area.

Now we’ll commit our changes to the GitIgnore branch by running git commit -m 'adding *.app and **/launch.json files to .gitignore'.

Note: Git might want to know who we are and ask us to enter our name or email in the config files. The message will provide instructions to resolve the problem. Follow them and then commit again.

And that’s it! At this point we’ve:

• Added files that we don’t want to track to the .gitignore file
• Created a feature branch and committed changes into our local repository
• Added missing settings into git config.

Here’s a recap of the commands we used:

Command	Description
Git checkout -b	Create a branch
Git Add	Add staged changes
Git commit -m ‘’	Commit changes

Submitting Changes to a GitHub Project

Now we’re ready to push our changes to https://github.com/Microsoft/ALAppExtensions.

Note: To complete this section we must have a GitHub account. Getting an account is quick and easy to do, just remember to verify the email account when you’re done. Instructions for getting an account are available here.

Microsoft/ALAppExtensions is a protected repository, and we need to use what’s called a “pull request” to submit our changes. A pull request notifies the administrator who maintains repository that we want them to pull our changes into the repository. The admin can review changes that are made in cloned repository and merge them if they look good.

That means we need to create our own repository on GitHub where we will push our changes so that the admin for the Microsoft/ALAppExtensions repository can see them.

Go to https://github.com/Microsoft/ALAppExtensions and choose the Fork button in the upper right corner.

After a couple of seconds we’ll get a repo cloned under our account. Notice that name of repo includes our login, and it has a comment that it was forked. The commit history and branches are also cloned, which is why it looks like the original repo.

Our repository is completely in sync with the Microsoft repository. We’re going to change that though by pushing our changes to the new branch of our repo by running the push command in the integrated terminal in Visual Studio Code. But to keep the command short let’s run Git remote add upstream https://github.com/gitbcdemo/ALAppExtensions to add the remote repo.

To check the status of our push we’ll run Git remote -v to get a list of nicknames for remote repositories. We should see the “origin” and “upstream” nicknames.

Note: When we ran the clone command GitHub added the remote repository https://github.com/Microsoft/ALAppExtensions  named origin. We can use this nickname in commands. For example, GitHub will recognize the git pull origin

Now we can run git push upstream GitIgnore to push changes.

The changes where submitted from our fork of the Microsoft/ALAppExtensions to the specified branch (that we called GitIgnore). We can see that the new branch is added, and switch to it.

GitHub shows a notification about the updated (created) GitIgnore branch. We’ll choose the Compare & pull request button to initiate the pull request process. We can run it from the notification, or switch to our branch and open a pull request from there.

Now we’re ready to submit our pull request to the Microsoft/ALAppExtensions repository. Because someone will approve our pull request it’s always a good idea to provide some information about our change. For example, we should explain the benefit it achieves and why it should become part of the standard product. Typically, comments about implementation nuances are also welcome. The better we describe our submission, the faster our request will be approved.

When we choose Create pull request, a pull request is created on the Microsoft/ALAppExtensions repository. Now it’s just a matter of time before our changes are approved (depending on quality of our changes, of course).

Cleaning up

After our pull request is approved and merged we can delete our branch (gitbcdemo:GitIgnore in this demo). We can also clean up our local repo by deleting our GitIgnore feature branch. To do that we’ll switch to our master branch and run the safe command Git checkout master so that we no longer have the GitIgnore feature branch checked out.

Notice that our local master branch is behind of the remote master branch. To resolve this, we’ll run Git fetch origin and then Git rebase origin/master to refresh our local master. Now we’ll run Git branch -d GitIgnore to delete our GitIgnore feature branch.

And we’re done. We’ve just submitted changes to our fork on GitHub, created a pull request, synced our local master branch with the remote, and did some housekeeping by deleting our local feature branch.

Here’s a list of the commands we used.

Command	Description
Submitted changes to our fork on GitHub	git push upstream
Switch to master branch	Git checkout master
Sync local master branch with remote repository	Git fetch origin and then Git rebase origin/master
Delete local feature branch	Git branch -d