Upgrading Version 16 Microsoft System and Base Application to Version 17

Use this scenario if you have a Business Central 2020 release wave 1 solution that uses the Microsoft System and Base applications.

Upgrade on unmodified Business Central application.

Single-tenant and multitenant deployments

The process for upgrading is similar for a single-tenant and multitenant deployment. However, there are some inherent differences. With a single-tenant deployment, the application code and business data are in the same database. In a multitenant deployment, application code is in a separate database (the application database) than the business data (tenant). In the procedures that follow, for a single-tenant deployment, consider references to the application database and tenant database as the same database. Steps are marked as Single-tenant only or Multitenant only where applicable.

Prerequisites

Your version 16 is compatible with version 17.

There are several updates for version 16. The updates have a compatible version 17 update. For more information, see Dynamics 365 Business Central Upgrade Compatibility Matrix. For example, if your solution is currently running 16.6, you can't upgrade to 17.0. You must wait until 17.1 is available.
Disable data encryption.

If the current server instance uses data encryption, disable it. You can enable it again after upgrading.

For more information, see Managing Encryption and Encryption Keys.

Instead of disabling encryption, you can export the current encryption key, which you'll then import after upgrade. However, we recommend disabling encryption before upgrading.

Task 1: Prepare version 16 databases

Make backup of the databases.
Start Business Central Administration Shell for version 16 as an administrator.

For more information, see Run Business Central Administration Shell.
(Single-tenant only) Uninstall all extensions from the old tenants.

In this step, you uninstall the Base Application, System Application (if used), and any other extensions that are currently installed on the database.
1. Get a list of installed extensions.
  
  This step is optional, but it can be useful to the names and versions of the extensions.
  
  To get a list of installed extensions, use the Get-NAVAppInfo cmdlet.
```
Get-NAVAppInfo -ServerInstance <server instance name> -Tenant <tenant ID>
```
  For a single-tenant deployment, set the <tenant ID> to default.
2. Uninstall the extensions.
  
  To uninstall an extension, you use the Uninstall-NAVApp cmdlet.
```
Uninstall-NAVApp -ServerInstance <server instance name> -Name <extensions name> -Tenant <tenant ID> -Version <extension version> -Force
```
  Replace <extension name> and <extension version> with the exact name and version the published System Application.
  
  For example, together with the Get-NAVApp cmdlet, you can uninstall all extensions with a single command:
```
Get-NAVAppInfo -ServerInstance <server instance name> -Tenant <tenant ID>| % { Uninstall-NAVApp -ServerInstance <server instance name> -Tenant <tenant ID> -Name $_.Name -Version $_.Version -Force}
```

Unpublish all system symbols.

To unpublish symbols, use the Unpublish-NAVAPP cmdlet with the -SymbolsOnly switch.

Get-NAVAppInfo -ServerInstance <BC15 server instance> -SymbolsOnly | % { Unpublish-NAVApp -ServerInstance <BC15 server instance> -Name $_.Name -Version $_.Version }

What are symbols?

(Multitenant only) Dismount the tenants from the application server instance.

To dismount a tenant, use the Dismount-NAVTenant cmdlet:
```
Dismount-NAVTenant -ServerInstance <server instance name> -Tenant <tenant ID>
```

Stop the server instance.

Stop-NAVServerInstance -ServerInstance <server instance name>

Task 2: Install version 17

Download the latest available update for Business Central 2020 (version 17) that is compatible with your version 16.

For more information, see Dynamics 365 Business Central Upgrade Compatibility Matrix.
Before you install version 17, it can be useful to create desktop shortcuts to the version 16.0 tools, such as the Business Central Server Administration tool, Business Central Administration Shell, and Dynamics NAV Development Shell because the Start menu items for these tools will be replaced with the version 16 tools.
Install Business Central version 17 components.

You can keep version 16 installed to complete some steps in the upgrade process. When you install version 17, you must either specify different port numbers for components (like the Business Central Server instance and web services) or you must stop the version 16.0 Business Central Server instance before you run the installation. Otherwise, you'll get an error that the Business Central Server failed to install.

