NAV 2017 CU1 on Azure

  • Article

Last night, the NAV 2017 CU1 image was uploaded to the Azure Gallery. A lot of things have changed, some things looks the same. The biggest change is of course that NAV on the image now is NAV 2017 CU1 instead of RTM, but also the a number of the pre-requisites for NAV have been updated or removed.

Building the image

A number of pre-requisites are installed before installing NAV on the image. All of these have changed in NAV 2017 CU1. Here's a list of what a NAV 2017 CU1 image consists of:

  • Windows Server 2012 R2 Datacenter (might try 2016 for CU2)
  • All updates from Windows Update
  • PowerShellGet (PackageManagement_x64.msi) for PowerShell Gallery (from here: https://www.powershellgallery.com/)
  • NuGet Package Provider 2.8.5.201 or higher (Install-PackageProvider -Name NuGet -MinimumVersion 2.8.5.201 -Force)
  • Search Service (Install-WindowsFeature Search-Service)
  • Download all DVD's to C:\NAVDVD\<countrycode>)
  • .net 4.5.2 (\Prerequisite Components\Microsoft .NET Framework 4.5.2\dotNetFx452_Full_x86_x64.exe on the DVD)
  • SQL Express 2016 (instance name NAVDEMO)
  • SharePoint Online Management Shell (https://www.microsoft.com/en-us/download/details.aspx?id=35588)
  • Install full NAV W1 on the server to standard folders and standard ports, using localhost\NAVDEMO as the database server using Windows Authentication.
    • Excluding the following installation options: ADCS, Outlook Addin, Excel Addin, Outlook Integration
  • Copy the content of the DEMO folder to C:\DEMO

Basically that's it. When people select a different localization of NAV to use in the C:\DEMO\Initialize script, the script will remove the W1 database, restore the new database (from the DVD in C:\NAVDVD) and run all the local installers from the DVD (C:\NAVDVD\<countrycode>\Installers\)

Now of course there are some tweeks because creating an image, because I have to do SYSPREP, which removes users and settings, so I have to make all administrators sysadmins on the SQL Server (as the normal administrator who installs SQL Express will be gone).

Earlier versions of the image used WebPI (Web Platform Installer) which caused new users created on the server after spinning up a VM to be unable to logon if they were not administrators. Earlier versions also had a lot of other pre-requisites - primarily because we didn't have the PowerShell Gallery.

At this time, you might be wondering why I am explaining how to build the image? - hold that thought for one second...

Unfortunately no CZ (Czech) localization on NAV 2017 CU1

Unfortunately the Czech localization is NOT on NAV 2017 CU1.

NAV 2017CU1 is based on W1 build 14199.

Due to a late bug in the Czech app, we had to take a new build for the Czech Localization. This build was created two days later on W1 build 14300. Unfortunately during these two days, the database version number was bumped.

This means that it is not possible to restore the CZ database and run the local installers to change the country code on the image. We build 14199 cannot use/mount a database from W1 14300. This is unfortunately a hard stop and I was forced to remove the CZ build from the image.

If you want to create a CZ demo environment with NAV 2017 CU1 - you will have to create the NAV VM on azure manually following the steps in the section about building the image.

Aka.ms/...

When deploying a new image to Azure, it is available almost immediately in the Classic Portal. It is also available to templated deployment (like https://aka.ms/navdemodeploy).

At this time, the following two Short URLs are working with NAV 2017CU1.

https://aka.ms/navdeploy - gives you a VM on Azure without running any scripts. You can run the demo scripts manually if you like.

https://aka.ms/navdemodeploy - gives you an initialized VM on Azure and runs a number of demo scripts to setup a demo environment.

Note The deployments done under these short Urls can potentially patch the files in the DEMO folder if there are any pending bug fixes to these files. This is the recommanded way of deploying NAV on Azure, you will always get the latest.

What else?

All DEMO scripts have been re-visited and updated. Earlier you had warnings and verbose messages flooding the screen and you couldn't really determine whether or not there were problems or everything was OK. As an example, the initialize output could look like this:
runinitialize

Every installation script in the DEMO folder used to have its own HelperFunctions.ps1. A lot of these had the same HelperFunctions. These have now been moved to a Common HelperFunctions.ps1 script. This supports things like logging to the DEMO status file and ensuring that a lot of the warnings and verbose messages that rolled over the screen whenever running a script, now is at a minimum and the necessary things are logged to ensure that it is easier to locate any problems on your VM.

Some scripts, that needed to download and install PowerShell modules (like AzureRM) are now using the PowerShell Gallery to do this:

 if (Get-Module -ListAvailable -Name AzureRM) {
    Log "AzureRM Powershell module already installed"
} else {
    Log "Install AzureRM PowerShell Module"
    Install-Module -Name "AzureRM"-Repository "PSGallery" -Force
}
Import-Module -Name "AzureRM"

Other scripts, like the AzureSQL installer requires the DAC Framework and uses NuGet package provider to download this:

 function Install-DACFx
{
    $packageName = "Microsoft.SqlServer.DacFx.x64"
    if (Get-Package -Name $packageName) {
        Log "$PackageName Powershell module already installed"
    } else {
        Log "Install $PackageName PowerShell Module"
        Register-PackageSource -Name NuGet -Location https://www.nuget.org/api/v2 -Provider NuGet -Trusted -Verbose | Out-Null
        Install-Package -Name $packageName -MinimumVersion 130.3485.1 -ProviderName NuGet -Force | Out-Null
    }
    (Get-Package -name $packageName).Version
}

Office 365 Single Sign On

A number of people reported, that the way the AAD (Azure Active Directory) App for Single Sign On was created, it was impossible for non-admin O365 users to access NAV.  The reason for this was, that in the NAV 2017RTM image, I changed from using the Set-NAVSingleSignOn Cmdlet, to do things in PowerShell. The PowerShell code did set the ClientServicesFederationMetadataLocation and the WSFederationLoginEndpoint to use a specific AAD Tenant (instead of Common) and as a result of this, the AAD App had to request permissions, that only an O365 Admin could give.

In CU1 - these keys are:

 <add key="ClientServicesFederationMetadataLocation" value="https://login.windows.net/Common/federationmetadata/2007-06/federationmetadata.xml" />
<add key="WSFederationLoginEndpoint" value="https://login.windows.net/Common/wsfed?wa=wsignin1.0%26wtrealm=<Web Client URL>" />

and the permissions required from the user accessing the app is just: Sign you in and read your profile:
permissions

The PowerShell Code for creating an AAD App, assigning permissions and adding a Logo can be found in c:\demo\O365 Integration\HelperFunctions.ps1 in the method called Setup-AadApps.

Extensions

The Azure Gallery Image contains three sample extensions (also in NAV 2016)

  • BingMaps Integration
  • O365 Integration
  • MSBand Integration

For NAV 2017 CU1, these extensions have gone through a major overhaul:

  • Objects, controls, variables and all have been renumbered to be in the 50000 range
  • Exposing Web Services is now part of the extension (earlier this was done in PowerShell)
  • The Control Add-ins are now part of the extension (earlier this was done in PowerShell)
  • Local translations are now part of the extension (ealier this was .txt files copied to the Service Translations folder in PowerShell)

Looking at the BingMaps Sources folder gives you the source of the BingMaps Extension:
bingmapssources

Definitions

  • All .DELTA files are source code DELTAs.
  • The .zip files are Control Add-ins.
  • The .xml files are Web Services definitions
  • The .txt files are translations

and here I need to express my apology to my icelandic friends that I do not have any icelandic translations. The primary reason for this is, that the Cognitive Translation Service on Azure doesn't support Icelandic and I found out of this too late. I am sure that some of my icelandic friends will help me translate the texts for the extensions to icelandic and I will include this in future CU's.

The BingMaps Extension has also been made more fail safe. This means that a simple geocoding error won't give a hard error, but will only cause that customer not to be geocoded.

Extension Development Shell (now with translation support)

The Extension Development Shell on the Azure Gallery Image is a lightweight set of scripts, that helps me develop the extensions on the Gallery Image.

After installing the Extension Development Shell you will see a list of available commands:
extensiondevelopmentshell

Nothing looks different since the NAV 2017RTM image here - but a lot have changed behind the scenes.

An AppFolder still refers to a folder under C:\DEMO, meaning that BingMaps is the App Folder name of the BingMaps extension. The CmdLets are still called the same, but a lot of the internals have changes.

The CmdLets now have fewer parameters and instead they assume, that in the App Folder, there is an AppSettings.ps1 available. If AppSettings is not available it will default values for you.

Lets try to setup a development environment for the BingMaps extension. Write the following commands:

 New-DevInstance -DevInstance dev -Language w1
Import-AppFolderDeltas -DevInstance dev -AppFolder BingMaps

(Yes, I know that language should have been countrycode)

The New-DevInstance will:

  • Create a new Service Tier for development (using W1)
  • Create a Web Client for this dev environment
  • Export all object files (we need them later)
  • Export all language files (we need them later)
  • Create shortcuts on the desktop for accessing the development environment, the Web Client and the Windows Client.
  • desktopshortcuts

The Import-AppFolderDeltas will:

  • Merge the .DELTA files in the AppFolder\Sources with the exported object files
  • Import and Compile the merged objects

If you open the DEV Development Environment now, you will see:
devenvbingmaps

(sorry for the Version List mismatch)

Now you can modify objects as you like and test things. In BingMaps Events you can see how to subscribe to the RegisterServiceConnection and have your Extension appear in the Service Connections list.

You will also find a sample on how to subscribe to the OnAfterActionEvent on the Extension Details Page in order to show a dialog when users install your extension and ask whether they want to setup the service connection right away.

When you have done your modifications you can open the extensions development shell again and use one of these CmdLets

 Update-AppFolderDeltas -DevInstance dev -AppFolder BingMaps
Update-AppFolderNavX -DevInstance dev -AppFolder BingMaps

The Update-AppFolderDeltas Cmdlet will:

  • Export object files from modified objects
  • Compare your modified objects to original objects and create .DELTA files
  • Export language files from modified objects
  • Compare your modified texts to original and create <OBJ>-strings.txt files for each object
  • Compare translations for all languages mentioned AppLanguages (in AppSettings.ps1) and
    • Remove removed strings or strings that have been translated in the object
    • Add new strings (and make a translation suggestion using the Azure Translation Service if you have provided a free key. See c:\demo\Common\HelperFunctions.ps1::TranslateText for implementation details)
  • Update files in the Sources folder.

Note:  If you modify the translation files, and fix translation errors, your translations will NOT be overridden by the Azure Translated strings:-)

The Update-AppFolderNavX Cmdlet will:

  • Do everything the Update-AppFolderDeltas does
  • Create a new .NavX file in the AppFolder.

So far so good.

If you want to test your extension, you can spin up a new test environment using

 New-DevInstance -DevInstance devdk -Language DK
Install-AppFolderNavX -DevInstance devdk -AppFolder BingMaps

Note:  The first time spinning up a dev instance in new language will take some time.

Where the Install-AppFolderNavX Cmdlet will:

  • Install the .NavX from the AppFolder to the corresponding development instance.

After this, you can test the extension on the Danish version of NAV 2017 CU1.

Important note: The Extensions Development Shell is not a full blown development environment, that should be used for all extension development. It is a light weight development environment, which can be used as inspiration for people when building up their Development Environments - there are a LOT of things that could be added to this.

2nd very Important note: The Extension Development Shell has nothing to do with the upcoming New Developer Experience in Visual Studio Code.

If you want to clean up, use:

 Remove-AllDevInstances

which will do exactly as the name suggests.

You can of course edit the O365 Extension by using "O365 Integration" instead of BingMaps.

Enough for now.

Enjoy

Freddy Kristiansen
Technical Evangelist