AdvaniaGIT: About the build steps

The goal of this post is to demo from start to finish the automated build and test of an AL solution for Microsoft Dynamics 365 Business Central.

About the build steps

All build steps are execute in the same way.  In the folder ‘C:\AdvaniaGIT\Scripts’ the script ‘Start-CustomAction.ps1’ is executed with parameters.

The AdvaniaGIT custom action is executed in the same way from a build machine and from a development machine.

When we created the container in our last post from Visual Studio Code with the command (Ctrl+Shift+P) ‘Build NAV Environment’, Visual Studio Code executed

From the build task we execute ‘C:\AdvaniaGIT\Scripts\Start-CustomAction.ps1’ with these parameters

We can see that these commands are almost the same.  We have the one additional parameter in the build script to notify the scripts that we are in Build Mode.

Each AdvaniaGIT build or development machine has a ‘C:\AdvaniaGIT\Data\GITSettings.Json’ configuration file.

When the scripts are started this file is read and all the settings imported.  Then the repository setup file is imported.  The default repository setup file is ‘setup.json’ as stated in GIT settings.  If the same parameters are in both the machine settings and in the repository settings then the repository settings are used.

The same structure is used for the ‘BuildSettings’ parameter that can be passed to the custom action.  The build settings will overwrite the same parameter in both the machine settings and the repository settings.

The default settings are built around the folder structure that I like to use.  For example, we have our C/AL objects in the ‘Objects’ folder.  Microsoft has their objects in then ‘BaseApp’ folder.  Just by adding the ‘objectsPath’ parameter to the repository settings for the Microsoft repository I can use their structure without problems.

If I wan’t to execute the same exact functionality in Visual Studio Code as I expect to get from my build script I can add the ‘BuildSettings’ parameter to the command.

The folder structure

The structure is defined in settings files.  By default I have the ‘AL’ folder for the main project and the ‘ALTests’ folder for the test project.  Example can be seen in the G/L Source Names repository.

In C/AL we are using deltas and using the build server to merge our solutions to a single solution.  Therefore we have a single repository for a single NAV version and put our solutions and customization into branches.

In AL this is no longer needed.  We can have a dedicated repository for each solution if we like to, since the scripts will not be doing any merge between branches.

AdvaniaGIT: Setup and configure the build machine

The goal of this post is to demo from start to finish the automated build and test of an AL solution for Microsoft Dynamics 365 Business Central.

Setup and configure the build machine

We will create our build machine from a standard Windows 2016 template in Azure.

Docker containers and container images will take a lot of disk space.  The data are stored in %ProgramData%\docker

It if obvious that we will not be able to store the lot on the system SSD system drive.  To solve this I create an 1TB HDD disk in Azure.

After starting the Azure VM and opening the Server Manager to look at the File and Storage Service we can see the new empty disk that need configuration.

Right click the new drive to create a new volume.

And assign the drive letter

Next go to Add roles and features to add the Containers feature.  More information can be found here.  We also need to add ‘.NET Framework 3.5 Features’.

I also like to make sure that all Microsoft updates have been installed.

Now I start PowerShell ISE as Administrator.

As Windows Servers are usually configured in a way that prohibits downloads I like to continue the installation task in PowerShell.

To enable all the scripts to be executes we need to change the execution policy for PowerShell scripts.  Executing

will take care of that. 

Confirm with Yes to all.

To make sure that all the following download functions will execute successfully we need to change the TLS configuration with another PowerShell command.

Let’s download Visual Studio Code!  Use the following PowerShell command

to download the installation file to your desktop.  Start the installation.  During installation I like to select all available additional tasks.

We also need to download GIT.  Using the following PowerShell command

will download the latest version at the time of this blog post.  The only thing I change from default during GIT setup is the default editor.  I like to use Visual Studio Code.

Go ahead and start Visual Studio Code as Administrator.

Add the AdvaniaGIT extension to Visual Studio Code

Install AdvaniaGIT PowerShell Scripts!  We access the commands in Visual Studio Code by pressing Ctrl+Shift+P.  From there we type to search for the command ‘Advania: Go!’ and the when selected we press enter.

You will get a small notification dialog asking you to switch to the AdvaniaGIT terminal window.

Accept the default path for the installation but select No to the two optional installation options.

We need a development license to work with NAV and Business Central.  This license you copy into the ‘C:\AdvaniaGIT\License’ folder.  In the ‘GITSettings.json’ file that Visual Studio Code opened during AdvaniaGIT installation we need to point to this license file.

The DockerSettings.json file is also opened during installation and if you have access to the insider builds we need to update that file.

If not make sure to have all setting blank

