Start-NAVDataUpgrade

Starts the process for upgrading the data in the tenant database.

Syntax

Start-NAVDataUpgrade
     [[-Tenant] <TenantId>]
     [-Language <LanguageSetting>]
     [[-FunctionExecutionMode] <FunctionExecutionModeValue>]
     [-ContinueOnError]
     [-SkipCompanyInitialization]
     [-SkipAppVersionCheck]
     [-SkipUserSessionCheck]
     [-ExcludeExtensions]
     [-SkipIfAlreadyUpgraded]
     [-ServerInstance] <String>
     [-Force]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]
Start-NAVDataUpgrade
     [[-Tenant] <TenantId>]
     [-Language <LanguageSetting>]
     [-SingleTransaction]
     [-SkipCompanyInitialization]
     [-SkipAppVersionCheck]
     [-SkipUserSessionCheck]
     [-ExcludeExtensions]
     [-SkipIfAlreadyUpgraded]
     [-ServerInstance] <String>
     [-Force]
     [-WhatIf]
     [-Confirm]
     [<CommonParameters>]

Description

The Start-NavDataUpgrade cmdlet calls the CheckPreconditions and Upgrade type functions in the upgrade codeunits that are set up for the application. These functions are used to update data in tables of the tenant database when schema changes have been made to tables in application database. These functions are called as follows:

  1. CheckPreconditions type functions are called (in random order). If an error occurs, then any changes made in this step are rolled back.

  2. Upgrade type functions are called (in random order). If an error occurs, then any changes made in this step are rolled back. All upgrade functions are executed in parallel (at the same time) unless you choose a different mode by setting the -FunctionExecutionMode parameter. When running in parallel, it is important that all upgrade functions of the type "CheckPrecondition" and "Upgrade" can be run independently of each other. If not, then place the dependent functions into a single upgrade function in the required order. The progress of the running process can be monitored using Get-NAVDataUpgrade cmdlet, stopped using Stop-NAVDataUpgrade cmdlet, and resumed using Resume-NAVDataUpgrade cmdlet.

Examples

EXAMPLE 1

Start-NAVDataUpgrade -ServerInstance BC -Force

This example starts new data upgrade process that runs upgrade functions in parallel.

EXAMPLE 2

Start-NAVDataUpgrade -ServerInstance BC -ContinueOnError -Force

This example starts new data upgrade process that runs upgrade functions run in parallel and is set to continue running when errors occur.

EXAMPLE 3

Start-NAVDataUpgrade -ServerInstance BC -FunctionExecutionMode Serial -Force

This example starts new data upgrade process that runs upgrade functions in serial. The execution of CheckPrecondition type functions will stop the process. Failure in an upgrade function will suspend the upgrade process, which can then be resumed by using Resume-NAVDataUpgrade cmdlet.

Parameters

-Confirm

Prompts you for confirmation before executing the command.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ContinueOnError

Specifies whether the Business Central Server instance continues to execute other upgrade functions when an error occurs while executing an upgrade function.

If you do not set this parameter, then when an error occurs, the Business Central Server instance will suspend the data upgrade process. It will cancel the execution of upgrade functions currently in progress and roll back any changes that were applied. Completed functions will not be rolled back.

The process remains in suspended state until you take one of the following actions:

  • Fix the problems in the upgrade functions that failed, and then resume the process by using the Resume-NAVDataUpgrade cmdlet. You should not add new upgrade functions at this time because they will be ignored when you resume the process.

  • Stop the data upgrade process by using the Stop-NAVDataUpgrade cmdlet. Stopping the process will not roll back changes made by upgrade functions that have already been executed.

If you set this parameter, then when an error occurs, the Business Central Server instance will continue executing other upgrade functions. At the end of the process, you can use the Get-NAVDataUpgrade cmdlet to see the list of failed upgrade functions. Changes that were applied by completed functions will not be rolled back.

When upgrading a large database, you should increase the SQL Command Timeout setting for the Business Central Server instance that connects to the database to avoid timeouts during schema synchronization. The default setting is 30 minutes. For more information, see Configuring Business Central Server in the MSDN Library.

Type:SwitchParameter
Position:3
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-ExcludeExtensions

