CLI Overview

The Azure portal extension developer CLI, namely ap, is the foundational tool used for all inner dev/test loop actions during extension development.

This document details the usage and extensibility points of the ap CLI. The following video covers the majority of the content within this document - ap cli video https://aka.ms/portalfx/apcli.

Setup and Installation

One time configuration steps

Install the LTS of nodejs download

download setup.js and place 'setup.js' inside the project or directory you are working on.
run node setup.js and perform any actions it asks you to.

If you prefer follow along see the step by step:

Manual one time Auth Setup and Installation steps
Video:One time configuration steps

Basic workflows

restore, build, serve, sideload and watch

Run command prompt as Admin
Get started with a declarative extension. A declarative extension is easier to build and cheaper to maintain. Learn more here. Extension authors can always shift from a declarative extension to a hybrid extension (declarative and native typescript blades) at any point of time.
To get started with a declarative extension, run following commands

cd c:\ && mkdir dev && cd dev
ap new -d -n Microsoft_Azure_FirstExtension -o ./FirstExtension
cd ./FirstExtension/src/default/extension
ap start

Alternatively, if you have evaluated using a declarative extension and established that it does not work for your scenario, you can start with a native Ibiza extension using the following commands -

cd c:\ && mkdir dev && cd dev
ap new -n Microsoft_Azure_FirstExtension -o ./FirstExtension
cd ./FirstExtension/src/default/extension
ap start

See ap start demo in the Video: A single command for restoring dependencies, building, serving with local hosting service, sideloading and compile on save

run tests

Run command prompt as Admin
run following commands

cd ./FirstExtension/src/default/extension.unittests
ap run test

See ap run test demo in the Video: running tests

lint your extension

cd ./FirstExtension/src/default/extension
ap lint

updating your Portal Framework version

Run the command prompt as Admin
Update the cli to the target version of Portal Framework e.g npm install -g @microsoft/azureportalcli@5.303.601
From the root of your enlistment run ap update and see changes with git status

ap update
git status

See ap update demo in the Video: Updating the CLI, extension SDK version and revoked SDKs.

Command Reference

Command	Alias	Description
build		Runs msbuild.exe on the .sln or proj with/p:RunBundlerInDevMode=true. If no .sln or proj is found and tsconfig.json exists then runs tsc.cmd. If arguments are supplied they are passed through to underlying executable.
diag		Emits all information and current deployed state of extension for all clouds.
lint		Runs eslint against an extension including azure portal custom lint rules.
new		Creates a new extension.
samples		Clones the samples extension.
release		Runs msbuild.exe on the .sln or proj with /p:RunBundlerInDevMode=false;Configuration=Release. If no .sln or proj is found and tsconfig.json exists then runs tsc.cmd. If arguments are supplied they are passed through to underlying executable.
restore		Installs node modules and restores NuGet packages for all package.json, .sln and .csproj recursively from the current working directory.
run		Straight passthrough to npm run i.e 'ap run mycommand' will execute 'npm run mycommand'
serve		A command to run the local hosting service. Optional arguments are passed through to the local hosting service.
start		A command to restore, build, run the local hosting service and start the watch process to enable compile on save.
update		Updates Azure Portal SDK NuGets and node modules to same version as the CLI.
watch		enables compile on save by running tsc.cmd in watch mode on the current working directory.
help		Lists available commands and their short descriptions.

Options: Option | Description --- | --- | --- --version | Show version number of ap cli --help | Shows help. Can be used on ap directly i.e ap --help or on its commands e.g ap start --help

ap build

ap build <arguments> [options]

Runs msbuild.exe on the *.sln or *proj with /p:RunBundlerInDevMode=true. If no *.sln or *proj is found and tsconfig.json exists then runs tsc.cmd. The resulting output is the build output in the format required by local hosting service. For deployable zip see release command. Arguments are optional, if supplied they are passed through to underlying executable for the resolved build type. The build alias for msbuild and tsc can be overriden using apCliConfig.json.

Arguments

Argument	Description

| All arguments supplied are passed through to the resolved build executable, generally msbuild or tsc. --help | Show help for build command

Example Usage

Most common usage is to perform build allowing ap to resolve the *.sln, *proj or tsconfig.json that requires build.

ap build

Perform build supplying your own arguments that are passthrough to msbuild.

ap build /m /t:Rebuild /flp1:logfile=msbuild.log /flp2:logfile=msbuild.err;errorsonly /flp3:logfile=msbuild.wrn;warningsonly /p:RunBundlerInDevMode=true

Perform build supplying your own arguments to tsc.cmd.

ap build -p tsconfig.json --traceResolution

Emit help for the build command.

ap build --help

Supplying defaults using apCliConfig.json

