MapLarge Command-line Interface dotnet tool
$ dotnet add package MapLargeInc.CLIThe MapLarge CLI provides tools for:
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.
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.
https://dotnet.microsoft.com/en-us/download/dotnet/8.0
https://nodejs.org/en/download
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
To trust Microsoft's ASP.NET developer certificates, run the following:
$ dotnet dev-certs https --trust
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
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.
You may wish to create an empty extension, an extension based on a template, or clone an existing extension from source control.
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.
To list available templates, run the following:
$ maplarge adk list-templatesTo 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-emptyTo 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.
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-cloneA 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 extensionsTo build, debug, and package MapLarge extensions, you must initialize your ADK project against a MapLarge server instance. There are two ways to do so.
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-nameThe -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.
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 localThis option recompiles all of the server TypeScript, so it may take significantly longer to init against a local source repo.
After initializing a client-side extension, you may run and debug the extension.
$ maplarge adk runThis 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.
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 MyExtensionThe 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.
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 \
-installNote: after running the above command, subsequent
deploycalls may leave off the authentication parameters, since they are saved to the profile.
maplarge adk deploy -extensions MyExtension -profile my-specific-instance-name -installADK 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.
For all CLI commands, you may include the -? option to see a list of options.