Specifies whether extensions, which would normally be part of the upgrade, should be exluded. By default, when the tenant is mounted and has older versions of extensions installed that are not published on the server then those extensions are required to be upgraded before the tenant is considered 'operational'.

If you set this parameter, the data upgrade is run without upgrading any extensions that need to be upgraded. Be aware that the tenant will still not be usable until those extensions have been upgraded. The extensions can still be upgraded individually using the Start-NavAppDataUpgrade cmdlet. You will typically use the parameter when an extension upgrade has errors and you want to check them individually.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-Force

Forces the command to run without asking for user confirmation.

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-FunctionExecutionMode

Specifies whether the Business Central Server instance executes upgrade functions in series or parallel.

If the parameter is set to Serial, then CheckPrecondition and Upgrade type functions for each company are executed in series (one after another).

If the parameter is set to Parallel, then CheckPrecondition type functions will be executed for all companies in parallel (starting at the same time), and if completed successfully, then all Upgrade type functions for all companies will be executed in parallel.

Type:FunctionExecutionModeValue
Accepted values:Parallel, Serial
Position:2
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-Language

Specifies the language in which the upgrade, specifically codeunits, will run. The value must be a valid culture name for a language in Business Central, such as en-US or da-DK. If the specified language does not exist on the Business Central Server instance, the language en-US will be used.

The Resume-NAVDataUpgrade function will also run in the language that was used by bthe Start-NAV DataUpgrade cmdlet.

This parameter is similar -Language paramter of the Invoke-NAVCodeunit cmdlet.

Type:LanguageSetting
Position:Named
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-ServerInstance

Specifies the name of a Business Central Server instance, for example, BC or myinstance. You can specify either the full name of an instance, such as MicrosoftDynamicsNavServer$myinstance or the short name such as myinstance. You must include the name within single quotation marks.

Type:String
Position:0
Default value:None
Accept pipeline input:True (ByPropertyName, ByValue)
Accept wildcard characters:False
-SingleTransaction

Specifies whether the Business Central Server instance executes upgrade functions within one transaction. This switch is used with Serial execution mode.

You cannot set this parameter if you have set the -FunctionExecutionMode parameter.

Type:SwitchParameter
Position:4
Default value:False
Accept pipeline input:False
Accept wildcard characters:False
-SkipAppVersionCheck

Specifies whether to check the application version of the tenant and application database before starting the data upgrade. By default, the application version of the tenant and application database on the Business Central Server instance are compared and verified against the supported application versions of the tenant database to determine whether the versions are compatible for the data upgrade. If the versions are not compatible, for example they are the same or differ by more than one version, then an error occurs and the data upgrade process is not started.

If you set this parameter, the data upgrade is run without checking the application versions. Be aware that skipping the application version check can potentially result in unwanted or destructive changes to the tenant data. The extent of the changes depends on upgrade code that is run. You will typically use this parameter when you are confident that running the data upgrade will not have an adverse effect on the tenant data.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-SkipCompanyInitialization

Specifies not to run codeunit 2 Company Initialization during the data upgrade.

Type:SwitchParameter
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False
-SkipIfAlreadyUpgraded

Skips the data upgrade if the application version number of the tenant database is greater or equal to the application version number of the application database on the Business Central Server instance.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-SkipUserSessionCheck

Specifies to run the data upgrade even if there are active user sessions on the server instance.

Without setting this parameter, user sessions must be ended before the data upgrade can be run. If you set this parameter, the cmdlet runs without checking for active user sessions. Be aware that this can potentially result in conflicts because of locked tables.

This parameter is available only in Business Central April 2019 and later versions.

Type:SwitchParameter
Position:Named
Default value:False
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-Tenant

Specifies the ID of the tenant that you want to synchronize with the application, such as Tenant1. This parameter is required unless the specified service instance is not configured to run multiple tenants.

Type:TenantId
Aliases:Id
Position:1
Default value:None
Accept pipeline input:True (ByPropertyName)
Accept wildcard characters:False
-WhatIf

Describes what would happen if you executed the command without actually executing the command.

Type:SwitchParameter
Aliases:wi
Position:Named
Default value:None
Accept pipeline input:False
Accept wildcard characters:False

Inputs

System.String

You can pass the value of the ServerInstance and Tenant parameters as a string to this cmdlet.

Notes

Because the functions in the steps are called in random order, you should design the functions so that they are independent from each other.