CAST Extend - CAST AIP extension ecosystem
Page tree

Versions Compared

Old Version 50

changes.mady.by.user James Hurrell

Saved on

compared with

New Version 66

changes.mady.by.user James Hurrell

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

CAST Extend local server and CAST Extend Offline (in v. ≥ 1.1.0) and  is are delivered "empty" without any preconfigured extensions - you will therefore need to populate them with extensions before you can use them. In addition, you may want to update CAST Extend local server/Offline to add new extensions or to include more recent releases of extensions.

An interface exists in CAST Extend (the live version available at https://extend.castsoftware.com) to create a new "bundle" containing the extensions you require, however, this interface only allows official CAST AIP extensions (known as "product" extensions) to be included. As a result, the ExtendCli tool has been developed to allow the integration of User Community and Labs extensions, as well as Product extensions (see Contributor types for more information about the types of extensions that are available) into CAST Extend local server/Offline.

Info

What's new

See ExtendCli - Release Notes for more information.

Prerequisites

To use ExtendCli, the following is required:

Supported Operating Systems

...

The ExtendCli tool is designed to perform this job and will allow the integration of the following (see Contributor types for more information about the types of extensions that are available):

  • Official Product extensions
  • User Community and Labs extensions
Info
  • ExtendCli does not replace CAST Extension Downloader - a tool used to download Extensions from CAST Extend (live or offline).
  • All dependent extensions of a given extension will be included when using ExtendCli.

What's new

See ExtendCli - Release Notes for more information.

Prerequisites

To use ExtendCli, the following is required:

Supported Operating Systems

Operating SystemSupportedSupported by reference
Microsoft Windows 8 64-bit
(tick)
Microsoft Windows 8.1 64-bit(tick)
Microsoft Windows 10 64-bit(tick)
Microsoft Windows Server 2008 R2 SP1 64-bit (Standard edition)
(tick)
Microsoft Windows Server 2012 64-bit (Standard edition)
(tick)
Microsoft Windows Server 2012 R2 64-bit (Standard edition)
(tick)
Microsoft Windows Server 2012 64-bit (Standard edition)(tick)Microsoft Windows Server 2012 R2 64-bit (Standard edition)(tick)Microsoft Windows Server 2016(tick)2016(tick)

Using ExtendCli

ExtendCli is provided as an executable (ExtendCli.exe) and must be used in command line mode. To do so, either:

...

Option

Description

Command line

Comment

Example of command line

set

Setup the CAST Extend (online) connection parameters.

ExtendCli.exe config set <api-key>

<api-key> is specific to a login for CAST Extend (online). You can find this in your profile.


Info
Note that this command only needs to be used once (unless you decide to use a different api-key for an alternative CAST Extend (online) login).


extendCli.exe config set api-key w9876xyz-d999-32ii-9fb0-0123cde45

ExtendCli.exe config set [extend-url]

[extend-url] is optional. It refers to the URL to use for CAST Extend (online). When no option is provided, the default value is used: https://extend.castsoftware.com.

Info
Note that this command only needs to be used once (unless you decide to use a different URL).


extendCli.exe config set extend-url "your URL"

download

This option allows you to download an extension in .nupkg format:

ExtendCli.exe

...

config set [

...

proxy]

...

Option

Description

Command line

Example of command line

-d | --skip-dependenciesThis option allows you to download an extension without any dependencies. CAST only recommends using this option if you understand the implication - an extension will not function correctly without its dependencies.

ExtendCli.exe download -d <extension id>

ExtendCli.exe download --skip-dependencies <extension id>

ExtendCli.exe download -d com.castsoftware.reactjs
-s | --latest-stable <true|false>This option allows you to configure whether to download the most recent stable release of an extension (-LTS or funcrel).  The default behaviour (i.e. when the option is omitted) the action is set to true and the latest-stable release will be downloaded. Explicitly add the option and set it to false to ensure that the latest stable release is not downloaded.

ExtendCli.exe download -s false <extension id>

ExtendCli.exe download --latest-stable false <extension id>

ExtendCli.exe download -s false com.castsoftware.reactjs
-a | --absolute-latest

[proxy] is optional. It should be used:

  • when your network environment uses a proxy for internet access.
  • when the machine you are running ExtendCli on does not have operating system level proxy settings enabled.

The syntax is as follows:

Code Block
ExtendCli.exe config set proxy <protocol://[user:password@]host[:port]>]

Note that if you are using the Use setup script option (1), CAST also recommends enabling the Automatically detect settings option (2):

Image Added

extendCli.exe config set proxy http://proxy_user:proxy_password@proxy.corp.com:8080

download

This option allows you to download

...

an extension in .nupkg format:

ExtendCli.exe

...

ExtendCli.exe download --absolute-latest <extension id>

...

download [options] <extension id>

the most recent funcrel release of an extension and all f <extension download latestfuncrel f coml lts LTS extension and all dependencies.l download lts l

Option

Description

Command line

Example of command line

-d | --skip-dependenciesThis option allows you to download an extension without any dependencies. CAST only recommends using this option if you understand the implication - an extension will not function correctly without its dependencies.

ExtendCli.exe download -

d <extension id>

ExtendCli.exe

download --

skip-

dependencies <extension id>

ExtendCli.exe download -d com.castsoftware.reactjs
-s | --latest-stable <true|false>This option allows you to configure whether to download the most recent stable release of an extension (-LTS or funcrel).  The default behaviour (i.e. when the option is omitted) the action is set to true and the latest-stable release will be downloaded. Explicitly add the option and set it to false to ensure that the latest stable release is not downloaded.

ExtendCli.exe download -

s false <extension id>

ExtendCli.exe

download --latest-

stable false <extension id>

ExtendCli.exe download -s false com.castsoftware.reactjs
-v a | --absolute-versionlatestThis option allows you to download a specific the most recent release of an extension and extension including alpha and beta releases and all dependencies.

ExtendCli.exe download -v <release><extension a <extension id>

ExtendCli.exe download --version <release><extension absolute-latest <extension id>

ExtendCli.exe download -v 1.1.4-funcrel a com.castsoftware.reactjs

...

-f | --latest-funcrelThis option allows you to download

...

<extensionId>

[--version <version>]

[--ignore-dependencies]

[--username <username>]

[--password <password>]

Use this option to specify an extension that you want to download on to your local machine. Note that you may also need to specify the --username and --password options if the remote server requires authentication

<extensionId> specify a particular extension for download using its ID - this is a mandatory option. The ID of a CAST AIP extension always takes the form com.castsoftware.<name>, without any version numbers. Note that the most recent versions of an extension's dependencies will always be downloaded alongside the extension, unless you are using the [--ignore-dependencies] option - see below.
This option allows you to specify a specific version of the extension for download using its version number. This option is not mandatory. When not included, the most recent version of the extension you require will always be downloaded.
install

Option

Description

the most recent funcrel release of an extension and all dependencies.

ExtendCli.exe download -f <extension id>

ExtendCli.exe download --latest-funcrel <extension id>

ExtendCli.exe download -f com.castsoftware.reactjs
-l | --latest-ltsThis option allows you to download the most recent LTS release of an extension and all dependencies.

ExtendCli.exe download -l <extension id>

ExtendCli.exe download --latest-lts <extension id>

ExtendCli.exe download -l com.castsoftware.reactjs
-v | --versionThis option allows you to [--version <version>]download a specific release of an extension and all dependencies.

ExtendCli.exe download -v <release><extension id>

ExtendCli.exe download --version <release><extension id>

ExtendCli.exe download -v 1.1.4-funcrel com.castsoftware.reactjs

install

This option allows you to download an extension from CAST Extend and store it on the local machine in %PROGRAMDATA%\CAST\CAST\Extensions (or an alternative location if you have modified the CAST_PLUGINS_ROOT_PATH option in the CastGlobalSettings.ini file):

install
uninstall

<extensionId>

[--version <version>]

[--ignore-dependencies]

This option allows you to download an extension without any dependencies. CAST only recommends using this option if you understand the implication - an extension will not function correctly without its dependencies.
This option is not mandatory. When not included, the most recent versions of an extension's dependencies will always be downloaded.

[--username <username>]

[--password <password>]

When connecting to a server that requires authentication (for example https://extend.castsoftware.com:443/api) to download an extension (with the install option), use these two options to specify your credentials. You will require an account on the remote server to authenticate when using CAST Extend. You can find out about registering for an account in CAST Extend website.

uninstall

extensionId[--username <username>]

[--password <password>]


Use this option to specify an extension that you want to download on to your local machine. Note that you may also need to specify the --username and --password options if the remote server requires authentication

Option

Description

<extensionId>

This option allows you to specify a particular extension for download using its ID - this is a mandatory option. The ID of a CAST AIP extension always takes the form com.castsoftware.<name>, without any version numbers. Note that the most recent versions of an extension's dependencies will always be downloaded alongside the extension, unless you are using the [--ignore-dependencies] option - see below.

[--version <version>]
Use this

This option allows you to specify

an extension that you have downloaded to your machine and that you now want to remove from your machine:

Option

Description

extensionId

a specific version of the extension for download using its version number. This option is not mandatory. When not included, the most recent version of the extension you require will always be downloaded.

[--ignore-dependencies]

This option allows you to

specify a particular extension for removal using its ID - this is a mandatory option. The ID of a CAST AIP extension always takes the form com.castsoftware.<name>, without any version numbers.
[--version <version>]

This option allows you to specify a specific version of the extension for download using its version number. This option is not mandatory. When not included, the most recent version of the extension you require will always be deleted from your machine.

Note that:

  • removing an extension will only delete the extension files on the local machine. It does not remove the extension from any CAST AIP databases/schemas that it has been installed to.
  • removing an extension only removes the specific extension. Any dependencies are left on the machine as other extensions may require them.
  • removing an extension from your machine will cause the following log message to be displayed in CAST Server Manager when CAST AIP databases/schemas that use the extension are detected:
Extension com.castsoftware.test version : 1.2.0-funcrel is not present on this machine,
and some schemas are using it. Please use ExtensionDownloader to download it and rerun Servman.

Usage examples

Set the CAST Extend (online) connection properties

Set the api key:

Code Block
extendCli.exe config set api-key w9876xyz-d999-32ii-9fb0-0123cde45

Image Removed

Set the CAST Extend URL:

Code Block
ExtendCli.exe config set extend-url "Your URL"

Define the extensions to package

Add one extension

The extension and any dependencies will be added to the list of extensions in the bundle with the following command:

Code Block
extendCli.exe bundle add com.castsoftware.typescript

You can also use certain [options] as follows:

Code Block
ExtendCli.exe bundle add com.castsoftware.typescript [options]

These options can be cumulative, for instance to download the absolute latest release (including alpha/beta) or the latest funcrel release or the latest LTS, use the following:

Code Block
extendCli.exe bundle add com.castsoftware.typescript -a -f -l

...

download an extension without any dependencies. CAST only recommends using this option if you understand the implication - an extension will not function correctly without its dependencies.
This option is not mandatory. When not included, the most recent versions of an extension's dependencies will always be downloaded.

[--username <username>]

[--password <password>]

When connecting to a server that requires authentication (for example https://extend.castsoftware.com:443/api) to download an extension (with the install option), use these two options to specify your credentials. You will require an account on the remote server to authenticate when using CAST Extend. You can find out about registering for an account in CAST Extend website.


uninstall

uninstall

extensionId

[--version <version>]

Use this option to specify an extension that you have downloaded to your machine and that you now want to remove from your machine:

Option

Description

extensionIdThis option allows you to specify a particular extension for removal using its ID - this is a mandatory option. The ID of a CAST AIP extension always takes the form com.castsoftware.<name>, without any version numbers.
[--version <version>]

This option allows you to specify a specific version of the extension for download using its version number. This option is not mandatory. When not included, the most recent version of the extension you require will always be deleted from your machine.

Note that:

  • removing an extension will only delete the extension files on the local machine. It does not remove the extension from any CAST AIP databases/schemas that it has been installed to.
  • removing an extension only removes the specific extension. Any dependencies are left on the machine as other extensions may require them.
  • removing an extension from your machine will cause the following log message to be displayed in CAST Server Manager when CAST AIP databases/schemas that use the extension are detected:
Extension com.castsoftware.test version : 1.2.0-funcrel is not present on this machine,
and some schemas are using it. Please use ExtensionDownloader to download it and rerun Servman.

Usage examples

Set the CAST Extend (online) connection properties

Set the api key:

Code Block
extendCli.exe bundleconfig add com.castsoftware.typescript -a -l

E.g.:

Image Removed

Add extensions from predefined bundles

...

set api-key w9876xyz-d999-32ii-9fb0-0123cde45

Image Added

Set the CAST Extend URL:

Code Block
ExtendCli.exe bundle template add 14

Image Removed

Save the bundle

Once you have defined the content of your bundle using the bundle add or template add commands, you can save it to a .json file, so that you can use the same bundle in the future:

Image Removed

Generate the package

When you generate the package, it will create the .extarchive file <last package name|default package name>.extarchive which can then be uploaded into your CAST Extend local server/Offline instance. You must define a folder where the archive file will be placed and the folder must exist already:

Code Block
ExtendCli.exe bundle pack -o "C:\PRODUCT\Extend Offline\My package"

Image Removed

Navigate to the folder you have defined as output (in the above example the path is C:\PRODUCT\Extend Offline\My package) - it will contain the generated .extarchive file that you can upload into your CAST Extend local server/Offline instance by following the steps described in Upload the bundle to CAST Extend local server or Upload the bundle to CAST Extend Offline:

...

config set extend-url "Your URL"

Define the extensions to package

Add one extension

The extension and any dependencies will be added to the list of extensions in the bundle with the following command:

Code Block
extendCli.exe bundle add com.castsoftware.typescript

You can also use certain [options] as follows:

Code Block
ExtendCli.exe bundle add com.castsoftware.typescript [options]

These options can be cumulative, for instance to download the absolute latest release (including alpha/beta) or the latest funcrel release or the latest LTS, use the following:

Code Block
extendCli.exe bundle add com.castsoftware.typescript -a -f -l

To download the absolute latest release (including alpha/beta) or the latest LTS, use the following:

Code Block
extendCli.exe bundle add com.castsoftware.typescript -a -l

E.g.:

Image Added

Add extensions from predefined bundles

The "add template" command allows you to add extensions to your bundle that belong to a specific predefined bundle (predefined in CAST Extend (online)). The following command will add template number 14 to the bundle:

Code Block
ExtendCli.exe bundle template add 14

Image Added

The following commands will add all "product", "user community" and "labs" extensions:

Code Block
ExtendCli.exe bundle template add product
ExtendCli.exe bundle template add community
ExtendCli.exe bundle template add labs

Save the bundle

Once you have defined the content of your bundle using the bundle add or template add commands, you can save it to a .json file, so that you can use the same bundle in the future:

Image Added

Generate the package

When you generate the package, it will create the .extarchive file <last package name|default package name>.extarchive which can then be uploaded into your CAST Extend local server/Offline instance. You must define a folder where the archive file will be placed and the folder must exist already:

Code Block
ExtendCli.exe bundle pack -o "C:\PRODUCT\Extend Offline\My package"

Image Added

Navigate to the folder you have defined as output (in the above example the path is C:\PRODUCT\Extend Offline\My package) - it will contain the generated .extarchive file that you can upload into your CAST Extend local server/Offline instance by following the steps described in Upload the bundle to CAST Extend local server or Upload the bundle to CAST Extend Offline:

Image Added

Advanced configuration settings - appsettings.json

Some additional advanced settings can be configured using the following file which can be edited with a text editor:

Code Block
<extend_cli_unzip_folder>\appsettings.json

Timeout

Code Block
"Timeout": 10800

This setting (available in ≥ 2.1.1-funcrel) is specifically for those with very slow network connections. The value is in seconds (the default value is 10800, or 3 hrs) and should only be increased if you are facing timeouts when fetching data from CAST Extend, i.e. when the total time required for CAST Extend to build the bundle and then for ExtendCli to download it exceeds 3 hrs. CAST does NOT recommend decreasing this value.

SettingsPath

Code Block
"SettingsPath": null

This setting (available in ≥ 2.1.1-funcrel) is set by default to %PROGRAMDATA%\CAST\ExtendCLI and defines where the current instance of ExtendCli will store configuration settings and cache files. If you need to run multiple instances of ExtendCli on one machine, and you want to ensure clear separation of data between each instance, you can define a custom path for the configuration data using this option. For example to set the path to D:\CAST\temp\ExtendCli:

Code Block
"SettingsPath": "D:\\CAST\\temp\\ExtendCli"


Info

Paths must conform to the following syntax:

  • Enclosed in double quotes
  • Absolute path (not relative)
  • Back slashes are required (forward slashes not accepted) and must be escaped with a back slash