Share via


Sync-NAVApp

Synchronizes a Business Central app to the specified tenant's database.

Syntax

TenantProperties (Default)

Sync-NAVApp
    [-ServerInstance] <String>
    [-Name <String>]
    [-Publisher <String>]
    [-Version <Version>]
    [-AppId <Guid>]
    [-CommitPerTable <Boolean>]
    [-Tenant <TenantId>]
    [-Mode <NavAppSyncMode>]
    [-ExclusiveAccessTicket <String>]
    [-PassThru]
    [-Force]
    [<CommonParameters>]

TenantDatabaseProperties

Sync-NAVApp
    [-ServerInstance] <String>
    [-Name <String>]
    [-Publisher <String>]
    [-Version <Version>]
    [-AppId <Guid>]
    [-CommitPerTable <Boolean>]
    [-TenantDatabaseId <TenantDatabaseId>]
    [-Mode <NavAppSyncMode>]
    [-PassThru]
    [-Force]
    [<CommonParameters>]

TenantPath

Sync-NAVApp
    [-ServerInstance] <String>
    -Path <String>
    [-CommitPerTable <Boolean>]
    [-Tenant <TenantId>]
    [-Mode <NavAppSyncMode>]
    [-ExclusiveAccessTicket <String>]
    [-PassThru]
    [-Force]
    [<CommonParameters>]

TenantDatabasePath

Sync-NAVApp
    [-ServerInstance] <String>
    -Path <String>
    [-CommitPerTable <Boolean>]
    [-TenantDatabaseId <TenantDatabaseId>]
    [-Mode <NavAppSyncMode>]
    [-PassThru]
    [-Force]
    [<CommonParameters>]

Description

Use the Sync-NAVApp cmdlet to synchronize the schema changes from an app to a tenant database. You must run this cmdlet after you publish an app to the server; otherwise you will not be able to install the app on tenants. This must be done after you publish an app for the first time and for each new version that you publish for upgrade. For more information, see Publishing and Installing an Extension and Upgrading Extensions

You can also use this cmdlet to delete the all versions of an app from the tenant database, after all versions have been uninstalled from the tenant, and eventually unpublished. For more information, see Unpublishing and Uninstalling Extensions.

Examples

EXAMPLE 1

Sync-NAVApp -ServerInstance BC -Id 'Test_Database' -Name 'Proseware SmartApp' -Publisher Proseware -Version 2.3.4.500 -Mode Add

This example synchronizes the Business Central app 'Proseware SmartApp' to a tenant database with the ID 'Test_Database'.

EXAMPLE 2

Sync-NAVApp -ServerInstance BC -Path '.\Proseware SmartApp.app' -Tenant 'Tenant1'

This example synchronizes the app at the specified path to the tenant database for the tenant with the ID 'Tenant1'.

EXAMPLE 3

Sync-NAVApp -ServerInstance BC -Tenant 'Tenant1' -Name 'Proseware SmartApp' -ExclusiveAccessTicket $ticket

This example synchronizes the Business Central app 'Proseware SmartApp' to the tenant database for the tenant with the ID 'Tenant1'. 'Tenant1' is in exclusive access mode and $ticket is the exclusive access ticket.

EXAMPLE 4

Sync-NAVApp -ServerInstance BC -Tenant 'Tenant1' -Name 'Proseware SmartApp' -Mode Clean

This example uses the '-Mode' parameter to synchronize the tenant database for the tenant with the ID Tenant1 and remove the schema entities created by the Business Central app 'Proseware SmartApp' (for example, tables and table extension related objects).

Parameters

-AppId

Specifies the app Id of the Business Central App that you want to synchronize. The results must uniquely identify a single Business Central App.

Parameter properties

Type:Guid
Default value:00000000-0000-0000-0000-000000000000
Supports wildcards:False
DontShow:False

Parameter sets

TenantProperties
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
TenantDatabaseProperties
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-CommitPerTable

Specifies that database schema modifications for the app are committed by separate transactions. Transactions are run one at a time, as they occur.

With the default behavior (that is, without using the -CommitPerTable parameter), all modifications are committed in a single transaction. Using this method provides better protection against leaving the database in an inconsistent state than using the -CommitPerTable parameter. If the synchronization process is terminated before it is completed, any changes that were made before the problem occurred are rolled back, returning the database to its original state. The drawback is that for a large database schema (for example, a large number of companies), the synchronization process can take a long time and consume considerable computer resources.

