ADI Employee Extension Manager

This codebase is a fork of Private Extension Manager along with PR #78.

ADI Employee Extension Manager lets you find, install, and update extensions from any NPM registry. This lets you distribute organization-specific extensions using a private registry server such as Sonatype Nexus, Verdaccio or GitHub.

Note: This extension is intended for ADI Employees only.

Managing Extensions

Select the ADI Employee Extensions icon on the activity bar.

This works similarly to Visual Studio Code's built-in extensions manager and allows you to install, update, and uninstall private extensions.

By default, the view will be empty. You will need to publish extensions to your private registry and tell the extension manager how to find the registry before you can use it.

Setup

Discovering Extensions

If you have not published any extensions, please refer to Publishing Extensions

Once your extensions are published to an NPM registry, you need to tell ADI Employee Extension Manager how to find them. This can be done using a workspace config file and/or a user config file.

If no registries are set up, or no extensions can be found in any registry, buttons will appear in the ADI Employee Extensions view. Clicking one of these buttons will open the associated config file for editing. Alternatively, you can use the following commands to edit the files. If these files do not exist, they will be created automatically.

Use Commands to Edit Config Files:

• Open the Command Palette:
  • macOS: ⌘+⇧+P
  • Windows / Linux: CTRL+⇧+P
• Search for and select one of the following commands:
  • ADI Employee Extensions: Configure Workspace Registries
  • ADI Employee Extensions: Configure Global / User Registries

Note: Remember to save configuration files after editing.

If you want to manually refresh the list of extensions, you can use the refresh (↻) button in the header of the extensions view.

Workspace Configuration

Note: You must have a folder / project open in Visual Studio Code to configure workspace registries as a file needs to be created in the projects .vscode folder.

The ADI Employee Extension Manager uses a config file similar to Visual Studio Code's extensions.json to allow workspaces to recommend extensions. This file defines your private extension registries and any recommended extensions.

There are two ways to create this file:

1. Manually:

• Create a file named .vscode/extensions.workspace.json in any workspace folder.

2. Using Commands:

• Open the Command Palette.
• Search for and select ADI Employee Extensions: Configure Recommended Extensions or ADI Employee Extensions: Configure Workspace Registries.
• These commands will create the config file from a template if it does not exist, and then open it.

The file has the following structure:

{
    "registries": [
        // Example of your private registry
        {
            "name": "My Private Registry",
            "registry": "https://my-private.registry",
        },
        // Example of a GitHub Registry Entry
        {
            "name": "My GitHub Registry",
            "registry": "https://npm.pkg.github.com",
            "org": "my-org",
            "filter": {
                "visibility": "internal",
                "keywords": [
                    "vscode-extension",
                    "my-amazing-extension"
                ]
            }
        }
    ],
    "recommendations": [
        "analogdevices.example-extension"
    ]
}

The registries array defines one or more NPM registries to search for private extensions. Each item supports the following fields:

• name: Name to display for the registry.
• registry: (Optional) The address of the NPM registry which contains the extension packages. If omitted, the registry is determined according to standard NPM config files.
• org: (Required if GitHub NPM Registry) The org / scope / username of the package. GitHub only supports scoped packages so this is required when searching for extensions. Example: @my-org/my-extension. Will accept @my-org or my-org.
• query: (Optional) Display only packages that match this search query. This is either an array of search terms or a string with space-delimited terms. For example, "keywords:group1 keywords:group2" would display only packages that have the either of the keywords group1 or group2. Note: this is not used for GitHub registries.
• filter: (Optional) Used to filter GitHub packages. The GitHub NPM Registry does not support searching so the GitHub Rest API, which also does not support search, is used to list packages. Adding a filter can speed up package retrieval.
• filter.visibility: (Optional) The selected visibility of the packages. Can be one of: public, private, internal
• filter.keywords: (Optional) String array of keywords to filter GitHub packages.
• enablePagination: (Optional) If true, keep requesting more package results from the registry until it gives an empty response. If false, make only one request. This defaults to true. Set it to false when using a server that doesn't properly handle the from parameter of the NPM search API. You may also need to increase limit to get all results if this is disabled.
• limit: (Optional) Number of results to limit each query to when requesting package results. Default: 100.
• Any options supported by npm-registry-fetch. Use these if you need to set authentication, a proxy, or other options.