Save both these configuration files and restart Visual Studio Code.  This restart is required to make sure Visual Studio Code recognizes the AdvaniaGIT PowerShell modules.

Let’s open our first GIT repository.  We start by opening the NAV 2018 repository.  Repositories must have the setup.json file in the root folder to support the AdvaniaGIT functionality.

I need some installation files from the NAV 2018 DVD and I will start by cloning my GitHub NAV 2018 respository.  From GitHub I copy the Url to the repository.  In Visual Studio Code I open the commands with Ctrl+Shift+P and execute the command ‘Git: Clone’.

I selected the default folder for the local copy and accepted to open the repository folder.  Again with Ctrl+Shift+P I start the NAV Installation.

The download will start.  The country version we are downloading does not matter at this point.  Every country has the same installation files that we require.

This will download NAV and start the installation.  I will just cancel the installation and manually install just what I need.

  • Microsoft SQL Server\sqlncli64
  • Microsoft SQL Server Management Objects\SQLSysClrTypes
  • Microsoft Visual C++ 2013\vcredist_x64
  • Microsoft Visual C++ 2013\vcredist_x86
  • Microsoft Visual C++ 2017\vcredist_x64
  • Microsoft Visual Studio 2010 Tools For Office Redist\vstor_redist

To enable the windows authentication for the build containers we need to save the windows credentials.  I am running as user “navlightadmin”.  I securely save the password for this user by starting a command (Ctrl+Shift+P) and select to save container credentials.

For all the docker container support I like to use the NAV Container Helper from Microsoft.  With another command (Ctrl+Shift+P) I install the container helper to the server.

To complete the docker installation I execute.

in Visual Studio Code Terminal.

We need to point docker to our data storage drive.  Kamil Sacek already pointed this out to us.

I use Visual Studio Code to update the docker configuration.  As pointed out here the default docker configuration file can be found at ‘C:\ProgramData\Docker\config\daemon.json’. If this file does not already exist, it can be created.  I update the ‘data-root’ configuration.

Now let’s restart the server by typing

or manually.

After restart, open Visual Studio Code as Administrator.

Now to verify the installation let’s clone my Business Central repository.  Start command (Ctrl+Shift+P) ‘Git: Clone’ and paste in the Url to the repository.

This repository has a setup.json that points to the Business Central Sandbox.

Make sure to have the Integrated Terminal visible and let’s verify the installation by executing a command (Ctrl+Shift+P) ‘Advania: Build NAV Environment’ to build the development environment.

The image download should start…

You should now be able to use the command (Ctrl+Shift+P) ‘Advania: Start Client’,  ‘Advania: Start Web Client’, ‘Advania: Start FinSql’ and ‘Advania: Start Debugger’ to verify all the required NAV/BC functionality.

If you are happy with the results you should be able to install the build agent as shown by Soren Klemmensen here.

 

Using the Translation Service for G/L Source Names

Until now I have had my G/L Source Names extension in English only.

Now the upcoming release of Microsoft Dynamics 365 Business Central I need to supply more languages.  What does a man do when he does not speak the language?

I gave a shout out yesterday on Twitter asking for help with translation.  Tobias Fenster reminded me that we have a service to help us with that.  I had already tried to work with this service and now it was time to test the service on my G/L Source Names extension.

In my previous posts I had created the Xliff translation files from my old ML properties.  I manually translated to my native language; is-IS.

I already got a Danish translation file sent from a colleague.

Before we start; I needed to do a minor update to the AdvaniaGIT tools.  Make sure you run “Advania: Go!” to update the PowerShell Script Package.  Then restart Visual Studio Code.

Off to the Microsoft Lifecycle Services to utilize the translation service.

Now, let’s prepare the Xliff files in Visual Studio Code.  From the last build I have the default GL Source Names.g.xlf file.  I executed the action to create Xliff files.

This action will prompt for a selection of language.  The selection is from the languages included in the NAV DVD.

After selection the system will prompt for a translation file that is exported from FinSql.  This I already showed in a YouTube Video.  If you don’t have a file from FinSql you can just cancel this part.  If you already have an Xliff file for that language then it will be imported into memory as translation data and then removed.

This method is therefore useful if you want to reuse the Xliff file data after an extension update.  All new files will be based on the g.xlf file.

I basically did this action for all 25 languages.  I already had the is-IS and da-DK files, so they where updated.  Since the source language is en-US all my en-XX files where automatically translated.  All the other languages have translation state set to “needs-translation”.

All these files I need to upload to the Translation Service.  From the Lifecycle Services menu select the Translation Service.  This will open the Translation Service Dashboard.

Press + to add a translation request.

I now need to zip and upload the nl-NL file from my Translations folder.

After upload I Submit the translation request

