LS Retail Update Service Workspace

LS Retail Update Service Workspace brings you the power of Update Service to your workspace in Visual Studio Code.

With this extension, you can ...

Easily install Update Service packages from VS Code to support your development...
- Such as a new LS Central environment for AL Extension development.
Get update notifications.
Update your installed packages to the latest version.
Remove installed packages.
Add LS Update Service Workspace to your project with LS Update Service: Go!.
Create LS Update Service packages from within VS Code.
Create LS Update Service packages for your Business Central app.
Autogeneration of launch.json file.
Handful of AL Extension development helpers.

Install

You can find it and install from the VS Code Marketplace

Requirements

LS Update Service client must be installed on the machine.

Quick Start - Extend LS Central

Prerequisite:

New AL Project

Open VS Code.
Open View->Command Pallette... (Ctrl+Shift+P).
Select AL: Go! and select the location of your new AL project.

Add Update Service To Project

Open View->Command Pallette... (Ctrl+Shift+P).
Select LS Update Service: Go!.
- This will create an LS Update Service project file at PROJECT\.gocurrent\gocurrent.json.

Add LS Central as Dependency

Open app.json in the project root in VS Code.

Add LS Central app to the dependency list:

{
    "id":  "5ecfc871-5d82-43f1-9c54-59685e82318d",
    "publisher":  "LS Retail",
    "name":  "LS Central",
    "version":  "17.0.0.0"
}

Adjust the version for your needs.

Right-click on the .gocurrent\gocurrent.json file and select LS Update Service AL: Import dependencies from app.json.
- This will search for any missing dependencies from app.json and add them to your gocurrent.json file. In this case, the LS Central app is known and no further action is required. But for unknown app dependencies, you must set the appropriate package id for the new app id(s).

Install LS Central for Extension Development

Open View->Command Pallette... (Ctrl+Shift+P).
Select LS Update Service: Install Packages.
Select LS Central.
Type in an instance name or use the default (this will be the name of your service tier and database).
- A new window will open, the LS Update Service client, which will perform the installation.
LS Update Service install Wizard will appear, click through the wizard to install LS Central.
When the installation has finished, close the LS Update Service install window and a new entry for the new instance has been added to your launch.json file.

Compile and Publish Your Extension

Press F5 to compile and publish the extension to the new LS Central you installed...

Create LS Update Service App Package

Open View->Command Pallette... (Ctrl+Shift+P).
Select LS Update Service AL: Create Package.
You will be prompted to install LSPackageTools and LS Update Service Server if you don't have it already, install and re-run the LS Update Service AL: Create Package command.
- NOTE: We only need the PowerShell cmdlets from the LS Update Service Server installation in order to create the package, to skip creating a database, you can remove database name in the argument window.
A package will be created in the root of your project directory.
Import the package to your LS Update Service server

Install Packages

Prerequisite: LS Update Service Workspace must be added to your project beforehand.

Open View->Command Pallette... (Ctrl+Shift+P)
Select LS Update Service: Install packages.
From the drop-down, select the packages you want to install.
A LS Update Service dialog will appear, you might be presented with some arguments and additional components.
Click Install when ready.

AL Extension Development

If your project is an AL Extension project and you installed a new Business Central instance, your launch.json file is automatically updated with your installation.

Check for Updates

Open View->Command Pallette... (Ctrl+Shift+P)
Select LS Update Service: Check for Updates.
If any updates are available, a notification will appear in the right lower corner.
Click Update on any of the notification to start the update process.

Remove Packages

Open View->Command Pallette... (Ctrl+Shift+P)
Select LS Update Service: Uninstall Packages.
From the drop-down, select the installed packages you want to remove.

Create a Package

Open View->Command Pallette... (Ctrl+Shift+P)
Select LS Update Service: Create Package.
By default, the package will be created in your project directory.

Other Commands

Add Instances to Your Workspace
- Add other LS Update Service instances to your workspace.
Create Package
- Creates a LS Update Service package with values specified in gocurrent.json.
Open App
- Opens the LS Update Service app.

AL Specific Commands

If your VS Code workspace is an AL app project (Business Central app), a handful of helper function will activate:

Download Dependencies (.alpackages + .netpackages)
- Download the dependencies listed in gocurrent.json from a LS Update Service server into .alpackages and .netpackages. App packages will be downloaded into the .alpackages directory and DotNet addin packages into .netpackages.
Compile and Create Package
1. Downloads the dependencies necessary for compilation.
2. Compiles the app, against the dependencies listed in gocurrent.json.
3. Creates an app package.
Create Package
- Creates an app package from already existing app file in your project dir.
Re-Populate launch.json
- Adds all Business Central instances on your workspace to your launch.json file.
Start App Data Upgrade
- Runs data upgrade for all apps with pending data upgrade for the selected instance.
Unpublish App
- Unpublishes an app from a selected instance with app id from your app.json file.