When the build command runs it will search for apCliConfig.json from the current working directory up to the root of the drive. The build command can be customized by supplying any of the following optional top level properties. This may be useful if you have a predefined wrapper alias used within your build environment.

Property	Description
msbuildAlias	optional. alias or path to alias to be used in place of msbuild.exe.
msbuildDefaultArgs	optional. arguments to be supplied to msbuild based projects when running `ap build`
tscAlias	optional. alias or path to alias to be used in place of tsc.cmd.

Example apCliConfig.json configuration:

{
    "msbuildAlias": "myspecialmsbuildalais",
    "msbuildDefaultArgs": "/m /t:Rebuild /p:RunBundlerInDevMode=true;Configuration=MyCustomConfig",
    "tscAlias": "./alias/not/on/path/tsc.cmd",
}

ap diag

ap diag <arguments>

This command emits diagnostics for an extension from clouds. Help developers understand what version of their extension is deployed in each of these different clouds and provide useful information about the extension. Diagnostics also include extension name, primary stamp version, shell version, extension portal side version, extension hosting service side version, SDK version, SDK age, stage definition, manifest errors, and last error in all common deplyment slots in all public clouds.

Arguments

Argument	alias	Description
--name	--n	Optional. The extension name in portal registration or extensions hosting service name to emit the diagnostics for.
--production	--prod	Optional. Emits the diagnostics from production cloud.
--blackforest	--bf	Optional. Emits the diagnostics from blackforest cloud.
--fairfax	--ff	Optional. Emits the diagnostics from fairfax cloud.
--mooncake	--mc	Optional. Emits the diagnostics from mooncake cloud.
--dogfood	--df	Optional. Emits the diagnostics from dogfood cloud.
--mpac	--mpac	Optional. Emits the diagnostics from mpac cloud.

Example Usage

Emits the diagnostics for the extension within the current working directory from all 6 clouds (production, blackforest, fairfax, mooncake, dogfood, mpac). When you run ap diag, you get the getExtensionNameInPortalRegistration as a default extension name from ./devServerConfig.json

ap diag

Emits the diagnostics for "Microsoft_Azure_Storage" extension from specific clouds. You can also choose the clouds you want to be diagnosed. If cloud name not given, it emits the diagnostics from all 6 clouds.

ap diag --name Microsoft_Azure_Storage

Emits the diagnostics for "storage" extension from specific clouds. You can also choose the clouds you want to be diagnosed. If cloud name not given, it emits the diagnostics from all 6 clouds.

ap diag --name storage
ap diag --name storage --prod
ap diag --name storage --prod --ff
ap diag --name storage --ff --bf --df

Emits the diagnostics for existing default extension from specific clouds. You can also choose the clouds you want to be diagnosed.

ap diag --prod
ap diag --mc --df --mpac

Supplying defaults using apCliConfig.json

When the ap diag command runs, it will search for apCliConfig.json from the current working directory up to the root of the drive. The diag command can be customized by supplying any of the following optional top level properties. This may be useful if you have other custom friendly names you wish to emit diagnostic information on by default.

Property	Description
diagAdditionaFriendlyNames	Optional. Collection of additional friendly names to emit diagnostics on.

{
    "diagAdditionaFriendlyNames": ["staging", "someotherfriendlyname"]
}

ap lint

ap lint <arguments>

This command lints the current directory using eslint / typescript-eslint. The CLI ships both core and recommended rule configuration for common public lint rules as well as custom lint rules authored by portal team for extension developers. To understand exactly how the portal team is planning to use this as a means to improve your developer experience it's recommended that you watch the linting Video: Linting - custom portal lint rules, automated breaking change resolution and lint integration to VS Code

If an .eslintrc* and/or .eslintignore files is present in the current working directory its configuration will take precedence over the configuration shipped within the CLI.

If authoring custom rules for your own team use apCliConfig.json to supply a collection of paths and ap CLI will supply them to the eslint --rulesdir argument.

Arguments

Argument	Description
--fix	Optional. Automatically fix problems by running the automated fix implementation that ship with each lint rule.
--format	Optional. formats results in the desired eslint format https://eslint.org/docs/user-guide/formatters.
--resolve-plugins-relative-to	Optional. A folder where plugins should be resolved from.
--help	Show help for the command.

Example Usage

Most common usage, integration directly with VS Code for realtime feedback on lint violations as you develop, see subsequent section for configuring the eslint plugin for VS Code.

Run lint from command prompt

ap lint

Run lint with automated fix

ap lint --fix

Emit help for the command.

ap lint --help

Linting directly within VS Code

A plugin can be installed and configured directly within VS Code to allow you to see and fix lint violations directly within the IDE as you develop. If you ware not using VS Code and want integration in your IDE you can checkout the following recommended plugins by IDE

