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]
[-ExcludeExtensions]
[-SkipIfAlreadyUpgraded]
[-ServerInstance] <String>
[-Force]
[-WhatIf]
[-Confirm]
[<CommonParameters>] Start-NAVDataUpgrade
[[-Tenant] <TenantId>]
[-Language <LanguageSetting>]
[-SingleTransaction]
[-SkipCompanyInitialization]
[-SkipAppVersionCheck]
[-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:
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. 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 DynamicsNAV -ForceThis example starts new data upgrade process that runs upgrade functions in parallel.
EXAMPLE 2
Start-NAVDataUpgrade -ServerInstance DynamicsNAV -ContinueOnError -ForceThis 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 DynamicsNAV -FunctionExecutionMode Serial -ForceThis 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 Microsoft Dynamics NAV 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 Microsoft Dynamics NAV 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 Microsoft Dynamics NAV 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 Microsoft Dynamics NAV Server instance that connects to the database to avoid timeouts during schema synchronization. The default setting is 30 minutes. For more information, see Configuring Microsoft Dynamics NAV Server in the MSDN Library.
| 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 Microsoft Dynamics NAV 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 |
| 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 Microsoft Dynamics NAV, such as en-US or da-DK. If the specified language does not exist on the Microsoft Dynamics NAV 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 Dynamics NAV Server instance, for example, DynamicsNAV 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 Microsoft Dynamics NAV 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 Dynamics NAV 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 |
| 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
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 Dynamics NAV Server instance.
| 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.