The Project File (gocurrent.json)

Add LS Update Service Workspace to Your Project

Open your project with VS Code.
Open View->Command Pallette... (Ctrl+Shift+P)
Select LS Update Service: Go!.
- This will create a new LS Update Service project file in PROJECT.gocurrent\gocurrent.json.

Define Your Package

You can specify the necessary metadata to create a package from the project file (gocurrent.json). The project file supports the same properties as the cmdlet New-UssPackage, a few of them are:

Property	Description
`id`	Specify package ID.
`name`	Specify package version.
`version`	Specify package name
`displayName`	Specify a display name for particular version.
`commands`	Specify the commands the package implements, install, update, remove, rollback.
`instance`	`true` for instance package.
`parameters`	List of parameters the package accepts.
`files`	List of files to include in the package.
`dependencies`	A list of packages, your package depends on.

AL App Package

AL app packages only support a handful of the package properties: id, name, displayName and version.

AL App Dependencies

Your AL app package dependencies should reflect the dependencies in the project's app.json file. If you list custom apps as dependencies, you must also create packages for them. Either by using LS Update Service Workspace or utilizing LSPackageTools.

To simplify the process of listing the dependency packages, you can import the dependencies from app.json to your gocurrent.json file:

In VS Code, right-click on gocurrent.json in the Explorer (CTRL+SHIF+E), then select LS Update Service: Import dependencies from app.json.
- This will populate the dependency list in gocurrent.json with missing dependencies.
For any custom or unrecognized apps, listed with id = 'set-package-id-for-app-id', replace the ID with the appropriate package.

Development Packages

You can add a package or group of packages your developers require during development, such as Business Central, SQL Server and other similar components, which allows the developers to install the package from within VS Code.

For example, let's add ls-hardware-station to your project.

Open .gocurrent/gocurrent.json for editing.
Locate the devPackageGroups property or add it.

Add the ls-hardware-station package as following:

...
"devPackageGroups": [
    {
        "id": "29bbdc62-9934-469c-8e74-688b2732d93c",
        "name": "Hardware Station",
        "description": "This will install the latest development version of Hardware Station.",
        "packages": [
            {
                "id": "ls-hardware-station",
                "version": "!^"
            }
        ]
    }
]
...

The id must be unique or different from any other entries under devPackageGroups property. You can add more than one package to the packages list to include it in the same installation or add another entry under devPackageGroups for separate installation.

Now you can install the ls-hardware-station package with View->Command Pallette... (Ctrl+Shift+P)->LS Update Service: Install Packages->Hardware Station.

Development Packages Setup for Multiple Projects/Workspace Folders

You can manage the same development package groups for multiple projects, which can be handy for projects that require the same development components (i.e. Business Central, SQL server).

First decide in which project you want to maintain the development packages setup and add the packages you want to devPackageGroups, as described above.
For the other projects, add to or create a VS Code settings file PROJECT.vscode\settings.json: json { ... "ls-update-service-workspace.devPackageGroupWorkspaceDirs": [ "..\\relative\\path\\to\\main\\project" ] }

Now if you open any of the other projects, and run the command LS Update Service: Install Packages, you can install any package group from the main project.

Variables

Variables can be used in basic text and version properties:

...
"version": "${versionVariable}"
"description": "The description + ${variableName}",
"variables": {
    "variableName": "This is variable.",
    "versionVariable": "1.0.0"
},
...

Built-in Variables

There are a couple of built-in variables that can be used:

${currentBranch}: Current branch name.
${projectDir}: Directory path where the gocurrent.json file resides.
AL Extension specific variables:
- ${alAppId}: App ID from app.json.
- ${alAppName}: App name from app.json.
- ${alAppPublisher}: App publisher from app.json.
- ${alAppVersion}: App version from app.json
- ${alAppDescription}: App description from app.json.
- ${alAppProjectDir}: Directory dir where the app.json file resides.

Variable Declerations

Variables can be declared in different ways:

Pure text: json "variables": { "variableName": "Variable value" }

From a PowerShell script:

"variables": {
    "fromPs":{
        "id": "",
        "version": "",
        "resolverPath": "VersionResolver.psm1",
        "resolverFunction": "Resolve-Version"
    }
}

where VersionResolver.psm1 contains:

function Resolve-Version
{
    param(
        $Id,
        $Version,
        $Target
    )
    if ($Target -eq 'ReleaseCandidate')
    {
        return "1.0.0-rc"
    }
    else 
    {
        return "1.0.0"
    }
}

Branch Priority Filter

"variables": {
    "branchFilter": {
        "branchPriorityFilter": [
            "${currentBranch}",
            "master"
        ]
    }
}

If the current branch is feature/my-branch the value will be *-dev.branch.feature-my-branch >> *-dev.0.master.