Install the eslint plugin for VS Code

The eslint plugin requires an .eslintrc (.js,.json,.yaml) file to be present. You can take the latest from node_modules@microsoft\azureportalcli\lint\.eslintrc.json

{
    "plugins": [
        "@microsoft/eslint-plugin-azureportal"
    ],
    "extends": [
        "plugin:@microsoft/eslint-plugin-azureportal/lib/core"
    ],
    "rules": {}
}

Enable eslint in VS Code for typescript - open json settings using CTL + Shift + P select (Preferences): Open Settings (JSON) and add:

    "eslint.validate": [
        {
            "language": "typescript",
            "autoFix": false
        },
    ],

Install dev dependencies required by the eslint plugin for vscode npm install typescript@3.5.3 @microsoft/eslint-plugin-azureportal --no-optional --save-dev (note version of typescript may have been updated since authoring.)

The eslint plugin should now be running the core set of azure portal rules directly within VS Code. If you suspect there are issues you can see the eslint plugin output in the Output window by changing the dropdown to Eslint. i.e Ctl + Shift + U to get the output window then select ESLint in the dropdown. Review the ouput to see if there are any configuration errors.

Customizing Lint Rules

The CLI linting component is built as an eslint pluging and is therefore highly extensible and configurable. For the most part many teams will what is provided out of the box should be sufficient, for those teams that wish to customize read on.

The CLI ships two sets of rules, namely core and recommended. core is the minimal set of rules that at the time of writing included only deprecated and azure portal custom rules. The recommended set contains all core rules and a recommended configuration common public rules from typescript-eslint.

You can change your project to use the recommended set by updating your .eslintrc* file to extend recommended rather then core i.e

```json
{
    "plugins": [
        "@microsoft/eslint-plugin-azureportal"
    ],
    "extends": [
        "plugin:@microsoft/eslint-plugin-azureportal/lib/recommended"
    ],
    "rules": {}
}
```

To customize rule levels off/warn/error additional rules you have full control of of all content within your own .eslintrc* this follows the eslintrc schema and is documented at configuring rules. The rule set you may be most interested in customizing for your specific team are documented here - typescript-eslint rules. We view the recommended set of rules as being extension developer community driven with the oversight of the azure portal team, if you believe rule configurations should be different/added in the recommeneded set please reach out to us to discuss.