For more information, see Installing Business Central Using Setup.

Task 3: Convert version 16 database

This task runs a technical upgrade on the application database to convert it from the version 16 platform to the version 17 platform. The conversion updates the system tables of the database to the new schema (data structure). It provides the latest platform features and performance enhancements.

Start Business Central Administration Shell for version 17 as an administrator.

Run the Invoke-NAVApplicationDatabaseConversion cmdlet to start the conversion:

Invoke-NAVApplicationDatabaseConversion -DatabaseServer <database server name>\<database server instance> -DatabaseName "<database name>"

When completed, a message like the following displays in the console:

DatabaseServer      : .\BCDEMO
DatabaseName        : Demo Database BC (16-0)
DatabaseCredentials :
DatabaseLocation    :
Collation           :

Note

When the database is on Azure SQL Database, you may get the following error:

SQL Server: Execution Timeout Expired. The timeout period elapsed prior to completion of the operation or the server is not responding. The statement has been terminated.

If you do, scale up the database resources in Azure SQL, then run the Invoke-NAVApplicationDatabaseConversion cmdlet again. If the conversion is successful, you can then scale it back down to its original setting and continue the upgrade.

Task 4: Configure version 17 server

When you installed version 17 in Task 2, a version 17 Business Central Server instance was created. In this task, you change server configuration settings that are required to complete the upgrade. Some of the changes are only required for version 16 to version 17 upgrade and can be reverted after you complete the upgrade.

Set the server instance to connect to the application database.
```
Set-NAVServerConfiguration -ServerInstance <server instance name> -KeyName DatabaseName -KeyValue "<database name>"
```
In a single tenant deployment, this command will mount the tenant automatically. For more information, see Connecting a Server Instance to a Database.
Disable task Scheduler on the server instance for purposes of upgrade.
```
Set-NavServerConfiguration -ServerInstance <server instance name> -KeyName "EnableTaskScheduler" -KeyValue false
```
Be sure to re-enable task scheduler after upgrade if needed.

Restart the server instance.

Restart-NAVServerInstance -ServerInstance <server instance name>

Task 5: Import version 17 license

Use the Import-NAVServerLicense to upload the version 17 license to the database.

Import-NAVServerLicense -ServerInstance <server instance name> -LicenseFile <path and file name>

Restart the server instance.

Restart-NAVServerInstance -ServerInstance <server instance name>

Task 6: Publish symbols and extensions

In this task, you'll publish the platform symbols and extensions. As minimum, you publish the new base application and system application extensions from the installation media (DVD). You also publish new versions of any Microsoft extensions and third-party extensions that were used on your old deployment.

Publishing an extension adds the extension to the application database that is mounted on the server instance. Once published, it's available for installing on tenants. This task updates internal tables, compiles the components of the extension behind-the-scenes, and builds the necessary metadata objects that are used at runtime.

The steps in this task continue to use the Business Central Administration Shell for version 16 that you started in the previous task.

Publish version 17 system symbols extension.

The symbols extension contains the required platform symbols that the base application depends on. The symbols extension package is called System.app. You find it where the AL Development Environment is installed. The default path is C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\170\AL Development Environment.
```
Publish-NAVApp -ServerInstance  <server instance name> -Path "<path to system.app>" -PackageType SymbolsOnly
```
What are symbols?
Publish the System Application extension (Microsoft_System Application.app).

