Creating an Extension Package in Dynamics NAV
Note
Extensions v1.0 are no longer supported. The text in the article applies to extensions v1.0. For information about writing extensions in AL, see the table below.
| For information about | See |
|---|---|
| Getting started writing extensions using the AL Language. | Getting Started |
| Converting extensions. | Converting Extensions V1 to Extensions V2 |
| Writing extension install code for when an extension is installed for the first time, or for when an uninstalled extension is reinstalled. | Writing Extension Install Code |
| Making a newer version of an extension available. | Upgrading Extensions V2 |
| Publishing, synchronizing, and installing the extension on the tenant. | Publishing and Installing an Extension v2.0 |
When you have developed a Dynamics NAV extension, the next step is to wrap your new .TXT and .DELTA files into a .NAVX file, the packaging format for extensions. The package includes the application objects and metadata that describes your extension, such as name and version.
To create the extension manifest
The extension manifest describes characteristics about your extension. All characteristics have a parameter in the Windows PowerShell cmdlet that you use to create the manifest. The following table describes the data in the manifest:
| Data | Description |
|---|---|
| Name | Specifies the name of the extension. |
| Publisher | Specifies the publisher of the extension, such as your company name. |
| Version | Specifies the version of the extension. The version is a string in the format of Major.Minor.Build.Revision, with a default value of 1.0.0.0. You must increment the value for each new version of the extension that you publish. |
| Description | Specifies the description for the extension. |
| Id | Specifies the unique identifier for the extension. A unique identifier will be generated if a value is not provided. The same unique identifier should be used for each new version of the extension. |
| Brief | Specifies a brief description for the extension. |
| PrivacyStatement | Specifies a hyperlink to the extension’s Privacy Statement. |
| Eula | Specifies a hyperlink to the End User License Agreement for your extension. |
| Url | Specifies a hyperlink to a page or web site with additional information about the extension. |
| Help | Specifies a hyperlink to the site where you have published Help for the extension. |
| CompatibilityId | Specifies the compatibility ID of the extension. The compatibility ID is a version string in the format of Major.Minor.Build.Revision, with a default value of 1.0.0.0. The value is used to indicate whether there are compatibility related code changes between different versions of the extension. If a new version of the extension does not break compatibility, leave the compatibility ID the same as the previous version. |
| Dependencies | Specifies the path to a package file (.navx) for another extension that this extension depends on. Use a comma (,) to separate the paths to multiple .navx files., such as in the following example: C:\Proseware\SmartAppBase.navx, C:\Proseware\ProsewareBase.navx |
| Prerequisites | Specifies the objects that must exist in order to deploy the extension to a Microsoft Dynamics NAV Server instance. The prerequisites is a string in the format of type=ID, where type can be any object type such as Table, CodeUnit, or Page. Use a comma (,) to separate the prerequisites, such as in the following example: Table=397, CodeUnit=78. |
For more information, see Manifest Overview.
The New-NAVAppManifest cmdlet creates an in-memory Manifest object.
New-NAVAppManifest -Name "Proseware SmartStuff" -Publisher "Proseware, Inc." -Version "1.5.0.12"
You can either persist this object to a file and then check it in to source control by using New-NAVAppManifestFile, or you can pass it directly to Windows PowerShell New-NAVAppPackage as described in the next step.
New-NAVAppManifest -Name "Proseware SmartStuff" -Publisher "Proseware, Inc." -Version "1.5.0.12" | New-NavAppManifestFile -Path proseware.xml
Related cmdlets are Get-NAVAppManifest and Set-NAVAppManifest. For more information, use the Get-Help command in the Microsoft Dynamics NAV Development Shell.
Tip
For any Windows PowerShell cmdlet, you can get help and sample usages, such as the following command: Get-Help Set-NAVAppManifest -Examples
Next, you can choose to include permission sets and other data in your package. This is optional, but at a minimum, an extension must include one permission set that grants permission to use the objects contained in the extension. An administrator must map users this permission set ID once it has been imported. For more information, see How to: Export Data for an Extension Package.
Important
If you do not include a permission set with your extension, only users with the SUPER permission set will be able to use the extension.
Once you have the DELTA and TXT files and .NET Interop add-ins for your app created you can now complete the final step and build the extension package file. Extension packages require a manifest and access to the application objects that you created.
To build the extension package
Use the New-NAVAppManifest and New-NAVAppPackage cmdlets to build the manifest and package file.
The following is an example of how to create a new extension .NAVX package file with a new manifest.
New-NAVAppManifest -Name "Proseware SmartStuff" -Publisher "Proseware, Inc." -Version "1.5.0.12" | New-NAVAppPackage -Path MyExtension.navx -SourcePath DELTA
Alternatively, if you created a manifest file, you can use directly from that file:
Get-NAVAppManifest -Path '.\Manifest-Proseware SmartStuff.xml' | New-NAVAppPackage -Path MyExtension.navx -SourcePath DELTA
You have packaged your extension so it is ready to be published and installed on a target server.
Note
The packaging process adds a description of the extension to the manifest, such as whether it changes pages or adds tables. While not explicitly being enforced currently, this can be used to determine whether to install an extension, or not. Use Get-NAVAppManifest –Path to see capabilities.
Finally, you can choose to get your extension package signed to help validate its authenticity.
Signing a NAVx File
Code signing is a common practice for many applications. For more information, see Authenticode in the MSDN Library. The signing must be performed on a computer that has Microsoft Dynamics NAV 2016 or later installed. You must have a certificate on the computer (as a file or in the certificate store) that includes code signing for the intended purpose. It is recommended that you use a certificate from a third party certificate authority. For testing purposes, it is acceptable to create a self-signed certificate using the New-SelfSignedCertificate cmdlet in PowerShell on Windows 10 or MakeCert.
The following example illustrates how to create a new self-signed certificate for code signing:
New-SelfSignedCertificate –Type CodeSigningCert –Subject “CN=ProsewareTest”
Example MakeCert command to create a new self-signed certificate for code signing:
Makecert –sk myNewKey –n “CN=Prosewaretest” –r –ss my
Optionally, but recommended, use a time stamp when signing the NAVx file. A time stamp allows the NAVx signature to be verifiable even after the certificate used for the signature has expired. For more information, see Time Stamping Authenticode Signatures.
Use a signing tool such as SignTool or CodeSign to sign the NAVx file.
The following example signs the Proseware.navx file using the certificate in the password-protected MyCert.pfx file.
SignTool sign /f MyCert.pfx /p MyPassword “C:\NAV\Proseware.navx”
The following example signs the Proseware.navx file with a time stamp using the certificate in the password-protected MyCert.pfx file.
SignTool sign /f MyCert.pfx /p MyPassword /t https://timestamp.verisign.com/scripts/timestamp.dll “C:\NAV\Proseware.navx”
The following example signs the Proseware.navx file using the certificate in the My store with a subject name of “Prosewaretest”.
SignTool sign /n Prosewaretest “C:\NAV\Extension\Proseware.navx”
Note
If you want to publish an unsigned extension package, you need explicitly state that by using the –SkipVerification parameter on the Publish-NAVApp cmdlet.