Before turning a rule off globally its worth considering just disabling the rule on the specific instance in the source file where it is flagged, at the same time it may be worth creating a work item to remediate the issue - this is particularly important for the custom azure portal rules i.e @microsoft/azureportal/* rules. To disble a rule for a specific occurence see the inline comment syntax documentation - disabling rules with inline comments.

If you have authored your own eslint plugin or custom ruleset please reach out to us as we would like to understand if it makese sense to role those rules into @microsoft/eslint-plugin-azureportal to enable all teams to use them. You can supply paths to your custom rulesets to the ap CLI using apCliConfig.json lintCustomRules property. Each rule in the collection will be supplied to eslint as a --rulesdir. example config

{
    "lintCustomRules":["./tools/mycustomlintrules/stable", "./tools/mycustomlintrules/futures"],
}

To learn more about linting and its configuration see Video: Linting - custom portal lint rules, automated breaking change resolution and lint integration to VS Code.

ap new

ap new <arguments>

Creates/Scaffolds a new Portal Extension and corresponding test project with the supplied name to the target ouput folder. For a video walkthrough of scaffolding a new extension see this video.

Arguments

Argument	alias	Description
--name	-n	Required. The name used in portal registration of the extension e.g Microsoft_Azure_SomeExtension.
--output	-o	Required. The output directory to place the new project.
--declarative	-d	Optional. Scaffolds declarative extension.
--help		Optional. Show help for new command.

Example Usage

Two examples scaffolding a new extension to the ./dev/newextension folder. The first using shorthand, the second longhand.

ap new -n CompanyName_ProductName_ServiceName -o ./dev/someextension
ap new --name Microsoft_Azure_Storage --output ./dev/storage
ap new --name Microsoft_Azure_MyExtension --output ./dev/myextension --declarative
ap new -n Microsoft_Azure_MyExtension -o ./dev/myextension -d

Emit help for the build command.

ap new --help

ap samples

ap samples <arguments>

Clones the Azure portal Samples Extension.

Arguments

Argument	alias	Description
--output	-o	Optional. The output directory to place the new project.
--help		Optional. Show help for new command.

Example Usage

Two examples scaffolding a samples extension to the ./dev/samplesextension folder. The first using shorthand, the second longhand.

ap samples
ap samples -o ./dev/someextension
ap samples --output ./dev/storage

Emit help for the build command.

ap samples --help

ap release

ap release <arguments>

Runs msbuild.exe on the *.sln or *proj with /p:RunBundlerInDevMode=false;Configuration=Release. If no *.sln or *proj is found and tsconfig.json exists then runs tsc.cmd. The result is the versioned zip, e.g 1.0.0.0.zip, output which can be deployed to hosting service. For build output in the format for required local hosting service see the build command. Arguments are optional, if supplied they are passed through to underlying executable for the resolved build type. The build alias for msbuild and tsc can be overriden using apCliConfig.json. For a video walkthrough of the release command this video

Arguments

Argument	Description

| All arguments supplied are passed through to the resolved build executable, generally msbuild or tsc. --help | Show help for build command

Example Usage

Most common usage is to perform build allowing ap to resolve the *.sln, *proj or tsconfig.json that requires build.

ap release

Perform release build supplying your own arguments that are passthrough to msbuild.

ap release /m /t:Rebuild /flp1:logfile=msbuild.log /flp2:logfile=msbuild.err;errorsonly /flp3:logfile=msbuild.wrn;warningsonly /p:RunBundlerInDevMode=false;Configuration=Release

Perform release build supplying your own arguments to tsc.cmd.

ap release -p tsconfig.json --traceResolution

Emit help for the release command.

ap release --help

Supplying defaults using apCliConfig.json

When the build command runs it will search for apCliConfig.json from the current working directory up to the root of the drive. The build command can be customized by supplying any of the following optional top level properties. This may be useful if you have a predefined wrapper alias used within your build environment.

Property	Description
msbuildAlias	optional. alias or path to alias to be used in place of msbuild.exe.
msbuildDefaultArgs	optional. arguments to be supplied to msbuild based projects when running `ap release`
tscAlias	optional. alias or path to alias to be used in place of tsc.cmd.

Example apCliConfig.json configuration:

{
    "msbuildAlias": "myspecialmsbuildalais",
    "msbuildDefaultArgs": "/m /t:Rebuild /p:RunBundlerInDevMode=true;Configuration=MyCustomConfig",
    "tscAlias": "./alias/not/on/path/tsc.cmd",
}

ap restore

ap restore <arguments>

Installs node modules and restores NuGet packages for all package.json, *.sln and *.csproj recursively from the current working directory. Note that the following folders are ignored node_modules, obj, objd, objr, out, output, debug and release.

Where recusive discovery of NuGet packages and node modules that need restoration is slow, such as in large projects, arguments or apCliConfig.json can be used to provide the collection of .sln,.csproj,package.json for restore/install.

Requires nuget and npm.cmd available on the path. See first time setup steps at top of this document.

Arguments

Argument	Alias	Description
--nugetRestoreFiles		optional. The .sln, .csproj or packages.config files to perform a NuGet restore upon. If more then one supplied separate using ';'. When supplied the command will not scan directories for files to restore.
--npmInstallPackageJsonFiles		optional. The package.json files to perform a npm install upon. If more then one supplied separate using ';'. When supplied the command will not scan directories directories for package.json files to restore.
--restoreInParallel		optional. Run npm install and NuGet restore in parallel.
--help		Emits help and usage for the command

Example Usage

Most common usage, node modules and NuGet packages needing install/restore will be discovered. if specific set supplied in apCliConfig.json then they will be used in place of recursive search.

ap restore

Examples specifying which files to perform NuGet restore restore against. In this case only the specified list will be restored using NuGet however node modules will still be discovered.

ap restore --nugetRestoreFiles ./SomeDir/Some.sln
ap restore --nugetRestoreFiles ./SomeDir/Some.sln --restoreInParallel
ap restore --nugetRestoreFiles ./SomeDir/Some.csproj
ap restore --nugetRestoreFiles ./SomeDir/Some.sln;./OtherDir/Other.csproj;./AnotherDir/packages.config

Examples specifying which files to perform npm install against. In this case only the specified list will be installed using npm however NuGet packages requireing restore will still be discovered.

ap restore --npmInstallPackageJsonFiles ./SomeDir/package.json
ap restore --npmInstallPackageJsonFiles ./SomeDir/package.json;./OtherDir/package.json

Supplying explicit set of Nuget and node module for restore and install. Note if used frequently rather then simple discovery see next section on supplying this via config.

ap restore --nugetRestoreFiles ./SomeDir/Some.sln;./OtherDir/package.json --npmInstallPackageJsonFiles ./SomeDir/package.json;./OtherDir/package.json

Emits help and usage examples for the restore command

ap restore --help

Supplying defaults using apCliConfig.json

When the restore command runs it will search up from the current working directory up until it finds apCliConfig.json or the root of the drive. The restore command can be customized by supplying any of the following optional top level properties. If you have a large project and discovery is slow this is useful to supply an explicit list of node modules and NuGet packages to be used by default by ap restore.

Property	Description
nugetRestoreFiles	Optional. An explicity collection of files e.g ./foo.sln and ./bar.csproj to perform nuget restore against.
npmInstallPackageJsonFiles	Optional. An explicity collection of package.json .sln and .csproj to perform nuget restore against.
restoreInParallel	Optional. Run npm install and NuGet restore in parallel.

Example apCliConfig.json configuration:

{
    "nugetRestoreFiles": ["./src/proja/Some.sln", "./src/projb/Other.sln", "./other/proj.csproj"],
    "npmInstallPackageJsonFiles": ["src/Default/Extension.UnitTest/package.json", "src/default/Extension.E2ETests/package.json"],
    "restoreInParallel": true,
}

ap run

ap run <arguments>

The ap run command provides straight passthrough to npm run. Typically used to run scripts defined in package.json.

Arguments

Argument	Description

| Required. All arguments are passed through directly to npm run. See usage examples --help | Emits help and usage for the command

Example Usage

Running tests in watch mode

ap run test

Running tests in single run ci mode

ap run test-ci

Running an arbitrary script from package.json

ap run myscript --myscriptargument

ap serve

ap serve <arguments>

A command to run the local hosting service. Optional arguments are passthrough to the local hosting service.

Arguments

Argument	Description

| Optional. All arguments are passed through directly to local hosting service. See usage examples --help | Emits help and usage for the command

Example usage

Most common usage, discovers first devServerConfig.json below current directory and runs local hosting service to side load your extension in portal.azure.com.

ap serve

Precedence:

-s "URL"
"sideLoadTarget" specified in devserverConfig.json
-s if neither is specified and -s is passed, the default https://portal.azure.com is loaded

Use specific ./devServerConfig.json and side load extension.

ap serve -c ./devServerConfig.json -s

Side load extension in mpac.

ap serve -s https://ms.portal.azure.com

Side load extension using specific config into rc.portal.azure.com.

ap serve -c ./devServerConfig.json -s https://rc.portal.azure.com

Side load extensions can be used with custom parameters

ap serve -c ./Extension.Server/devServerConfig.json -s https://portal.azure.com?feature.foo=true#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview

Overriding settings for local development

A Local host specific *.config can be used to override prod settings for local development. This is useful in scenarios where an extension may want to update a setting to use a webApi that is running on localhost or to test the impact of changing other settings.

By default local override config files can be placed within ./LocalContent/Config they are identical to trusted authority files that are located within /Content/Config except the settings are customized to your desired local use.

Example: Assume you want to change settings for mpac:

Copy ./Content/Config/ms.portal.azure.com.json to ./LocalContent/Config/ms.portal.azure.com.json and update the config to use the local settings you wish to test; for example a local webapi you are developing

{
    ...
    "fooApi" : "https://localhost:12345/Api/foo",
    ...
}

When you run ap serve the content of ./LocalContent/Config/ms.portal.azure.com.json will be used instead of ./Content/Config/ms.portal.azure.com.json.

The path for ./LocalContent/Config can be customized from the default using either the -l argument or the localConfigPath property of devServerConfig.json, examples follow.

Example: supplying the local config path via -l argument

ap serve -c ./devServerConfig.json  -l "./Test/Config"

Example: supply the local config path via devServerConfig.json

{
  ...
    localConfigPath: "ExamplePath"
  ...
}

If the path is supplied in multiple places the precedence is -l argument followed by devServerConfig.json otherwise default path ./LocalContent/Config is used.

Paths are relative to where the devServerConfig.json exists

The local hosting service devServerConfig.json supports the following properties:

PropertyName	Description
extensionHostingServiceName	Name of extension as registered in the hosting service
extensionNameInPortalRegistration	Name of extension as registered in the Azure Portal
port	The port the server will listen on for incoming requests
extensionServableContentPath	The output that is generated by the bundler
bundlerPath	The path to the bundler executable
extensionContentSource	The output of the typescript compiler
sideLoadTarget	URL for sideload supports custom parameters. This is optional
localConfigPath	Optional. The folder path relative to devServerConfig.json that contains local config files for development.
galleryPackagePath	Optional. The path to the local gallery package. If omitted, will default to <devServerConfig.json path>/App_Data/Gallery

example: An example of a dev server config:

{
    "extensionHostingServiceName": "firstextension",
    "extensionNameInPortalRegistration": "Microsoft_Azure_FirstExtension",
    "port": 1339,
    "extensionServableContentPath": "./obj/Debug",
    "bundlerPath": "../../packages/Microsoft.Portal.Tools.5.0.303.3921/build/bundle.exe",
    "extensionContentSource": "./Output",
    "sideLoadTarget": "https://portal.azure.com?feature.foo=true#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview"
    "localConfigPath" : "./LocalContent/Config",
    "galleryPackagePath": "./App_Data/Gallery"
}

ap start

ap start

Provides a simple single command to restore, build, serve the extension via local hosting service and start the watch process to enable compile on save. This effectively enables compile on save based development with a full pipeline from save through local hosting service ingestion such taht you can see changes reflected within the browser as you undergo active development. The following video demonstrates this command - Video: A single command for restoring dependencies, building, serving with local hosting service, sideloading and compile on save.

Customization using apCliConfig.json as defined in the restore, build and watch commands will also apply to this command.

Arguments

Argument	Description
--help	Emits help and usage for the command

Example Usage

Performs restore, build, serve and watch commands enabling compile on save and fast inner dev/test loop.

ap start

Emits help and usage examples for the watch command

ap start --help

ap update

ap update

Updates Azure Portal SDK NuGets and node modules to same version as the CLI. By default the following files are recursively searched for and updated: packages.config,package.json,corext.config,.proj,.csproj,*.njsproj and devServerConfig.json. To provide your own set of files either supply a collection of file paths or supply a glob pattern via apCliConfig.json. This video details how to update both the ap CLI and your extension using this command - Video: Updating the CLI, extension SDK version and revoked SDKs.

Arguments

Argument	Alias	Description
--config	-c	Optional. Path to apCliConfig.json.
--help	Emits help and usage for the command

Example Usage

Most common, recursively finds target files to update NuGet and node module references from portal sdk.

ap update

Supplying a config file argument where a glob is defined that specifies the set of file you wish to have updated by this command. Note, by default update also searches up from the current working directory for apCliConfig.json if no --config file is supplied.

ap update --config ../../some/other/path/apCliConfig.json

Emits help and usage examples for the update command.

ap update --help

Supplying defaults using apCliConfig.json

When the update command runs you can optionally specify a collection of file paths or custom glob pattern for files to be updated using apCliConfig.json using either of the following optional top level properties. If you have a large project and discovery is slow this is useful to supply an explicit list of files will speed up this command.

Property	Description
updateCmdFiles	optional. A collection of file paths.
updateCmdFilesGlob	optional. A glob pattern. If updateCmdFiles is defined it will take precedence and this setting will be ignored.

Example apCliConfig.json configuration providing a custom list of files:

{
    "updateCmdFiles": ["./src/Default/Extension.UnitTest/package.json", "./src/Default/Extension/packages.config", "./src/Default/Extension/Extension.csproj"],
}

Example apCliConfig.json configuration providing a custom glob pattern
```json
{
    "updateCmdFilesGlob": "**/{packages.config,package.json,corext.config,*.proj,*.csproj,*.njsproj,devServerConfig.json}",
}

