Overview of Building and Packaging the Extensions

Locally

In the end all the extensions in this repo are packaged using the tfx client. A PowerShell script in the root of the repo is provided to do this locally. It builds all packages in the repo.

However, this way of working is rarely used as it does not version stamp the extensions VSIX files and contained tasks. Version stamping is important as the Microsoft VSTS Marketplace (and local TFS server galleries) will only allow the updating of an extension if it has a higher version number than any previously installed.

As most of the extensions are Powershell based, tfx is enough to complete the package process. However, there is an increasing number of Typescript/Node.JS based cross platform tasks in extensions. These have to be 'pre-built' using NPM to transpile the Typescript to Node.JS prior to packaging.

Formal Release to the Marketplace (CI/CD)

The more common way of working is to use a VSTS CI/CD pipeline to build and package the extension, after any local testing that is possible. This handles automated version stamping, unit testing and releases to the VSTS marketplace both initially as private release to limited VSTS instances for manual and automated functional testing then, if all is OK, as a publicly accessible extensions.

Note that A private VSTS based Repo is used as part of my CI/CD process that contains some functional tests and related source to generate test data. If there is any demand I might move this to GitHub, but I don't see the need at present.

Local Builds and Packaging Process

If the extension has PowerShell based tasks

If packaging any extensions that contains PowerShell based tasks no special pre-processing is required. However, if there may be test that you wish to run. This is done as follows

1. CD into the tasks test folder
2. To run the tests
   • All tests run invoke-pester
   • To run a single test file run invoke-pester thefile.tests.ps1

If the extension has Node.JS based tasks

If packaging any extensions that contains cross platform tasks then an NPM build process must be used first to handle the transpile of the TypeScript into Node.JS. The process is as follows

1. CD into the the extension folder you wish to build (this contains the package.json file)
2. Get all the NPM packages npm install as defined in the package.json
3. Run TSLint and transpile the TypeScript to Node.JS. There is a single command npm run build to do this, but they can be rerun individually npm run lint and npm run transpile
4. Run any unit tests you have npm run test-no-logging (Note the npm run test script is used by the CI/CD process to dump the test results for uploading to VSTS logging. I tend to find when working locally that just dumping the test results to the console is enough.
5. Package the the resultant .JS files npm run package. This script does two jobs, it remove any NPM modules that are set as -savedev i.e. only used in development and not production and also copies the required files to the correct locations to be packaged into a VSIX file. NOTE after this command is run you need to rerun npm install to reinstall the development NPM packages prior to be able to run tests etc. locally

To achieve all of this the package.json contains the following script definitions

"scripts": {
    "build": "npm run clean && npm run lint && npm run transpile ",
    "package": "npm prune -production && npm run copy",
    "copy": "ncp ./node_modules ./task/node_modules && ncp ./dist/src ./task",
    "clean": "rimraf ./dist/src && rimraf ./dist/test && rimraf ./task/*.js && rimraf ./task/*.js.map && rimraf ./task/node_modules",
    "transpile": "tsc -p ./",
    "lint": "tslint -c tslint.json src/*.ts test/*.ts",
    "test": "mocha -r ts-node/register ./test/*.ts --reporter mocha-junit-reporter --reporter-options mochaFile=./test-output/test-results.xml ",
    "test-no-logger": "mocha -r ts-node/register ./test/*.ts "
}

All types of extensions

The package.ps1 script in the extension folder builds the VSIX using PowerShell. REMEMBER if your extension has Typescript based tasks you need to follow the process outline above first for each task in turn to convert Typescript to Node.JS.

If using this PowerShell script for anything other than proving the VSIX is created you will need to update the extension and task manifest files manually, or with your own script, to provide suitable version numbers prior to packaging.