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 does the following:
- Runs logic to required upgrade the platform-related data in database.
- Runs upgrade codunits that are built in CSIDE.
- Runs upgrade codeunits (in AL) for any extensions 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
-ExcludeExtensionsparameter.
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:
Calls the CheckPreconditions and Upgrade type functions in the CSIDE 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:
CheckPreconditions type functions are called (in random order).
If an error occurs, then any changes made in this step are rolled back.
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.
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.
Runs upgrade steps on the platform data. You can see the steps in this process by running the Get-NAVDataUpgrade cmdlet with the
-Detailedswitch 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 BCThis example starts new data upgrade process that runs upgrade functions in parallel.
EXAMPLE 2
Start-NAVDataUpgrade -ServerInstance BC -ContinueOnErrorThis 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 SerialThis 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 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 |
| 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: | Parallel, 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 paramter of the Invoke-NAVCodeunit cmdlet.
| Type: | LanguageSetting |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| 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 |
-SkipCompanyInitialization
Specifies not to run codeunit 2 Company Initialization during the data upgrade.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| 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.