ap watch

ap watch

This command enables compile on save by running tsc.cmd in watch mode on the current working directory. When used in conjunction with serve command provides end to end compile on save and ingestion of udpated files into local hosting service for faster inner dev test loop. For build environments where you may have your own alias abstracting tsc you can supply your own tscAlias within apCliConfig.json as defined in the build

Requires tsconfig.json to be present within the directory that this command is run within.

Arguments

Argument	Description
--help	Emits help and usage for the command

Example Usage

Most common usage, performs tsc watch using tsconfig.json from current working directory. Used predominantly for compile on save based development.

ap watch

Emits help and usage examples for the watch command

ap watch --help

Supplying defaults using apCliConfig.json

When the watch command runs it will search for apCliConfig.json from the current working directory up to the root of the drive. The watch command can be customized by supplying any of the following optional top level properties. This may be useful if you have a predefined wrapper alias used within your build environment.

Property	Description
tscAlias	optional. alias or path to alias to be used in place of tsc.cmd.

Example apCliConfig.json configuration:

{
    "tscAlias": "./my/tsc.cmd",
}

Extending the cli with your teams own commands

The Azure portal extension developer CLI is extensible and allows you to add your own custom commands that may be specific to tasks that your team commonly performs. Note if you have commands that you think are applicable to all teams reach out to us to discuss collaborating to contribute these back to the CLI so all teams can benefit. this content is also covered in this Video: Extending and Overriding commands in the CLI

