Edit

Share via

Publishing and installing an extension

  • Article

To make your extension available to tenant users requires three basic tasks: publish the extension package to the Dynamics 365 Business Central server instance, synchronize the extension with the tenant database, and install the extension on the tenant.

Note

This article describes how to publish and install the first version of an extension. If you want to publish an install newer version of an extension, see Upgrading Extensions.

Publish and synchronize an extension

Publishing an extension to a Dynamics 365 Business Central server instance adds the extension to the application database that is mounted on the server instance, making it available for installation on tenants of the server instance. Publishing updates internal tables, compiles the components of the extension behind-the-scenes, and builds the necessary metadata objects that are used at runtime.

Synchronizing an extension updates the database schema of the tenant database with the database schema that is defined by the extension objects. If a table or table extension is included in the extension, the respective full or companion table is created in the tenant database.

  1. Start the Business Central Administration Shell.

  2. To publish the extension, run the Publish-NAVApp cmdlet.

    The cmdlet takes as parameters the Dynamics 365 Business Central service instance that you want to install to and the .app package file that contains the extension. The following example publishes the extension MyExtension.app to the YourDynamicsNAVServer instance.

    Publish-NAVApp -ServerInstance YourDynamicsNAVServer -Path ".\MyExtension.app"

    Note

    If you are publishing a version 16.0 Microsoft extension, you'll have to include the -SkipVerification parameter. Otherwise, you will get the error "Publish-NAVApp : You cannot publish an extension that has not been code signed.". This issue is fixed in later versions.

  3. To synchronize the schema of a tenant database to the extension, run the Sync-NavApp cmdlet.

    The following example synchronizes the extension MyExtension with version number 1.0.0.0:

    Sync-NavApp -ServerInstance YourDynamicsNAVServer -Name ExtensionName -Version 1.0.0.0 -Tenant TenantID

    Replace TenantID with the tenant ID of the database. If you don't have a multitenant server instance, use default or omit this parameter.

The extension can now be installed on tenants.

Install an extension

After you publish and synchronize an extension, you can install it on tenants. The extension is then available to users in the client. Installing an extension can be done from the Dynamics 365 client or Business Central Administration Shell.

Note

Installing an extension will run any installation code that is built-in to the extension. Installation code could, for example, perform operations like populating empty records with data, service callbacks and telemetry, version checks, and messages to users. For more information, see Writing Extension Install Code.

Install an extension by using Business Central Administration Shell

  1. Start the Business Central Administration Shell.

  2. To install the extension on one or more tenants, use the Install-NAVApp cmdlet.

    The following example installs the extension My Extension for Tenant1 and Tenant3. In single-tenant deployments, you either specify default as the tenant ID, or you omit the –Tenant parameter.

    Install-NAVApp -ServerInstance YourDynamicsNAVServer -Name "My Extension" –Tenant Tenant1, Tenant3

Install an extension by using the client

  1. In Dynamics 365 Business Central, use search to open the Extension Management page.

    In the Extension Management window, you can view the extensions that are published to your server. For each extension, you can see the current installation status.

  2. Select an extension to see additional information and to install the extension.

  3. Review and accept the license agreement.

  4. Select the Install button to install the extension.

Unpublishing and Uninstalling Extensions
Developing Extensions
Analyzing Extension Lifecycle Telemetry