编辑

通过

Upgrading Customized C/AL Application to Microsoft Base Application Version 17

  • 项目

This article describes how to upgrade a customized version 14 application to a version 17 solution that uses the Microsoft Base Application.

Shows the upgrade of an unmodified Business Central application.

Overview

The upgrade is divided into two sections: Application Upgrade and Data Upgrade. The Application Upgrade section deals with upgrading the application code. For the application upgrade, you'll have to create several extensions. Some of these extensions are only used for upgrade purposes. The Data Upgrade section deals with upgrading the data on tenants - publishing, syncing, and installing extensions. For this scenario, the data upgrade consists of two phases for migrating data from the current tables to extension-based tables. The following figure illustrates the upgrade process.

Shows the upgrade on unmodified Business Central application.

The process uses two special features for migrating tables and data to extensions:

  • destinationappsformigration server setting

    The destinationappsformigration setting is a configuration setting on the Business Central Server. In short, it's used to transfer ownership of the existing tables to the table migration extension. For more information, see DestinationAppsForMigration.

  • migration.json file

    The migration.json file is used to migrate tables and fields from one extension to another. In this case, migration is from the table migration extension to system and base application tables. For more information about the migration.json, see The Migration.json File.

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.

Personalization and customizations

Since version 14, the way user profiles are defined, stored, and customized has undergone a major overhaul. This change means user personalization and profile customizations that were done in the Windows Client are lost after upgrade. The legacy profiles remain available but their associated profile configurations are discarded. Page customizations must be either recreated using the latest Business Central client or as an AL extension. For more information about personalization, customization, and Al profiles, see:

Prerequisites

  1. Your version 14 is compatible with version 17.

    There are several updates for version 14. The updates have a compatible version 17 update. For more information, see Dynamics 365 Business Central Upgrade Compatibility Matrix.

  2. The version 14 Dynamics NAV Development Shell and Business Central Administration Shell are installed.

  3. Get the required version of the txt2al conversion tool.

    During the upgrade, you'll use the txt2al conversion tool to convert existing tables to the AL syntax. You'll need to use a version of txt2al conversion tool that supports the --tableDataOnly parameter. This parameter was first introduced in version 14.12 (cumulative update 11, platform 14.0.41862). So if you're upgrading from version 14.11 (cumulative update 10) or earlier, you'll have to download the txt2al conversion tool from a later version 14 update. See Released Cumulative Updates for Microsoft Dynamics 365 Business Central Spring 2019 Update on-premises.

Install version 17

  1. Download the latest available update for Dynamics 365 Business Central (version 17) that is compatible with your version 14.

    For more information, see Dynamics 365 Business Central Upgrade Compatibility Matrix.

  2. Before you install version 17, it can be useful to create desktop shortcuts to the version 14.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 17 tools.

  3. Install Business Central version 17 components.

    You'll have to keep version 14 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 stop the version 14.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.

APPLICATION UPGRADE

This section describes how to upgrade the application code. This work involves creating various extensions.

Task 1: Move code customizations to extensions

The first step, and the largest step, is to create extensions for the customizations compared to the Microsoft base application.

  • Create extensions for the target platform 6.0 Business Central 2020 release wave 2.
  • Include dependencies for the Microsoft System, Base, and Application extensions for version 17.0.0.0.

For example, if your application includes custom tables, then create extensions that include table objects and logic for the custom tables. If the application includes custom fields on system or base application tables, create extensions that include table extension objects to cover the custom fields. As part of this upgrade process, the data currently stored in custom tables or fields will be migrated from the existing tables to the new ones defined in the extensions.

Task 2: Create empty extensions System, Base, and customization extensions

For the interim phase of migrating tables and data to extensions, you create empty extension versions for:

  • Microsoft system application
  • Microsoft base application
  • Each new customization extension that includes table or table extension objects for moving out of the existing base application. You don't have to create empty versions for extensions that don't include table changes. For example, the extension only includes a page object and code.