To extend the CLI with your own custom commands requires two things a custom command(s) module(s) extending portalYargsCommand and config in apCliConfig.json defining where the CLI can load your commands from. Step by step instructions follow:

create a directory in your repo for your extensions e.g src/tools/cliextensions
cd src/tools/cliextensions
run command npm init
run command npm install yargs @microsoft/azureportalcli --no-optional --save

add file src/tools/cliextensions/cmds/foobar.ts with the following content

//src/tools/cliextensions/cmds/foobar.ts
import { Argv } from "yargs";
import { PortalYargsCommand } from "@microsoft/azureportalcli/lib/core/portalYargsCommand";

class Foobar extends PortalYargsCommand {
    public readonly command = "foobar";
    public readonly description = "my teams foobar command";

    public builder(yargs: Argv): Argv<any> {
        return yargs.options({
            name: {
                alias: "n",
                description: "<name> argument",
                requiresArg: true,
                required: true,
            },
        }).example(`ap ${this.command} -n somename`, "");
    }

    public async runCommand(args: { [argName: string]: string; }): Promise<void> {
        console.log(`custom implementation of ${this.command} called with argument ${args.n || args.name}`);
    }
}

export = Foobar;

Build the foobar.ts file ..\node_modules\.bin\tsc.cmd foobar.ts --lib ES2015,dom.
update your apCliConfig.json, typically located in /src/apCliConfig.json, to specify the path to the build output, i.e *.js, for your custom comands. Note the output path you use will vary depedending on your build or if you are distributing using a node module.