The advantage of setting the -CommitPerTable is that it will decrease the time that is required to complete the synchronization process and consume less computer resources, which can be useful for large database schemas when performance is a concern. However, when you set this parameter, committed changes are not rolled back if the synchronization process is terminated before it is completed. This can result in a partial synchronization of the database, which might leave the database inoperable. We recommend that you make a backup of the database before you run the Sync-NavApp cmdlet. Also, tables are not always locked during synchronization. Therefore, you should prohibit users from connecting to the database during synchronization.

Parameter properties

Type:Boolean
Default value:False
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-ExclusiveAccessTicket

Specifies the exclusive access ticket allowing this operation on the tenant in the exclusive access mode.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

TenantProperties
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
TenantPath
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Force

Forces the command to run without asking for user confirmation.

Parameter properties

Type:SwitchParameter
Default value:False
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Mode

The sync mode that dictates the behavior of the command. Specifies how the database schema for the tenant database is synchronized with the database schema that the target Business Central app's objects define.

Add: The database schema defined by the objects in the target Business Central app are added to the database schema of the target tenant database. That is, if a table or table extension was included in the target Business Central app, then the respective full or companion table is created in the tenant database. You will use this mode after you publish an extension for the first time.

Clean: The database schema defined by all versions of the target Business Central app will be removed from the target tenant database and all data is lost. That is, if a table or table extension was included in any version of the target Business Central app, then the respective full or companion table will be dropped from the tenant database.

Note

You cannot synchronize in clean mode if any version of the extension is installed on a tenant of the server instance. Moreover, in production, this should primarily be done as a final cleanup step after all versions of an extension have been uninstalled and unpublished for good.

Note

If you specify the TenantDatabaseId flag and the tenant is not mounted, then the extension can be synced with mode Clean even if the extension is installed for that tenant.

Development: This mode is acts similar to Add, except it is intended for use during development. It enables you to sync the same version of an App that is already published, eliminating the need to increase the version number. However, to run this mode, only one version the App can be currently published.

ForceSync: This mode is also intended for use during development, but unlike the Development and Add modes, it supports destructive schema changes (like removing fields, renaming them, changing their datatypes, and more). This mode is useful in development because it enables you to make these kinds of changes without losing data. Because destructive changes are not backwards compatible, this mode should not be used in production. To use this mode, the App must first be uninstalled from the tenant.

None: This mode doesn't synchronize the app.

Parameter properties

Type:NavAppSyncMode
Default value:Add
Accepted values:Add, Clean, Development, ForceSync, None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Name

Specifies the name of the Business Central app that you want to synchronize. The results must uniquely identify a single Business Central app.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False
Aliases:AppName

Parameter sets

TenantProperties
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
TenantDatabaseProperties
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-PassThru

Returns an Extension object for the synced Extension. The Extension object contains the properties of the Extension, such as name, publisher, version.

Parameter properties

Type:SwitchParameter
Default value:False
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-Path

Specifies the path to a Business Central app package file that you want to synchronize.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

TenantPath
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
TenantDatabasePath
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Publisher

Specifies the publisher of the Business Central app that you want to synchronize. The results must uniquely identify a single Business Central app.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False
Aliases:AppPublisher

Parameter sets

TenantProperties
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False
TenantDatabaseProperties
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ServerInstance

Specifies the Business Central Server instance that the Business Central app is published to, such as BC.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:0
Mandatory:True
Value from pipeline:True
Value from pipeline by property name:True
Value from remaining arguments:False

-Tenant

Specifies the ID of a specific tenant that you want to act on, such as Tenant1.

Parameter properties

Type:TenantId
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

TenantProperties
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
TenantPath
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-TenantDatabaseId

Specifies the ID of a specific tenant database that you want to act on, such as Data1.

Parameter properties

Type:TenantDatabaseId
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

TenantDatabaseProperties
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
TenantDatabasePath
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

-Version

Specifies the version of the Business Central app that you want to synchronize. The results must uniquely identify a single Business Central app.

Parameter properties

Type:Version
Default value:None
Supports wildcards:False
DontShow:False
Aliases:AppVersion

Parameter sets

TenantProperties
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False
TenantDatabaseProperties
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:True
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Inputs

System.String

By value and by property name: ServerInstance

System.String

By property name: Name

System.String

By property name: Publisher

System.Version

By property name: Version

System.String

By property name: Path

Microsoft.Dynamics.Nav.Types.TenantId

By property name: Tenant

Microsoft.Dynamics.Nav.Types.TenantDatabaseId

By property name: TenantDatabaseId

Microsoft.Dynamics.Nav.Types.NavAppSyncMode

By property name: Mode

System.String

By property name: ExclusiveAccessTicket