Object Package

In this step, we will create a package with your objects, a FOB file with your objects, and any modification to NAV or LS Central objects. During the package installation or update the FOB file is imported into your connected database and the table schema is synced.

Example:

$ErrorActionPreference = 'stop'

Import-Module LSPackageTools\ObjectPackageCreator
Import-Module UpdateServiceServer

$Arguments = @{
    Id = 'my-objects'
    Name = 'My Objects'
    Version = '1.0.0'
    Path = 'c:\MyGoCPackages\objects\my-objects.fob'
    ForceDestructiveChanges = $true # If there are any destructive schema changes, they are forced.
    Dependencies = @(
        @{ Id = 'bc-server'; Version = "=14.0.35916.0"}
    )
    SkipValidation = $true
    OutputDir = 'c:\MyGoCPackages\Output'
}
New-ObjectPackage @Arguments | Import-UssPackage

The specific parameters for this cmdlet are:

  • Id, Name, Version and OutputDir are common package parameters.
  • Path: Specify the path to your FOB file to include in the package. The FOB file should contain all the objects you intend to have in your database and they should be compiled if they should be operational, as Update Service will not attempt to compile them at any point.
  • Dependencies: Specifies dependencies required by the objects.
    • You should at least add a dependency to bc-server package,
    • If the objects depend on DotNet add-ins, you should create packages for those and list as dependencies.
  • SkipValidation: By default, the cmdlet validates that bc-server is listed in the dependencies. This requires to check with the server

Export Objects to FOB Using LSPackageTools

You can export the FOB file with Export-ObjectsForPackage found in the LSPackageTools\ObjectsPackageCreator PS module.

$ErrorActionPreference = 'stop'
Import-Module LSPackageTools\ObjectPackageCreator

$Arguments = @{
    OutputFobPath = 'c:\MyGoCPackages\objects\my-objects.fob'
    InstanceName = 'BcInstance'
}

Export-ObjectsForPackage @Arguments

The specific parameters for this cmdlet are:

  • OutputFobPath: Specify a path to save the FOB file.
  • InstanceName: Specify an Update Service instance name that has Business Central installed (bc-server package to be specific).
  • Filter: (Optional) Specify a Version List filter to select specific objects in the database.

This will use the Business Central service tier (bc-server) to export all (or by the filter) objects to a FOB file.

Apps and C/AL Objects (LS Central 14.XX and older)

Note

This section only applies to LS Central 14.02 or older with app/extension support.

When using apps in 14.0 and earlier versions, you must also use objects and application symbols. The application symbols are an app that acts as an interface to your objects and, it's important that the symbols reflect the objects.

First, you need to create a package for your objects, as described on the objects package page. Then you should have a package called my-objects, which we utilize in the example below.

Here is an example of how you can create packages for your symbols and app:

$ErrorActionPreference = 'stop'

Import-Module LsPackageTools\AppPackageCreator
Import-Module UpdateServiceServer

$Package = @{
    Id = 'my-application-symbols'
    Name = 'My Symbols'
    Version = '1.0.0'
    Path = 'c:\path\to\symbols.app'
    OutputDir = 'c:\MyGoCPackages\Output'
    SymbolsOnly = $true
    Dependencies = @(
        @{ Id = 'my-objects'; Version = "=1.0.0" }
    )
}

New-AppPackage @Package | Import-UssPackage

$Package = @{
    Id = 'my-app'
    Name = 'My App'
    Version = '1.0.0'
    Path = 'c:\path\to\extension.app'
    OutputDir = 'c:\MyGoCPackages\Output'
    Dependencies = @(
        @{ Id = 'my-application-symbols'; Version = ">=1.0.0" }
    )
}

New-AppPackage @Package | Import-UssPackage

The example will create two packages called my-app and my-application-symbols, from app files, you must provide beforehand. You must also make sure the dependencies are correctly set up, this example has the following hierarchy: my-app -> my-application-symbols -> my-objects -> bc-server.

We recommend creating both symbols and objects packages at the same time, with the same version number to make sure they stay in sync:

Warning

If you install a different symbols package that does not reflect the objects in your database, you risk getting an installation or runtime errors.

$ErrorActionPreference = 'stop'

Import-Module LsPackageTools\ObjectsPackageCreator
Import-Module LsPackageTools\AppPackageCreator
Import-Module UpdateServiceServer

$ObjectsVersion = '1.0.0'

# Create objects package from path:
$Package = @{
    Id = "my-objects"
    Name = "My Objects"
    Version = $ObjectsVersion
    FobPath = 'c:\path\to\objects.fob'
    ForceDestructiveChanges = $true # If there are any destructive schema changes, they are forced.
    Dependencies = @(
        @{ Id = 'bc-server'; Version = "=14.0.35916.0"}
    )
    SkipValidation = $true
    OutputDir = 'c:\MyGoCPackages\Output'
}

New-ObjectPackage @Package | Import-UssPackage

# Create symbols package from path:
$Package = @{
    Id = 'my-application-symbols'
    Name = 'My Symbols'
    Version = $ObjectsVersion
    Path = 'c:\path\to\symbols.app'
    OutputDir = 'c:\MyGoCPackages\Output'
    SymbolsOnly = $true
    Dependencies = @(
        @{ Id = 'my-objects'; Version = $ObjectsVersion }
    )
}

New-AppPackage @Package | Import-UssPackage

# Create app package from path:
$Package = @{
    Id = 'my-app'
    Name = 'My App'
    Version = '1.0.0'
    Path = 'c:\path\to\extension.app'
    OutputDir = 'c:\MyGoCPackages\Output'
    Dependencies = @(
        @{ Id = 'my-application-symbols'; Version = ">=1.0.0" }
    )
}

New-AppPackage @Package | Import-UssPackage

This example will create all three packages, my-app, my-application-symbols and, my-objects. Notice how we use the variable $ObjectsVersion to keep the symbols and objects packages version in sync.

We can automate this even further by connecting to a database to generate and export symbols and objects instead of relying on provided files. In the LsPackageTools we have two helper cmdlets, Export-ApplicationSymbols to generate and export a symbols app and Export-ObjectsForPackage to export objects from a database. See the full example on Github

Next Steps

Common Questions

C/AL and Apps: How to generate and create symbols app?

First, you need to generate the symbols in the Business Central database: https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-running-cside-and-al-side-by-side

Second, you need to download the symbols app with the AL language extension in VS Code. In short:

  1. Setup VS Code with AL Language extension.
  2. Open VS Code on an AL app project (you can create a new project with AL: Go!)
  3. Edit launch.json with connection parameters to your service-tier/NST containing your objects.
  4. Then run CTRL+SHIFT+P -> AL: Download Symbols and the symbols app will download into .alpackage directory.

You can also download the symbols from a browser:

http[s]://localhost:DEV-PORT/INSTANCENAME/dev/packages?publisher=Microsoft&appName=Application&versionText=MAJOR-VERSION.0.0.0

i.e.

http://localhost:9048/MyInstance/dev/packages?publisher=Microsoft&appName=Application&versionText=14.0.0.0

C/AL and Apps: Can I use bc-system-symbols instead of creating my own symbols app package?

You can only use the bc-system-symbols if you only have standard Business Central objects and they have not been modified.

You can think of symbol packages as an interface to the objects in the database which your apps can interact with. If the objects are modified or you add new objects, you need to generate new symbols (interface) in order to expose the correct API to the apps.