example with relative build output
```
{
    "customCommandRootPaths": ["./tools/cliextensions/cmds"],
}
```
example if distributed as a node module
```
{
    "customCommandRootPaths": ["./node_modules/@microsoft/azureportalcil-myteam-extensions/tools/cliextensions/cmds"],
}
```
run ap --help and observe that your foobar command now shows up

Overriding the behavior of existing commands

There are two ways to override and existing command within the cli. This can be useful to teams that have very specific requirements that the configurability of the existing command aguments and apCliConfig.json do not allow you to control. note if you think your scenario should be supported reach out to us to discuss adding support.

To override an existing either of the following approaches can be used:

define the command within the scripts object of the package.json in the current working directory. e.g to override restore deinfe "restore": "echo my restore". when you run ap restore it will now outut my estore rather then using the CLIs implementation. For more involved cases that cant be expressed in package.json see the following approach.
In the section above foobar.ts was added to extend the cli. This approach can also be used to override and existing command. Simply ensure the filename, class name and command property all express the same name of the command you wish to override.

Telemetry

Telemetry is collected to help improve ap and the extension developer experience. Writing remote telemetry can be disabled by setting disableRemoteTelemetry to true in apCliConfig.json AND apCliConfig.json exists in the current directory that ap is run within or any parent directory between where ap is run and the root of the drive drive. i.e it will find-up from the process.cwd().

Contributions and feedback

The ap CLI is built by the Azure portal team for the extension developer community. We welcome your contributions to the CLI and lint infrastructure where those contributions are applicable to all teams. Please reach out to us to discuss ideas. More details in Video: Contributions and Feedback

FAQ

Do I have to read this document, don't you have a video?

Yes, see the ap cli video https://aka.ms/portalfx/apcli.
How do I update the CLI?

npm install -g @microsoft/azureportalcli@5.303.1234 Note update the version to the target version of cli/sdk you desire. For commentary on updating the cli, your extension and revoked SDKs see Video: Updating the CLI, extension SDK version and revoked SDKs.
Can I use the CLI with VS Code?

Yes, you can use it directly within VS Code either via the deep integration VS Code provides with package.json scripts e.g "start": "ap start". See this video for details VS Code integration. For deeper integration see VS Code tasks if you create a deeper integration here we would be interested in hearing from you. Note you may also used the integrated terminal.
Where can I request features?

Request here https://aka.ms/portalfx/clifeature or work with us to contribute the feature back to the portal extension dev community.
Where can I log bugs?

Log here https://aka.ms/portalfx/clibug or contribute a fix back.
Where can I ask general questions?

Ask questions here
What are the IDE specific installs required for Visual Studio Code? The first time Setup and Installation covers everything required. Visual Studio Code can be installed from here

What are the IDE specific installs required for Visual Studio? Insall Visual Studio 2019 Professional or Enterpise from https://visualstudio.microsoft.com/downloads/.

* Select the following workloads from the *workloads* tab:
  * Node.js development
  * ASP.NET and web development

![alt-text](../media/top-extensions-install-software/vs2019_workloads.png "Selecting VS 2019 workloads")

* Select .NET Framework 4.7.2 SDK and targeting pack from the *Individual components* tab:

![alt-text](../media/top-extensions-install-software/vs2019_components.png "Selecting VS 2019 components")

How can CloudTest access internal Azure DevOps feed?