The recommendations array is an optional list of private extensions from any of the registries which should be recommended for users of the workspace. The identifier of an extension is always "${publisher}.${name}". For example: "analogdevices.adi-employee-extension-manager".

You may have multiple workspace folders that contain an extensions.workspace.json file. The extension manager will display the registries and recommendations from all of them.

Note: if the query option is omitted, the query text will be a single asterisk. Some registry servers such as Verdaccio do not respond to this with all available packages, so you may need to set query to get any results at all.

User Configuration

Each user may also specify registries to use regardless of which workspace is open with the extensions.user.json config file located in {os.homedir()}/.adiEmployeeExtensions/. This has the same format as the registries array in extensions.workspace.json.

You can edit this file by using the ADI Employee Extensions: Configure Global / User Registries command. If the file does not exist, it will be created:

• Open the Command Palette.
• Search for and select ADI Employee Extensions: Configure Global / User Registries

Example of a user configuration file:

{
    "registries": {
        /* Same structure as workspace config */
    },
    "channels": {
        /* Detailed in next section */
    },
    "updateCheckInterval": 3600, // Detailed below
    "autoUpdate": false // Controls if extensions are automatically updated. Default: false
}

Custom Channels

It is possible to create tracking channels by using npm dist-tags when publishing a private extension. This lets you publish pre-release or other special versions of an extension without updating all users to them. Only users who are tracking the specific release channel will get the updates.

Tracking a Channel

To switch release channels for an extension, install the extension, then right-click it in the extensions list and select Switch Release Channels.... Alternatively, click the Channel button on the extension details page.

You can manually set channels in the extensions.user.json config file. This is a dictionary where each key is an extension identifier ("${publisher}.${name}") and each name is the dist-tag to track, as shown in the example below:

{
    "channels": {
        "analogdevices.example-1": "insiders", // Tracks the 'insiders' dist-tag
        "analogdevices.example-2": "beta",     // Tracks the 'beta' dist-tag
        "analogdevices.example-3": "1.0.0"     // Pins the extension to version 1.0.0
    }
}

You can also pin an extension to a specific version by listing the version instead of a dist-tag. ADI Employee Extension Manager will not notify you of updates to a pinned extension, so you can use this to temporarily ignore newer versions of an extension.

Publishing to a Channel

To publish an extension to a channel, simply specify the channel name using npm dist-tags when publishing. By default, all packages will reference the latest tag.

npm publish . --tag=insiders

When publishing pre-release versions, it is recommended to use pre-release sematic versioning, such as 1.0.0-beta.0.

Publishing Extensions

To allow ADI Employee Extension Manager to find your extension, package it in the VSIX format using vsce, create an NPM package containing the .vsix file, and publish it to an NPM registry. Your extension's package.json must contain a files array with the path to the .vsix file so the extension manager knows what to install. Use vsce package in a prepublishOnly script to ensure that your NPM packages always contain an up-to-date extension package.

Note that when ADI Employee Extension Manager displays the details for an extension, it will unpack the latest version of the NPM package to read its README and CHANGELOG files, but it will not unpack the .vsix file. If your extension has an icon, ensure that it is either accessible via HTTPS or included directly in your NPM package by referencing it in the package.json's files array.

Visual Studio Code does not support scoped extension names such as @my-org/my-extension. It is recommended that you create a registry that only contains Visual Studio Code extensions to avoid name collisions. If you need to publish to a registry that contains packages that are not Visual Studio Code extensions, add a keywords field to your package.json and tag all your extensions with the same keyword so you can filter to just extensions, or ensure that all non-extension packages are scoped.