You find the (Microsoft_System Application.app in the Applications\System Application\Source folder of installation media (DVD).
```
Publish-NAVApp -ServerInstance <server instance name> -Path "<path to Microsoft_System Application.app>"
```
What is the System Application?
Publish the Business Central base application extension (Microsoft_Base Application.app).

The Base Application extension contains the application business objects. You find the (Microsoft_Base Application.app in the Applications\BaseApp\Source folder of installation media (DVD).
```
Publish-NAVApp -ServerInstance <server instance name> -Path "<path to Microsoft_Base Application.app>"
```
Publish the Microsoft_Application extension.

For more information about this extension, see The Microsoft_Application.app File.
```
Publish-NAVApp -ServerInstance <server instance name> -Path "<path to Microsoft_Application.app>"
```
Publish the new versions of Microsoft extensions.

In this step, you publish new versions of Microsoft extensions that were used on your version 16 deployment. You find the extensions in the Applications folder of the installation media (DVD).
```
Publish-NAVApp -ServerInstance <server instance name> -Path "<path to Microsoft extension>"
```
For example:
```
Publish-NAVApp -ServerInstance BC170 -Path "C:\W1DVD\Applications\SalesAndInventoryForecast\Source\SalesAndInventoryForecast.app"
```
Publish new versions of 3rd-party extensions.

If you have new versions of these extensions, built on the Business Central version 17, then publish the new versions.
```
Publish-NAVApp -ServerInstance BC170 -Path "<path to extension>"
```
Recompile extensions not build on version 17.

This step pertains to any published extension versions that aren't built on version 16, which you want to reinstall on tenants. These extensions must be recompiled to work with version 16. To recompile the extensions, use the Repair-NAVApp cmdlet:
```
Repair-NAVApp -ServerInstance <server instance> -Name <extension name> -Version <extension name>
```
For example, to recompile all extensions that are not published by Microsoft, you could run the following command:
```
Get-NAVAppInfo -ServerInstance <server instance> | Where-Object {$_.Publisher -notlike 'Microsoft'} | Repair-NAVApp
```
Restart the Business Central Server when completed.

Task 7: Synchronize tenant

You'll synchronize the tenant's database schema with any schema changes in the application database and extensions. If you have a multitenant deployment, do these steps for each tenant.

(Multitenant only) Mount the tenant to the version 17 server instance.

To mount the tenant, use the Mount-NAVTenant cmdlet:
```
Mount-NAVTenant -ServerInstance <server instance name> -DatabaseName <database name> -DatabaseServer <database server>\<database instance> -Tenant <tenant ID> -AllowAppDatabaseWrite
```
Important

You must use the same tenant ID for the tenant that was used in the old deployment; otherwise you'll get an error when mounting or syncing the tenant. If you want to use a different ID for the tenant, you can either use the -AlternateId parameter now or after upgrading, dismount the tenant, then mount it again using the new ID and the OverwriteTenantIdInDatabase parameter.

Note

For upgrade, we recommend that you use the -AllowAppDatabaseWrite parameter. After upgrade, you can dismount and mount the tenant again without the parameter if needed.

At this stage, the tenant state is OperationalWithSyncPending.
Synchronize the tenant with the application database.

Use the Sync-NAVTenant cmdlet:
```
Sync-NAVTenant -ServerInstance <server instance name> -Mode Sync -Tenant <tenant ID>
```
With a single-tenant deployment, you can omit the -Tenant parameter and value.
Synchronize the tenant with the System Application extension.

Use the Sync-NAVApp cmdlet:
```
Sync-NAVApp -ServerInstance <server instance name> -Tenant <tenant ID> -Name "System Application" -Version <extension version>
```
Replace <extension version> with the exact version of the published System Application. To get the version, you can use the Get-NAVAppInfo cmdlet.
Synchronize the tenant with the Business Central Base Application extension.
```
Sync-NAVApp -ServerInstance <server instance name> -Tenant <tenant ID> -Name "Base Application" -Version <extension version>
```
Replace <extension version> with the exact version of the published Base Application.

Synchronize the tenant with the Application extension.

Sync-NAVApp -ServerInstance <server instance name> -Tenant <tenant ID> -Name "Application"

Synchronize the tenant with Microsoft and 3rd-party extensions.

For each extension, run the Sync-NAVApp cmdlet:
```
Sync-NAVApp -ServerInstance BC150 -Tenant default -Name "<extension name>" -Version <extension version>
```

Task 8: Upgrade data

In this task, you run a data upgrade for extensions.

Single tenant

Run the data upgrade on extensions in order of dependency.

Run the data upgrade for the System Application, followed by the Base Application.

To run the data upgrade, use the Start-NAVAppDataUpgrade cmdlet cmdlet:
```
Start-NAVAppDataUpgrade -ServerInstance <server instance name> -Name "<extension name>" -Version <extension version>
```
This step will automatically install the new system application and base application versions on the tenant.
Upgrade the new versions of Microsoft extensions and third-party extensions.

Complete this task to upgrade any Microsoft and third-party extension used in the old deployment to new versions on the installation media. The new versions are in the Application folder of the DVD. There's a folder for each extension. The extension package (.app file) is in the Source folder.

For each extension, run Start-NAVAppDataUpgrade cmdlet. First, run the data upgrade for the Application extension, then run it for other Microsoft extensions and third-party extensions.

This step will also automatically install the new extension version on the tenant.

Multitenant

On each tenant, run the Start-NavDataUpgrade cmdlet as follows:

Start-NAVDataUpgrade -ServerInstance <server instance name> -Tenant <tenant ID> -FunctionExecutionMode Serial -SkipAppVersionCheck

This command will upgrade and install the extensions on the tenant.

Task 9: Install 3rd-party extensions

Complete this task to install third-party extensions for which a new version wasn't published. For each extension, run the Install-NAVApp cmdlet:

Install-NAVApp -ServerInstance <server instance name> -Name <extension name> -Version <extension version>

Task 10: Upgrade control add-ins

The Business Central Server installation includes new versions of the Microsoft-provided Javascript-based control add-ins, like Microsoft.Dynamics.Nav.Client.BusinessChart, Microsoft.Dynamics.Nav.Client.VideoPlayer, and more. If your solution uses any of these control add-ins, upgrade them to the latest version.

To upgrade the control add-ins from the client, do the following steps:

Open the Business Central client.
Search for and open the Control Add-ins page.
Choose Actions > Control Add-in Resource > Import.
Locate and select the .zip file for the control add-in and choose Open.

The .zip files are located in the Add-ins folder of the Business Central Server installation. There's a subfolder for each add-in. For example, the path to the Business Chart control add-in is C:\Program Files\Microsoft Dynamics 365 Business Central\160\Service\Add-ins\BusinessChart\Microsoft.Dynamics.Nav.Client.BusinessChart.zip.
After you've imported all the new control add-in versions, restart Business Central Server instance.

Alternatively, you can use the Set-NAVAddin cmdlet of the Business Central Administration Shell. For example, the following commands update the control add-ins installed by default. Modify the commands to suit:

$InstanceName = 'BC170'
$ServicesAddinsFolder = 'C:\Program Files\Microsoft Dynamics 365 Business Central\170\Service\Add-ins'
Set-NAVAddIn -ServerInstance $InstanceName -AddinName 'Microsoft.Dynamics.Nav.Client.BusinessChart' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $ServicesAddinsFolder 'BusinessChart\Microsoft.Dynamics.Nav.Client.BusinessChart.zip')
Set-NAVAddIn -ServerInstance $InstanceName -AddinName 'Microsoft.Dynamics.Nav.Client.FlowIntegration' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $ServicesAddinsFolder 'FlowIntegration\Microsoft.Dynamics.Nav.Client.FlowIntegration.zip')
Set-NAVAddIn -ServerInstance $InstanceName -AddinName 'Microsoft.Dynamics.Nav.Client.OAuthIntegration' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $ServicesAddinsFolder 'OAuthIntegration\Microsoft.Dynamics.Nav.Client.OAuthIntegration.zip')
Set-NAVAddIn -ServerInstance $InstanceName -AddinName 'Microsoft.Dynamics.Nav.Client.PageReady' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $ServicesAddinsFolder 'PageReady\Microsoft.Dynamics.Nav.Client.PageReady.zip')
Set-NAVAddIn -ServerInstance $InstanceName -AddinName 'Microsoft.Dynamics.Nav.Client.PowerBIManagement' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $ServicesAddinsFolder 'PowerBIManagement\Microsoft.Dynamics.Nav.Client.PowerBIManagement.zip')
Set-NAVAddIn -ServerInstance $InstanceName -AddinName 'Microsoft.Dynamics.Nav.Client.RoleCenterSelector' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $ServicesAddinsFolder 'RoleCenterSelector\Microsoft.Dynamics.Nav.Client.RoleCenterSelector.zip')
Set-NAVAddIn -ServerInstance $InstanceName -AddinName 'Microsoft.Dynamics.Nav.Client.SatisfactionSurvey' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $ServicesAddinsFolder 'SatisfactionSurvey\Microsoft.Dynamics.Nav.Client.SatisfactionSurvey.zip')
Set-NAVAddIn -ServerInstance $InstanceName -AddinName 'Microsoft.Dynamics.Nav.Client.SocialListening' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $ServicesAddinsFolder 'SocialListening\Microsoft.Dynamics.Nav.Client.SocialListening.zip')
Set-NAVAddIn -ServerInstance $InstanceName -AddinName 'Microsoft.Dynamics.Nav.Client.VideoPlayer' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $ServicesAddinsFolder 'VideoPlayer\Microsoft.Dynamics.Nav.Client.VideoPlayer.zip')
Set-NAVAddIn -ServerInstance $InstanceName -AddinName 'Microsoft.Dynamics.Nav.Client.WebPageViewer' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $ServicesAddinsFolder 'WebPageViewer\Microsoft.Dynamics.Nav.Client.WebPageViewer.zip')
Set-NAVAddIn -ServerInstance $InstanceName -AddinName 'Microsoft.Dynamics.Nav.Client.WelcomeWizard' -PublicKeyToken 31bf3856ad364e35 -ResourceFile ($AppName = Join-Path $ServicesAddinsFolder 'WelcomeWizard\Microsoft.Dynamics.Nav.Client.WelcomeWizard.zip')