The only file in the extension project that is required is an app.json. You can create the empty extension like any other extension by adding an AL project in Visual Studio Code:

  1. In Visual Studio Code, select View > Command Palette > AL: Go! and follow instructions.

  2. Delete the HelloWorld.al sample file from the project.

  3. Modify the app.json file.

    The important settings in the app.json file are: "id", "name", "version", "publisher", "dependencies", and "runtime".

    • The id and name must match the value used by Microsoft's extensions.
    • Set the version to any version lower than 17.0.0.0, like 14.0.0.0.
    • You'll also have to include the "publisher". You can use your own publisher name or "Microsoft".
    • Remove all other settings. It's important that there are no "dependencies" set.
    • Set the runtime to "6.0".

    The app.json files for the System Application and Base Application extensions, should look similar to following examples:

    System Application

      "id": "63ca2fa4-4f03-4f2b-a480-172fef340d3f",
  "name": "System Application",
  "publisher": "Microsoft",
  "version": "14.0.0.0",
  "runtime": "6.0"

    Base Application

      "id": "437dbf0e-84ff-417a-965d-ed2bb9650972",
  "name": "Base Application",
  "publisher": "Microsoft",
  "version": "14.0.0.0",
  "runtime": "6.0"

    Customization extensions

      "id": "437dbf0e-84ff-417a-965d-ed2bb9650972",
  "name": "<extension name>",
  "publisher": "<extension publisher",
  "version": "<extension version - must be lower than the final version>",
  "runtime": "8.0",
  "target": "OnPrem"

    Note

    For customization extensions, the version number must be lower than the final version for publication. Otherwise, you can't run upgrade on the extension later.

  4. Build and compile the extension package. To build the extension package, select Ctrl+Shift+B.

Tip

This step is only required if you need to trigger a data upgrade on these extensions, which you'll do by running Start-NavAppDataUpgrade on these extensions in Task 14. For the scenario in this article, at a minimum this step is required for the System and Base Applications. You can skip this step for any customization extensions that do not not include upgrade code.

Task 3: Create table migration extension

In this step, you create an extension that consists only of the non-system table objects from your custom base application. The table objects will only include the properties and field definitions. They won't include AL code on triggers or methods. This extension is an interim extension used only during the upgrade.

You'll create two versions of this extension. The first version contains the table objects. The second version, is an empty extension that contains a migrate.json file.

Create the first version

  1. Create a folder where you'll store exported txt files for tables (for example, C:\export2al\bc14tablesonly).

  2. Start the Dynamics NAV Development Shell for version 14.

  3. Run the Export-NAVApplicationObject cmdlet to export only tables from the database.

    Export-NAVApplicationObject -DatabaseServer .\BCDEMO -DatabaseName "Demo Database BC (14-0)" -ExportToNewSyntax -Path "C:\export2al\bc14tablesonly\exportedbc14-tables.txt" -Filter 'Type=Table;Id=1..1999999999'

  4. Use the txt2al conversion tool to convert the exported tables to the AL syntax. Use the --tableDataOnly parameter to include table and field definitions only.

    1. Create a folder for storing the AL files for base application objects (for example, C:\export2al\bc14tablesonly\al).

    2. Start a command prompt as an administrator, and navigate to the folder that contains txt2al.exe file.

      By default, the location is C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\140\RoleTailored Client.

    3. Run the txt2al command:

    txt2al --source=C:\export2al\bc14tablesonly --target=C:\export2al\bc14tablesonly\al --tableDataOnly

    For more information about this tool, see The Txt2Al Conversion Tool.

    Note

    If the --tableDataOnly parameter isn't available, you'll need a later version ot the txt2al conversion tool. For more information, see Prerequisites.

  5. Make sure you've installed the latest AL Extension for Visual Studio Code from the version 17 DVD.

    For more information, see Get Started with AL.

  6. In Visual Studio Code, create an AL project for table migration extension using the AL: Go! command.

    Set the target platform to 6.0 Business Central 2020 release wave 2.

  7. Configure the project's app.json file:

    • Set the "name", "publisher", and "version". You can use any valid values.
    • Delete the "application" parameter.
    • Clear the "dependencies".
    • Set the "idRanges" to cover the table object IDs or clear all values.
    • Add the "target" parameter and set it to "Onprem".

    Make a note of the "id" setting value, which is the ID assigned to the table migration extension. You'll use this ID later in the process. Don't use the ID in the following example. It's for illustration purposes only.

    {
  "id": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "name": "bc14tablesonly",
  "publisher": "My publisher",
  "version": "1.0.0.0",
  "brief": "",
  "description": "",
  "privacyStatement": "",
  "EULA": "",
  "help": "",
  "url": "",
  "logo": "",
  "dependencies": [],
  "screenshots": [],
  "platform": "17.0.0.0",
  "idRanges": [  ],
  "contextSensitiveHelpUrl": "https://bc14tablesonly.com/help/",
  "showMyCode": true,
  "runtime": "6.0",
  "target": "OnPrem"
}

  8. Create an .alpackages folder in the root folder of the project and then copy the version 17 system symbols extension (System.app file) to the folder.

    The System.app file is located where you installed the AL Development Environment. By default, the folder path is C:\Program Files (x86)\Microsoft Dynamics 365 Business Central\170\AL Development Environment. This package contains the symbols for all the system tables and codeunits.

  9. Add the AL files for tha tables that you converted earlier to the root folder for the project.

    The folder used in this article is C:\export2al\bc14tablesonly\al.

    Important

    If you're upgrading a CH or NA local version (14.18 or later), you'll have to rename the primary keys in some tables. For more information, see Known Issues.

  10. Build the extension package for the first version.

    To build the extension package, select Ctrl+Shift+B. This step creates an .app file for your extension. The file name has the format <publisher>_<name>_<version>.app.