Use publishConfig to set the registry to which the extension should be published. You may also need to authenticate with this registry using npm login --registry=<url>. Use npm publish . to publish your extension (not vsce publish, as that publishes to the public extensions gallery).

Your package.json should look like a regular extension manifest but with extra files and publishConfig fields and a prepublishOnly script to handle the NPM-specific behavior:

{
    "name": "example-extension",
    "displayName": "Example Extension",
    "description": "This is an example extension.",
    "version": "1.2.3",
    "author": {
        "name": "John Doe",
        "email": "John.Doe@analog.com"
    },
    "publisher": "analogdevices",
    "engines": {
        "vscode": "^1.40.0"
    },
    "icon": "media/icon.png",
    "files": [
        "extension.vsix",
        "media/icon.png"
    ],
    "publishConfig": {
        "registry": "https://my-private.registry"
    },
    "scripts": {
        "prepublishOnly": "vsce package -o extension.vsix",
        ...
    },
    "devDependencies": {
        "vsce": "^1.75.0",
        ...
    }
    ...
}

Note: prepare scripts will not be run before installing the extension. If you have native dependencies, instead of using node-gyp to build them on the user's machine, you should build them yourself for each supported platform and include them in the .vsix or host them on a server and have your extension download them at runtime.

OS specific Extensions

By default, the first .vsix file in the files array is used. If you have different native dependencies for each platform, you can use osSpecificVsix to choose a .vsix file by the operating system and architecture.

Ensure the target is specified in the following format {os-platform}-{os-architecture}.

    ...
    "osSpecificVsix": {
        "linux-x64": "extension-linux-x64.vsix",
        "win32-arm": "extension-win32-arm.vsix",
        "default": "extension-default.vsix",
    },
    ...

The package must include all files listed. default (optional) is used to select a file in case none of the explicit keys matches; otherwise an error is shown on unsupported platforms.

Note: GitHub packages strips osSpecificVsix from the package manifest so the Extension Manager will look in files for OS specific VSIX files.

Extension Updates

ADI Employee Extension Manager will periodically check your installed extensions for updates and notify you if any are found. You can adjust the check interval or disable it by adding a updateCheckInterval setting to the extensions.user.json config file.

{
    "updateCheckInterval": 3600, // 60 minutes
    "updateCheckInterval": 0     // Disable checks by setting to 0
}

The ADI Employee Extensions sidebar panel will also indicate any extensions with new versions with a green arrow. Clicking it will update the extension.

You will typically need to reload the Visual Studio Code window for an update to take effect.

Remote Development

When using a remote development extension such as Remote-SSH, install the ADI Employee Extension Manager: Remote Helper extension to give ADI Employee Extension Manager access to the local machine.

ADI Employee Extension Manager will attempt to infer where VS Code will install an extension. If it shows "Install Locally" for a workspace extension or vice versa, set the extensionKind property in your extension's package.json to tell both VS Code and Private Extension Manager where the extension should be installed.

Troubleshooting

If you are successfully connecting to a private NPM registry and don't see any errors, but you don't see any extensions either, first open the Output panel (Ctrl+Shift+U) and check the dropdown list for "ADI Employee Extension Manager". If it is present, it may contain information as to why extension packages are being discarded.

If packages aren't being discarded, they may not be found to begin with. If you do not specify a query or other options in your registry configuration, the default search query is:

{registry-url}/-/v1/search?text=*&size=20&from=0

Check how your registry server responds to this. Some servers such as Verdaccio do not respond to text=* with a list of all packages, so you may need to change the query option for your registry (see the Workspace Configuration) section above.

Privacy Statement

When communicating with the private extension servers you have configured, the extension will not transmit any data beyond what is necessary to establish the connection. The extension will not transmit any data back to Analog Devices.

Third Party Licenses

Third party licenses can be found here: https://download.analog.com/EMPEXTMGR/versions.html.