How to: Create an Extension Package

Article
04/14/2016

When you have developed a Microsoft 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, New-NAVAppManifest. 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.
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 Extending Microsoft Dynamics NAV Using Extension PackagesManifest 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 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 and . For more information, use the Get-Help command in the Microsoft Dynamics NAV 2016 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 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.

To retrieve permission sets for the extension

Use the cmdlet to export any permission sets that you have created for the extension as shown in the following example.
```
Export-NAVAppPermissionSet -ServerInstance DynamicsNAVServer -Path ProsewarePerm.xml -PermissionSetId 12
```
Warning

If you do not include a permission set with your extension, only users with the SUPER permission set will be able to use the app.

Once you have the DELTA and TXT files 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 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 on how to create a new extension package file (.navx) 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 NAV App 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 sign an extension package

To help validate the authenticity of an extension package (the .navx file), we recommend that you have it signed. Code signing is a common practice for many applications. For more information about code signing, see Authenticode and Introduction to Code Signing in the MSDN Library.

To sign an extension package, you need a computer that has the following:
1. A code signing tool, such as SignTool or CodeSign.
  
  SignTool is part of the Windows Software Development Toolkit. For more information, see SignTool.
2. Microsoft Dynamics NAV 2016 or later.
Obtain a certificate that is enabled for the code signing purpose. You can have certificate as a file or installed in the certificate store of the computer.

In production, we recommend that you use a certificate from a third party certificate authority. However, for testing purposes, it is acceptable to create a self-signed certificate, which, for example, you can create by using the New-SelfSignedCertificate cmdlet in Windows PowerShell or MakeCert.

The following example uses the New-SelfSignedCertificate cmdlet to create a new self-signed certificate:
```
New-SelfSignedCertificate –Type CodeSigningCert –Subject “CN=ProsewareTest”
```
The following example uses the MakeCert tool to create a new self-signed certificate:
```
makecert –sk myNewKey –n “CN=Prosewaretest” –r –ss my
```
It is optional but we recommend that you use a time stamp when signing the .navx file.

A time stamp allows the .navx file signature to be verifiable even after the certificate that is used for the signature has expired. For more information, see Time Stamping Authenticode Signatures.
Sign the .navx file by using your signing tool.

See the following examples for signing by using SignTool.

Example

The following example signs the Proseware.navx file with 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 the certificate in the password-protected MyCert.pfx file and a time stamp.

SignTool sign /f MyCert.pfx /p MyPassword /t http://timestamp.verisign.com/scripts/timestamp.dll "C:\NAV\Proseware.navx"

The following example signs the Proseware.navx file with the certificate in the store called My with a subject name of Prosewaretest.

SignTool sign /n Prosewaretest "C:\NAV\Extension\Proseware.navx"

How to: Create an Extension Package

To create the extension manifest

To retrieve permission sets for the extension

To build the extension package

To sign an extension package

Example

See Also

Tasks

Concepts

Other Resources

Additional resources