The request will appear on the dashboard with the status; Processing.  Now I need to wait for the status to change to Completed.  Or, create requests for all the other languages and upload files to summit.

When translation has completed I can download the result.

And I have a translation in state “needs-review-translation”.

Now I just need to complete all languages and push changes to GitHub.

Please, if you can, download your language file and look at the results.

Using AdvaniaGIT – Convert G/L Source Names to AL

Here we go.

The NAV on Docker environment we just created can be used for the task at hand.  I have an Extension in Dynamics 365 called G/L Source Names.

I need to update this Extension to V2.0 using AL.  In this video I go through the upgrade and conversion process using AdvainaGIT and Visual Studio Code.

In the first part I copy the deltas from my Dynamics 365 Extension into my work space and I download and prepare the latest release of NAV 2018 Docker Container.

Using our source and modified environments we can build new syntax objects and new syntax deltas. These new syntax deltas are then converted to AL code.

 

Using AdvaniaGIT in Visual Studio Code

It has become obvious that the future of AL programming is in Visual Studio Code.

Microsoft has made a decision to ship all their releases as Docker Containers.

The result of this is a development machine that does not have any NAV version installed.  I wanted to go through the installation and configuration of a new NAV on Docker development machine.

Here is what I did.

I installed Windows Server 2016 with Containers.  The other option was to use Windows 10 and install Docker as explained here.

After installing and fully updating the operating system I downloaded and installed Visual Studo Code.

After installation Visual Studio Code detects that I need to install Git.

I selected Download Git and was taken to the Git download page.

I downloaded and installed Git with default settings.

To be able to run NAV Development and NAV Client I need to install prerequisite components.  I copied the Prerequisite Components folder from my NAV 2018 DVD and installed some of them…

Let’s hook Visual Studio Code to our NAV 2018 repository and install AdvaniaGIT.  I first make sure to always run Visual Studio Code with administrative privileges.

Now that we have our AdvaniaGIT installed and configured we can start our development.  Let’s start our C/AL classic development.  Where this video ends you can continue development as described in my previous posts on AdvaniaGIT.  AdvaniaGIT also supports NAV 2016 and NAV 2017.

Since we are running NAV 2018 we can and should be using AL language and the Extension 2.0 model.  Let’s see how to use our repository structure, our already build Docker container and Visual Studio Code to start our first AL project.

So as you can see by watching these short videos it is easy to start developing both in C/AL and AL using AdvaniaGIT and Visual Studio Code.

My next task is to update my G/L Source Names extension to V2.  I will be using these tools for the job.  More to come soon…

Using AdvaniaGIT – FTP server for teams

So, you are not the only one in your company doing development, right?

Essential part of being able to develop C/AL is to have a starting point.  That starting point is usually where you left of last time you did some development.  If you are starting a task your starting point may just be the localized release from Microsoft.

A starting point in AdvaniaGIT is a database backup.  The database backup can contain data and it should.  Data to make sure that you as a developer can do some basic testing of the solution you are creating.

AdvaniaGIT has a dedicated folder (C:\AdvaniaGIT\Backup) for the database backups.  That is where you should put your backups.

If you are working in teams, and even if not you might not want to flood your local drive with database backups.  That is why we configure an FTP server in C:\AdvaniaGIT\Data\GITSetting.json.

When we start an action to build NAV development environment the AdvaniaGIT tools searches for a database backup.

The search is both on C:\AdvaniaGIT\Backup and also on the root of the FTP server.

Using the function Get-NAVBackupFilePath to locate the desired backup file it will search based on these patterns.

The navRelease is the year (2016,2017,…).  The navVersion is the build (9.0.46045.0,9.0.46290.0,10.0.17972.0,…)

The projectName and navSolution parameters are defined in Setup.json (settings file) in every GIT branch.

Combining these values we can see that the search will be done with these patterns.

And these file patterns are applied both to C:\AdvaniaGIT\Backup and to the FTP server root folder.  Here are screenshots from our FTP server.

Looking into the 2017 folder

And into one of the build folders

My local backup folder is simpler

This should give you some idea on where to store your SQL backup files.

 

 

Using AdvaniaGIT – Docker Containers

There is a new kid in town.  His name is Docker.

Microsoft is saying:

We are currently investigating how we can use Docker for deploying NAV. For test purposes we have created a Docker Container Image with the NAV Developer Preview, which you can try out.

Docker Containers is a technology where you, instead of virtualizing the entire machine, only virtualize the services and share resources from the host computer. Read more about it here: https://www.docker.com/what-docker

Read more about how to get started with Docker here: https://docs.docker.com/docker-for-windows/install/

So what does this mean?

We can install NAV environments as container both in Azure and on premise.  We can have multiple NAV versions to work with without having to install, so there is no conflict.  We can also get access to container images that are still in preview.