Task 11: Change application version

This task serves two purposes. It ensures that personalization works as expected after upgrade. It's also useful for support purposes and answering a common question about the application version.

On the Help and Support page in the client, you'll see an application version, such as 16.0.2345.6. For an explanation of the number, see Version numbers in Business Central. This version isn't updated automatically when you install an update. If you want the version to reflect the version of the update or your own version, you change it manually.

We recommend setting the value to application build number for the version 17 update. You get the number from the Released Updates for Microsoft Dynamics 365 Business Central 2020 Release Wave 2 on-premises.

Run the Set-NAVApplication cmdlet:

Set-NAVApplication -ServerInstance <server instance name> -ApplicationVersion <new application version> -Force

For example:

Set-NAVApplication -ServerInstance BC170 -ApplicationVersion 17.0.38071.0 -Force

Run the Sync-NAVTenant cmdlet to synchronize the tenant with the application database.
```
Sync-NAVTenant -ServerInstance <server instance name> -Mode Sync -Tenant <tenant ID>
```
With a single-tenant deployment, you can omit the -Tenant parameter and value.

Run the Start-NavDataUpgrade cmdlet to change the version number:

Start-NAVDataUpgrade -ServerInstance <server instance name> -FunctionExecutionMode Serial -Tenant <tenant ID>

The data upgrade process will be running in the background after running the above Start-NAVDataUpgrade cmdlet. You check on the progress using the Get-NAVDataUpgrade cmdlet: such as: Get-NAVDataUpgrade -ServerInstance $NewBcServerInstance -Tenant $TenantId -Progress or Get-NAVDataUpgrade -ServerInstance $NewBcServerInstance -Tenant $TenantId -Detailed.

Don't stop the Business Central Server instance until the process is complete, that is, when you see State = Operational in the results from the Get-NAVDataUpgrade cmdlet. Also, you won't be able to do operations, like installing extensions, until the state is operational. It can take several minutes before the process completes.

Post-upgrade tasks

Enable task scheduler on the server instance.
(Multitenant only) For tenants other than the tenant that you use for administration purposes, if you mounted the tenants using the -AllowAppDatabaseWrite parameter, dismount the tenants, then mount them again without using the -AllowAppDatabaseWrite parameter.
If you want to use data encryption as before, enable it.

For more information, see Managing Encryption and Encryption Keys.

Optionally, if you exported the encryption key instead of disabling encryption earlier, import the encryption key file to enable encryption.

Upgrading to Business Central
Upgrading Extensions

Feedback

Was this page helpful?

Last updated on 2024-04-18