Important Note: if you would like better integration with devops internal package feeds, i.e so that you dont need to perform the steps below, then vote for this feature vote here
1. Create a service account with 2FA exemption.
2. This is the link to grant the service account access to the AzurePortal Feed https://msazure.visualstudio.com/One/_packaging?_a=connect&feed=AzurePortal .
3. Once granted access, after the service account has permission to the AzurePortal Feed, you can generate PAT token following this doc .
4. Store the PAT token in a keyvault that cloudtest can access.
5. If not already base 64 encoded, don't forget to encode the PAT token in base 64 before putting it in .npmrc. more details to generate .npmrc with a long lasting PAT here .

Manual one time Auth Setup and Installation

The following steps detail the one time configuration that must be applied to authenticate against the internal AzurePortal registry for both NuGet and npm. If you prefer follow along see the step by step: Video:One time configuration steps

Install the LTS of nodejs download
Install the .NET 4.7.2 Developer Pack - located here
NuGet Credential provider
1. Connect to the AzurePortal Feed https://msazure.visualstudio.com/One/_packaging?_a=connect&feed=AzurePortal
2. Select NuGet.exe under the NuGet header
3. Click the 'Get the tools' button in the top right corner
4. Follow steps 1 and 2 to download the latest NuGet version and the credential provider.
NPM Auth Personal Access Token (PAT)

Just as NuGet needed the credentidal provider npm requires a PAT for auth. Which can be configured as follows.
1. Connect to the AzurePortal Feed https://msazure.visualstudio.com/One/_packaging?_a=connect&feed=AzurePortal
2. Select npm under the npm header
3. Click the 'Get the tools' button in the top right corner
4. Optional. Follow steps 1 to install node.js and npm if not already done so.
5. Follow step 2 to install vsts-npm-auth node.
6. Add a .npmrc file to your project or empty directory with the following content
```
registry=https://msazure.pkgs.visualstudio.com/_packaging/AzurePortal/npm/registry/
always-auth=true
```
7. From the command prompt in the same directory:
  - set the default npm registry
```
npm config set registry https://msazure.pkgs.visualstudio.com/_packaging/AzurePortal/npm/registry/
```
  - generate a readonly PAT using vsts-npm-auth
```
vsts-npm-auth -R -config .npmrc
```
  Generally the PAT will be written to %USERPROFILE%.npmrc we strongly recommend not checking your PAT into source control; anyone with access to your PAT can interact with Azure DevOps Services as you.
Path Ensure the following are on your path i.e resolve when typed in and run from the command prompt.
1. NuGet and the above installed credential provider is on your path.
2. Ensure npm is on your path.
3. Ensure msbuild is on your path.
If not present you can add the items to your path as follows:
1. WindowsKey + R
2. rundll32.exe sysdm.cpl,EditEnvironmentVariables
3. In the dialog click Edit on the Path variable and add (note paths may vary depending on your environment and msbuiuld version)
  - for npm C:\Users\youralias\AppData\Roaming\npm
  - for nuget and cred provider C:\Users\youralias\.nuget
  - for msbuild C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\MSBuild\15.0\Bin

If you have run into problems checkout the Video:One time configuration steps

Installing the Azure portal extension developer CLI

With the one time configuration steps complete you can now install the CLI as you would with any other node module.

Run the following command in the directory that contains your .npmrc.
```
npm install -g @microsoft/azureportalcli
```

Video: Installing the node module

To validate that your dev machine is ready for Azure Portal Extension development start with the template extension in the Getting Started Guide

Files

top-ap-cli.md

Latest commit

History

top-ap-cli.md

File metadata and controls

CLI Overview

Setup and Installation

One time configuration steps

Basic workflows

restore, build, serve, sideload and watch

run tests

lint your extension

updating your Portal Framework version

Command Reference

ap build

Arguments

Example Usage

Supplying defaults using apCliConfig.json

ap diag

Arguments

Example Usage

Supplying defaults using apCliConfig.json

ap lint

Arguments

Example Usage

Linting directly within VS Code

Customizing Lint Rules

ap new

Arguments

Example Usage

ap samples

Arguments

Example Usage

ap release

Arguments

Example Usage

Supplying defaults using apCliConfig.json

ap restore

Arguments

Example Usage

Supplying defaults using apCliConfig.json

ap run

Arguments

Example Usage

ap serve

Arguments

Example usage

Overriding settings for local development

ap start

Arguments

Example Usage

ap update

Arguments

Example Usage

Supplying defaults using apCliConfig.json

ap watch

Arguments

Example Usage

Supplying defaults using apCliConfig.json

Extending the cli with your teams own commands

Overriding the behavior of existing commands

Telemetry

Contributions and feedback

FAQ

Manual one time Auth Setup and Installation

Installing the Azure portal extension developer CLI