Note what Microsoft says, they are investigating.  The NAV Container Image service is not public yet.  You need authentication to get access.  This project has a place on GitHub.  To get access please contact Microsoft or send me a line and I will point you in the right direction.

The easiest way to get started is to try the NAV Developer Preview template on Azure,  http://aka.ms/navdeveloperpreview.  This will give you a full development environment for NAV Extension2.0 using VS Code.

It should be straight forward to install AdvaniaGIT on top of the NAV Developer Preview and start from there.  We can also start from Azure template called “Windows Server 2016 Datacenter – with Containers”.

The local option is to install Docker on our Windows laptop.  If you would like to use Docker on your laptop you need to change one setting after installation.  You need to switch to Windows containers.  Your laptop will most likely restart during installation and configuration of Docker so make sure to have your work saved.

If you are planning to run a Docker-Only environment you don’t need to install NAV.  Still there are prerequisite components that you must install.  These components can be found on the NAV DVD folder “Prerequisite Components”.  From the “Microsoft SQL Server” folder install sqlncli64.msi and ReportBuilder3.msi.  From the “Microsoft Visual C++ 2013” folder install vcredist_x64.exe.  From the “Microsoft Visual Studio 2010 Tools for Office Redist” install vstor_redist.exe.  From the “Microsoft Report Viewer” folder install both SQLSysClrTypes.msi and ReportViewer.msi.  You should now be ready for the next step.

So, let’s get started

In your C:\AdvaniaGIT\Data folder open DockerSettings.json

That’s all.  Your are now ready to use Docker with AdvaniaGIT.  Make sure to always have the latest version of AdvaniaGIT installed.

You can even use the “devpreview” build of NAV TENERIFE to do vNext development both in C/AL and AL.

Stay tuned, the AdvaniaGIT journey will continue…

Using AdvaniaGIT – How to configure licenses

When NAV environments are built a development license is uploaded to the development database.

Make sure to save your development licenses in your AdvaniaGIT license folder.

There are two ways to configure which license is used.  First with the “licenseFile” property of GITSettings.json in your AdvaniaGIT data folder.

Just specify the file name in the license folder.

The license configured in GITSettings.json will be used as default for all builds.  However, as mentioned earlier, every settings in GITSettings.json can be overwritten by the settings in each branch.

The settings file in each branch is named according to the “setupPath” parameter in GITSettings.json.  If we take a look at the setup.json file for my G/L Source Names solution.

Here I need to use another license file.  The one used when I applied for the object range for my extension.

Licenses are not to be stored in SQL backups used by AdvaniaGIT.  When using AdvaniaGIT to create SQL backups the license is removed before creating the backup and reinstalled afterwards.

The first function that is executed after SQL database restore is a database upgrade with the development environment.  This must be done to make sure that the database fits the service version being used.  For this database upgrade function to be successful, first either make sure that the database does not contain expired license, and make sure that you have a valid license in the master database.

There are a few ways of doing this.  First, there is an option when installing NAV to upload the license.

Secondly, in the development environment you can upload a license, going through Tools and License Information.

But make sure that the database your development environment is connected to does not have the “Save license in database” set like here, going through File, Database and Alter.

The third option is to use the server administrative shell.

Hope this helps.  More to come soon.  Stay tuned…

Using AdvaniaGIT – Bring your solution into SCM

Most of us are not just starting working with NAV.  But again not all of us have been able to apply Source Control Management (SCM) to our daily work.

In the previous posts we have installed and prepared our development environment and we are now ready to start working on our solution in the SCM way.

Our first step is to create a branch for our solution.

Now we should look at the options we have to import our solution into our branch.  We can have our solution in different formats.

All these file formats can be imported into our solution branch with the tools that AdvaniaGIT delivers.  Let’s start with the SQL backup, 2016-DAA_WineApp.bak.  AdvaniaGIT will search for backups using these patterns.

In this example the values are:

The module first searches the local drive (default = C:\AdvaniaGIT\Backup) and then the ftp server if one is defined in GITSettings.json.

When AdvaniaGIT creates a database backup it is named according to the first pattern, in this case 2016-WineSolution.bak and saved in the default backup location.

The rest of the file types require that the solution branch has already been built like shown in the first video.

Here we restore from bacpac.  Bacpac format is for example used by AzureSQL.

The Navdata format was created by the NAV development team.  To be able to import from a Navdata file we require an Navdata export with the application included.

Perhaps the most common way is to have a FOB export.

Text exported objects can be imported directly into out GIT branch.

And finally we can update the solution branch from delta files.

Out next task will be to do some development in our solution and commit the changes we make to our GIT server.  Stay tuned…