Start-NAVDataUpgrade

  • Reference
Module:
Microsoft.BusinessCentral.Management

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

Syntax

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

Description

The Start-NAVDataUpgrade cmdlet does the following:

  • Runs logic to required upgrade the platform-related data in database.
  • Runs upgrade codeunits for any extension that is installed on the tenant but the installed version is not published to the application on the server instance. You have the option to skip this step by using the -ExcludeExtensions parameter.

You'll typically use the Start-NAVDataupgrade cmdlet when upgrading from one Business Central major version to another.

The process that's run by Start-NavDataUpgrade cmdlet is as follows:

  1. Runs upgrade on eligible extensions, including steps for the OnCheckPreconditions, OnUpgrade, OnValidateUpgrade triggers, and other upgrade methods (functions). These functions are used to update data in tables of the tenant database when schema changes have been made to tables in application database. The order in which the upgrade codeunits are run is random.

    If an error occurs in a step, then any changes made in the 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 can be run independently of each other.

  2. Runs upgrade steps on the platform data. You can see the steps in this process by running the Get-NAVDataUpgrade cmdlet with the -Detailed switch set. The steps are indicated by the following details for each company:

    Detail Value
    ModuleName BASE
    WorkflowStep CheckPreconditions, OnUpgrade, OnValidateUpgrade, AfterUpgradeCommit

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

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

EXAMPLE 2

Start-NAVDataUpgrade -ServerInstance BC -ContinueOnError

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

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
Required:False
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 Business Central Developer and IT Pro help.

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

-ExcludeExtensions

Specifies whether extensions, which would normally be part of the upgrade, should be excluded. 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
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Force

Forces the command to run without asking for user confirmation.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
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). The results are not returned until all upgrade steps have been run.

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:Serial
Position:2
Default value:None
Required:False
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 parameter of the Invoke-NAVCodeunit cmdlet.

Type:LanguageSetting
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-ProgressAction

A common PowerShell parameter that determines how PowerShell responds to progress updates generated by a script, cmdlet, or provider. Learn more.

Type:ActionPreference
Aliases:proga
Position:Named
Default value:None
Required:False
Accept pipeline input:False
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
Required:True
Accept pipeline input:True
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
Required: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.

In the application database, the application version is stored in the applicationversion column of the $ndo$dbproperty table. In the tenant database, the application version is stored in the applicationversion column of the $ndo$tenantdatabaseversion table.

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.

You can't set this parameter if you also set the -SkipIfAlreadyUpgraded parameter. If you do, you'll get the error Parameter set cannot be resolved using the specified named parameters.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-SkipIfAlreadyUpgraded

Compares the application version of the application database to the application version of the tenant database. If the application version is the same in both, then the data upgrade process isn't run.

In the application database, the application version is stored in the applicationversion column of the $ndo$dbproperty table. In the tenant database, the application version is stored in the applicationversion column of the $ndo$tenantdatabaseversion table.

You can't set this parameter if you also set the -SkipAppVersionCheck parameter. If you do, you'll get the error Parameter set cannot be resolved using the specified named parameters.

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:True
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
Required:False
Accept pipeline input:True
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
Required:False
Accept pipeline input:True
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
Required:False
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.