Create the second version

  1. In Visual Studio Code, create a new file called migration.json file and add it to the project's root folder.

  2. In the migration.json, include rules for the Microsoft base application, system application, and your customization extensions.

    {
    "apprules": [
        {
            "id": "63ca2fa4-4f03-4f2b-a480-172fef340d3f"
        },
        {
            "id": "437dbf0e-84ff-417a-965d-ed2bb9650972"
        },
        {
            "id": "<NNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN>"
        }
    ]
}

    In the example code:

    • 63ca2fa4-4f03-4f2b-a480-172fef340d3f identifies the system application extension
    • 437dbf0e-84ff-417a-965d-ed2bb9650972 identifies the base application extension
    • The last entry is an example that identifies new customization extension. Include an entry for each customization extension for which you created an empty version in Task 2. Replace <NNNNNNNN-NNNN-NNNN-NNNN-NNNNNNNNNNNN> with the actual extension ID. Remove this entry if not used.

    For more information about the migration.json, see The Migration.json File.

  3. Delete the AL object files.

  4. Increase the version in the app.json file.

  5. Build the extension package for the second version.

    To build the extension package, select Ctrl+Shift+B.

DATA UPGRADE

Task 4: Prepare databases

  1. Make backup of the databases.

  2. 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.

  3. Start Business Central Administration Shell for version 14 as an administrator.

    For more information, see Run Business Central Administration Shell.

  4. (Single-tenant only) Uninstall all extensions from the tenants.

    To uninstall an extension, you use the Uninstall-NAVApp cmdlet. For example, 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}

  5. (Single-tenant only) Unpublish all extensions from the application server instance.

    To unpublish an extension, use the Unpublish-NAVApp cmdlet. For example, you can unpublish all extensions by using a single command:

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

  6. Unpublish all system, test, and application symbols.

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

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

    What are symbols?

  7. (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>

  8. Stop the server instance.

    Stop-NAVServerInstance -ServerInstance <server instance name>

Task 5: Convert version 14 database

This task runs a technical upgrade on the application database. The task converts the database from the version 14 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.

  1. If the database is on Azure SQL Database, you may get add your user account to the dbmanager database role on the master database.

    This membership is only required for converting the database, and can be removed afterwards. This step isn't required for Azure SQL Managed Instance.

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

  2. 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 (14-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 6: Configure version 17 server for DestinationAppsForMigration

In this step, you configure the version 17 server instance. In particular, you configure it to migrate the table migration extension that you created earlier. The migration is controlled by the DestinationAppsForMigration setting for the server instance. For more information about the DestinationAppsForMigration setting, see DestinationAppsForMigration.

  1. 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.

  2. Configure the DestinationAppsForMigration setting of the server instance to table migration extension.

    You'll need the ID, name, and publisher for the table migration extension that you created in Task 3.

    Set-NAVServerConfiguration -ServerInstance <server instance name> -KeyName "DestinationAppsForMigration" -KeyValue '[{"appId":"<table migration extension ID>", "name":"<table migration extension>", "publisher": "<publisher>"}]'

    For example:

    Set-NAVServerConfiguration -ServerInstance BC -KeyName "DestinationAppsForMigration" -KeyValue '[{"appId":"00001111-aaaa-2222-bbbb-3333cccc4444", "name":"bc14tablesonly", "publisher": "My publisher"}]'

    Note

    You can add multiple extensions to this setting.

  3. 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.

  4. Restart the server instance.

    Restart-NAVServerInstance -ServerInstance <server instance name>

Task 7: Import License

Import the version 17 partner license. To import the license, use the Import-NAVServerLicense cmdlet:

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

Restart the server instance.

Task 8: Publish symbols and DestinationAppsForMigrations

In this task, you'll publish the platform symbols and the extensions configured as DestinationAppsForMigration.

  1. 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?

  2. Publish the first version of the table migration extension, which is the version that contains the table objects.

    Publish-NAVApp -ServerInstance <server instance name> -Path "<path to extension .app file>"

  3. Publish the empty versions of the following extensions:

    • System Application extension
    • Base Application extension
    • Customization extensions (if any).

    This step publishes the extensions you created in Task 2. Publish the extensions using the Publish-NAVApp, like in the previous steps. Except if the extensions aren't signed, use the -SkipVerification switch parameter.

  4. Restart the server instance.

    Restart-NAVServerInstance -ServerInstance <server instance name>

Task 9: Synchronize tenant

In this task, 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.

  1. (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.

  2. 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.

  3. Synchronize the tenant with the table migration extension. This extension is the tables-only extension you created in Task 3.

    Use the Sync-NAVApp cmdlet:

    Sync-NAVApp -ServerInstance <server instance name> -Tenant <tenant ID> -Name "<table migration extension>" -Version <extension version>

    This step creates empty tables in the database for the table objects defined in the table migration extension. When completed, the table migration extension takes ownership of the table. In SQL Server, you'll notice that the table names will be suffixed with the extension ID. At this point, the tenant state is OperationalDataUpgradePending.

    Tip

    To verify the tenant state, run Get-NAVTenant cmdlet with the -ForceRefresh switch:

    Get-NAVTenant <server instance> -Tenant <default> -ForceRefresh

  4. Synchronize the empty versions of system application, base application, and customization extensions that you published in Task 8.

Task 10: Install DestinationAppsForMigration and move tables

In this task, you run a data upgrade on tables to handle data changes made by platform and extensions. The step installs table migration extension. It moves data from the old tables to the new tables owned by the table migration extension.

  1. To run the data upgrade, use the Start-NavDataUpgrade cmdlet:

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

  2. Before continuing, wait until the data upgrade process completes, and the tenant status becomes operational. It can take several minutes before the process completes.

    To view the progress of the data upgrade, run Get-NavDataUpgrade cmdlet with the –Progress or –Detailed switches, like:

    Get-NAVDataUpgrade -ServerInstance <server instance name> -Tenant <tenant ID> -Progress

    Or

    Get-NAVDataUpgrade -ServerInstance <server instance name> -Tenant <tenant ID> -Detailed

    The process is complete when you see State = Operational in the results.

    When completed, the table migration extension will be installed.

  3. Install the empty versions of the system, base, and custom extensions that you published in Task 8.

    To install the extension, you use the Install-NAVApp cmdlet.

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

  4. (Multitenant only) Repeat steps 1 and 2 for each tenant.

Task 11: Publish final extensions

This step starts the second phase of the data upgrade. You'll publish the second version of the table migration extension and the production versions of extensions. The production extensions include the new versions of Microsoft System Application, Base Application extension, and customization extensions. The extension packages for Microsoft extensions are on the installation media (DVD). Customization extensions include the extension versions that you created in Task 1, not the empty versions that you created in Task 2. Publish extensions using the Publish-NAVApp cmdlet like you did in previous steps.

Publish-NAVApp -ServerInstance <server instance name> -Path "<path to extension .app file>"

Publish the extensions in the following order:

  1. Second version of the table migration extension, which is the empty version with the migration.json file.

  2. Microsoft System Application

    Publish the Microsoft_System Application.app extension package file that is in the Applications\System Application\Source folder of installation media (DVD).

  3. Microsoft Base Application

    Publish the Microsoft_Base Application.app extension package file that is in the Applications\BaseApp\Source folder of installation media (DVD).

    Note

    The other .app files in this folder, like Microsoft_Danish language (Denmark).app, are extensions that add translations for a specific language. By publishing and installing these extensions, you add the capability of showing the base application in another language. These extensions aren't required to complete the upgrade and can be published and installed later.

  4. Customization extensions.

  5. Application extension.

  6. Microsoft and third-party extensions.

    The Microsoft extensions are in the Applications folder of installation media (DVD).

Task 12: Synchronize final extensions

Synchronize the newly published extensions using the Sync-NAVApp cmdlet like you did in previous steps.

Sync-NAVApp -ServerInstance <server instance name> -Tenant <tenant ID> -Name "<extension name>" -Version <extension version>

Synchronize the extensions in the following order:

  1. Microsoft System Application
  2. Microsoft Base Application
  3. Microsoft Application
  4. Microsoft and third-party extensions
  5. Customization extensions
  6. Second version of the table migration extension (empty version)

Important

Synchronize extensions in the order of dependencies. The migration extension must be synchronized last. This step will change table ownership to the system and base application.

Task 13: Upgrade empty table migration extension

Run data upgrade on the table migration extension (empty version) by using the Start-NAVAppDataUpgrade cmdlet. For example:

Start-NAVAppDataUpgrade -ServerInstance <server instance> -Name "<table migration extension>" -version <version 2>

Task 14: Upgrade and install final extensions

The final step is to upgrade to the new extension versions in the following order. Use the Start-NAVAppDataUpgrade or Install-NAVApp cmdlets like you did in the previous task.

Run the data upgrade on the extensions in the following order:

  1. Upgrade the Microsoft System Application extension.

  2. Upgrade the Microsoft Base Application extension.

  3. Install the Microsoft Application extension

  4. Upgrade customization extensions, Microsoft, and third-party extensions.

    For customization extensions, only do this step for those extensions that have an empty version currently installed on the tenant (see Task 10). If you have a customization extension for which you didn't create and publish an empty version, complete the next step to install these extensions.

  5. Install remaining customization extensions for which you didn't create and publish an empty version.

Task 15: Upgrade control add-ins

The Business Central Server installation includes new versions of the Microsoft-provided Javascript-based control add-ins that must be upgraded.

  • Microsoft.Dynamics.Nav.Client.BusinessChart
  • Microsoft.Dynamics.Nav.Client.FlowIntegration
  • Microsoft.Dynamics.Nav.Client.OAuthIntegration
  • Microsoft.Dynamics.Nav.Client.PageReady
  • Microsoft.Dynamics.Nav.Client.PowerBIManagement
  • Microsoft.Dynamics.Nav.Client.RoleCenterSelector
  • Microsoft.Dynamics.Nav.Client.SocialListening
  • Microsoft.Dynamics.Nav.Client.SatisficationSurvey
  • Microsoft.Dynamics.Nav.Client.TimelineVisualization
  • Microsoft.Dynamics.Nav.Client.VideoPlayer
  • Microsoft.Dynamics.Nav.Client.WebPageViewer
  • Microsoft.Dynamics.Nav.Client.WelcomeWizard

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

  1. Open the Business Central client.

  2. Search for and open the Control Add-ins page.

  3. Choose Actions > Control Add-in Resource > Import.

  4. 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\170\Service\Add-ins\BusinessChart\Microsoft.Dynamics.Nav.Client.BusinessChart.zip.

  5. After you've imported all the new control add-in versions, restart Business Central Server instance.

Instead, 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 16: 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 14.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.

  1. 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

  2. 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.

  3. 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

  1. Uninstall the table migration extension.

  2. Enable task scheduler on the server instance.

  3. (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.

  4. 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.

  5. Grant users permission to the Open in Excel and Edit in Excel actions.

    Version 17 introduces a system permission that protects these two actions. The permission is granted by the system object 6110 Allow Action Export To Excel. Because of this change, users who had permission to these actions before upgrading, will lose permission. To grant permission again, do one of the following steps:

    • Assign the EXCEL EXPORT ACTION permission set to appropriate users.

    • Add the system object 6110 Allow Action Export To Excel permission directly to appropriate permission sets.

    For more information about working with permission sets and permissions, see Export and Import Permission Sets.

Publishing and Installing an Extension
Upgrading to Business Central
Sign an APP Package File