From app.json dependencies:
```
"variables": {
    "lsCentralApp": {
        "alAppId": "5ecfc871-5d82-43f1-9c54-59685e82318d",
        "alAppIdParts": 3,
        "alAppIdType": "fromMinor"
    }
}
```
- If app.json has dependency to LS Central (app id 5ecfc871-5d82-43f1-9c54-59685e82318d) with minimum version 17.1.0.0, the value will be >=17.1.0.
- alAppIdParts can be 2,3 or 4, and specifies how many parts of the version will be included in the resulting value.
- alAppIdType can be:
  - version: The specified version value, i.e. 17.1.0.
  - fromMinor: The version value on the form: >=17.1.0.
  - fromMajor: The version value on the form: >=17.0.0.
  - fromMinorToNextMajor: The version value on the form: >=17.1.0 <18.0.
  - fromMajorToNextMajor: The version value on the form: >=17.0.0 <18.0.

Variable Functions

Variables can be manipulated with built-in functions:

Function	${variableName}	Result
${variableName:parts(3)}	1.0.0.0	1.0.0
${variableName:preReleaseLabel}	Foo Bar	Foo-Bar
${variableName:branchLabel}	feature/branch-name	dev.branch.feature-branch-name
${variableName:maxLength(3)}	AVeryLongText	AVe
${variableName:nextMajor}	1.2.3	2.0.0
${variableName:nextMinor}	1.2.3	1.3.0
${variableName:nextPatch}	1.2.3	1.2.4
${variableName:currentMajor}	1.2.3	1.0.0
${variableName:currentMinor}	1.2.3	1.2.0
${variableName:nextPreRelease}	1.2.0-rc.1	1.2.0-rc.2

Version Targets

You can create packages for different version targets, such as release, releaseCandidate, dev or your custom target.

Example:

"version": {
    "default": "1.0.0",
    "releaseCandidate": "1.0.0-rc",
    "dev": "1.0.0-${currentBranch:branchLabel}.${buildNumber}"
}

You must always define a default target as a catch all.

Frequently Asked Questions

Can I create a package with CI pipeline?

Yes, LSPackageTools contains tools you can include in your builds.

Can I use an existing instance (not installed through VS Code)?

You can add any LS Update Service instances to your workspace by:

Open View->Command Pallette... (Ctrl+Shift+P)
Select LS Update Service: Add Instance to Your Workspace
- A drop-down list of all LS Update Service instances will appear.
Select the instance you want to add to your workspace.

Which files should I add to source control?

You should add .gocurrent\gocurrent.json to source control but add .gocurrent\data.json to .gitignore.

(AL) My LS Central/Business Central instance is missing from launch.json

You can re-add all Business Central instances on your workspace to your launch.json file.

Open View->Command Pallette... (Ctrl+Shift+P)
Select LS Update Service AL: Re-populate launch.json
- This will only add missing Business Central instances.
- Any other entries will be left intact.

(AL) "The extension could not be deployed because it is already deployed as a global application or a per tenant application"

You will encounter this message if you install a Business Central instance with your app already installed the database and then you try to publish the same app from VS Code. To continue, you must unpublish the app:

Open View->Command Pallette... (Ctrl+Shift+P)
Select LS Update Service AL: Unpublish App
Select the instance from the drop-down to unpublish the app.
- This will unpublish the app with the app id from your app.json file.
- This will not remove any data.
Re-publish the app (F5)

(AL) "Error while publishing in VS Code: Cannot install the extension XXX for the tenant default because an earlier version was already installed. Run Start-NAVAppDataUpgrade to upgrade the extension"

When you publish an app with a newer version to your Business Central instance, you will encounter this message. You are required to run a data upgrade on your app to continue.

The LS Update Service Workspace extension provides a handy helper to do that from within VS Code:

Open View->Command Pallette... (Ctrl+Shift+P)
Select LS Update Service AL: Start App Data Upgrade
Select the instance from the drop-down to apply the data upgrade.
- A short process will start to run data upgrade for all apps necessary.
Re-publish the app (F5).

(AL) How to update launch.json for multiple AL apps in the same workspace?

Let's say you have two projects A and B in the same workspace or repository.

In A, define your development package group, with your Business Central setup.

For project B, create or add to the VS Code settings file Project-B.vscode\settings.json:

{
    ...
    "ls-update-service-workspace.devPackageGroupWorkspaceDirs": [
        "..\\Project-A"
    ]
}

Reload or restart VS Code.

Now you can:

Open A and B in the same workspace and when you install a new BC instance, launch.json is updated for both projects.
Only open B in VS Code, run LS Update Service: Install Packages and install any group defined in A.
Run Re-populate launch.json and launch.json is updated with instances from project A for A and/or B depending on which are open in VS Code.