MapLargeInc.CLI 1.0.85

MapLarge CLI

The MapLarge CLI provides tools for:

• Administering MapLarge server instances
• Developing extensions using the Application Development Kit (ADK)

With these tools, a local developer can create a new extension project, create new components, run the extension locally during development, and finally deploy the built and finished package to the MapLarge Server of their choice.

Setting up your local ADK environment

The MapLarge ADK (Application Development Kit) is a set of tools that allow developers to build and package extensions for the MapLarge server.

Follow these steps to setup your local environment.

Install Microsoft .NET SDK 8.0

https://dotnet.microsoft.com/en-us/download/dotnet/8.0

Install Node.js

https://nodejs.org/en/download

Install MapLarge CLI

The ADK comes bundled with the MapLarge CLI (command-line interface). You can install the CLI from a Nuget tool package via the command prompt.

$ dotnet tool install -g MapLargeInc.CLI --add-source [path to folder containing nupkg file] --version [package version number]

To validate the installation, run the following command to see the installed version of the CLI.

$ maplarge version

Trust ASP.NET dev certificates

To trust Microsoft's ASP.NET developer certificates, run the following:

$ dotnet dev-certs https --trust

Create an empty ADK project

One or more MapLarge extensions can be developed inside a single ADK project. To create an empty ADK project, run the following:

$ maplarge adk create-project -name MyExtensions

Change directory to your newly created project folder:

$ cd MyExtensions

Open Visual Studio Code

We recommend Visual Studio Code for developing client-side extensions for MapLarge. You can quickly open VS Code from the command prompt by running:

$ code .

Suggestion: You may use a Terminal Window inside VS Code to run CLI commands.

Adding a MapLarge extension to your ADK project

You may wish to create an empty extension, an extension based on a template, or clone an existing extension from source control.

Create an empty extension

To create a new, empty extension, run the following:

$ maplarge adk create-extension -name MyExtension

You should see a new folder for your extension inside the extensions/ folder in your project.

Create an extension from a template

To list available templates, run the following:

$ maplarge adk list-templates

To create an extension using a template, include the -template option, followed by the template name. For example:

$ maplarge adk create-extension -name MyExtension -template client-extension-empty

Clone an extension from source control

To clone an existing extension from source control, you must first determine the folder structure of the repo. Some repos house a single extension, while others contain multiple.

Single-extension Repo

A single-extension repo will contain a client/ and/or server/ folders and a manifest.json file in the root of the repo, among other files. For example:

client/
server/
manifest.json

To clone this repo, you may use the MapLarge CLI to clone the extension:

$ maplarge adk create-extension -name MyExtension -clone https://url-to repo-to-clone

Multi-extension Repo

A multi-extension repo will likely contain folders for each extension at the root of the repo, like this:

MyExtension/
    client/
    server/
    manifest.json
AnotherExtension/
    client/
    manifest.json

In this case, you'll need to clone your repo using git directly.

From the root of your ADK project, run the following, taking care to specify that you want your local clone to be put in the extensions/ folder.

$ git clone https://url-to-repo-to-clone extensions

Initialize your ADK project

To build, debug, and package MapLarge extensions, you must initialize your ADK project against a MapLarge server instance. There are two ways to do so.

Init against a remote server

Initialize your project against a running MapLarge server instance. The following command will download several configuration files, TypeScript declarations, and DLLs needed to package an extension that is compatible with that server's particular version.

$ maplarge adk init -remoteServer https://maplarge-instance-domain \
    -profile my-specific-instance-name

The -profile option will save the remote server URL (among other options like username/password), allowing you to run other commands (e.g. package, deploy) without needing to include such options every time.

Init against a local repository of server source code

Internal MapLarge developers who have cloned the server source code locally main initialize an ADK project against the local version, allowing them to make server changes in conjuction with ADK extension development.

$ maplarge adk init -remoteServer https://localhost:1234 \
    -localServerRoot "local-path-to-server-repo-root" \
    -profile local

This option recompiles all of the server TypeScript, so it may take significantly longer to init against a local source repo.

Running your local client-side extension

After initializing a client-side extension, you may run and debug the extension.

$ maplarge adk run

This command will compile the TypeScript and LESS files, and start a local ASP.NET server instance that will host your extension. While your extension is hosted locally, any communication with the MapLarge server instance (e.g. queries) will be sent to the server you initialized against. This means that your MapLarge server instance must be running while your local ADK project runs.

While your local project is running, changes to extension source files (e.g. TypeScript files) will automatically trigger a recompile of the extension. After it finishes, you may refresh your browser to see the changes.

Packaging an extension for deployment

In addition to debugging an extension locally (using run), you may also package up an extension and install it directly on a MapLarge server instance, just how it would be in production.

$ maplarge adk package -extensions MyExtension

The package command will create a ZIP file and deposit it in the .adk/.deploy/ folder. This ZIP file may be installed on a MapLarge instance via the sidebar menu: Admin → Extensions.

Deploying an extension from the command-line

The CLI allows developers to package, upload, and install an extension using a single command.

$ maplarge adk deploy -extensions MyExtension \
    -user user@domain.com \
    -password mypassword \
    -profile my-specific-instance-name \
    -install

Note: after running the above command, subsequent deploy calls may leave off the authentication parameters, since they are saved to the profile.

maplarge adk deploy -extensions MyExtension -profile my-specific-instance-name -install

Server-side Plugins

ADK projects also support server-side plugins. Code for these plugins resides in the server/ folder of an extension. An extension may include both client-side and server-side components. We recommend developers use Visual Studio to develop server-side plugins.

Server-side plugins must be deployed to a running MapLarge server instance in order to execute them.

CLI Help

For all CLI commands, you may include the -? option to see a list of options.