Automating the Upgrade Process using Sample Windows PowerShell Scripts

  • Article

Applies to: Microsoft Dynamics NAV 2017. See Microsoft Dynamics NAV 2018 version.

You can use Windows PowerShell scripts to help you upgrade to the latest version of Dynamics NAV. You can use automation to upgrade a single Dynamics NAV database as well as multiple Dynamics NAV databases that use the same application. Microsoft Dynamics NAV 2018 provides sample scripts that you can adapt for your deployment architecture.

Automating the Upgrade Process

When you upgrade to Microsoft Dynamics NAV 2018, you must first upgrade the application code, and then you upgrade the data. By using Windows PowerShell, you can automate both parts of the upgrade process. Also, you can use the same scripts to test each step in your upgrade process before you upgrade production databases.

Also, if you maintain multiple Dynamics NAV databases, for example if you support multiple customers with the same Dynamics NAV application, you can reduce the time that you spend upgrading each database by using Windows PowerShell scripts. In that case, you can upgrade the application locally, and then use scripts to roll out the upgrade of each database with reduced unavailability for each database. You can combine this automated upgrade with a migration to multitenancy if this makes maintenance easier for you.

The Sample Scripts for Code Upgrade

Dynamics NAV includes sample scripts that illustrate how you can use Windows PowerShell cmdlets to upgrade your application to the latest version of Dynamics NAV. The sample scripts are located in the ApplicationMergeUtilities folder under the WindowsPowerShellScripts folder on the Dynamics NAV product media. The sample scripts illustrate how you can create scripts that you run in the Microsoft Dynamics NAV Development Shell or the Windows PowerShell Integrated Scripting Environment (ISE).

The sample scripts show different ways of merging application objects that can help you find the best approach to upgrade your application code. The ApplicationMergeUtilities folder contains four subfolders that can help you start working with the scripts. The demonstration data in the ORIGINAL, MODIFIED, and TARGET folders illustrate the text files that are the input to the cmdlets. The __Run-Application-Merge-Utilities.ps1 script runs the sample scripts based on simplified demonstration data. For more information, see Merging Application Objects using the Example Scripts.

The Sample Scripts for Data Upgrade

Dynamics NAV includes sample scripts that illustrate how you can automate the upgrade of data to the latest version of Dynamics NAV. The sample scripts are located in the Upgrade folder under the WindowsPowerShellScripts folder on the Dynamics NAV product media. The sample scripts include a HowTo script that illustrates how you can use the Dynamics NAV cmdlets and sample scripts.

The HowTo-UpgradeNAVDatabase.ps1 script illustrates how you can create a script that upgrades a database from an earlier version of Dynamics NAV to a new version through a set of upgrade tasks. You can run the sample script using a partner license or a customer license.

The Upgrade folder also contains the Set-PartnerSettings.ps1 where you can specify values for the input parameters that the HowTo-UpgradeNAVDatabase.ps1 script requires, such as the database that you want to upgrade. You must also specify the folder where the license is stored. Finally, you must specify the location of the .fob file with the upgraded application objects. Optionally, the upgrade toolkit objects can be part of that .fob file, or they can be stored in a separate .fob file and import them later.

The Example.ps1 script reads the upgrade parameters from the Set-PartnerSettings.ps1 script, calls the HowTo script, passing the upgrade parameters, and then shows the detailed information about each upgrade task. To run the sample script for the data upgrade of a Dynamics NAV database, you must have a Microsoft Dynamics NAV 2013, Microsoft Dynamics NAV 2013 R2, or Microsoft Dynamics NAV 2015 database that is available on a SQL Server instance and is ready to be upgraded. The Example.ps1 script runs the following main steps:

  1. Loads the settings from the Set-PartnerSettings.ps1 file, and prepares the Windows PowerShell session by importing the required modules.

  2. Saves the current license from the Microsoft Dynamics NAV 2013, Microsoft Dynamics NAV 2013 R2, or Microsoft Dynamics NAV 2015 database.

  3. Creates a backup of the Microsoft Dynamics NAV 2013, Microsoft Dynamics NAV 2013 R2, or Microsoft Dynamics NAV 2015 database, and then converts the database to Microsoft Dynamics NAV 2018.

  4. Connects the Microsoft Dynamics NAV 2018 Server instance to the converted database, imports the Microsoft Dynamics NAV 2018 license file, and then synchronizes the table schema.

  5. Imports the application objects and upgrade toolkit objects from the specified .fob file, and then synchronizes the table schema again. This updates the SQL Server database based on the new table schema that is defined by the imported application objects. Data that must be mapped to another table is saved in upgrade tables.

  6. Calls the Start-NAVDataUpgrade cmdlet to verify the data upgrade preconditions and transfer data from the upgrade tables to the destination tables.

  7. Deletes all obsolete tables and the upgrade toolkit objects.

  8. Initializes all companies in the upgraded database. If you specified a RapidStart package in the Set-PartnerSettings.ps1 file, the package is applied to all companies.

    The sample script is intended to be run in the context of a Microsoft Dynamics NAV 2018 deployment, including the Microsoft Dynamics NAV Server instance. The Microsoft Dynamics NAV Server instance cannot be multitenant. When the sample script runs successfully, the result is a Microsoft Dynamics NAV 2018 database that is connected to a Microsoft Dynamics NAV 2018 Server instance, and which uses a Microsoft Dynamics NAV 2018 license. The sample script also returns a list of statistics about the upgrade tasks, including information about whether the task ran or not. If a task failed, it is marked, and the information includes the error message and stack trace to help you identify the problem. You can resolve errors in the Microsoft Dynamics NAV Development Environment, save changes, and then run the sample script again, using the database backup that you created earlier.

See Also

Microsoft Dynamics NAV Windows PowerShell Cmdlets
Sample Windows PowerShell Scripts for Microsoft Dynamics NAV
Merging Application Objects using the Example Scripts
Upgrading the Application Code
Upgrading to Microsoft Dynamics NAV 2017