VSTS-TASK-LIB TYPESCRIPT API

Dependencies

A cross platform agent OR a TFS 2015 Update 2 Windows agent (or higher) is required to run a Node task end-to-end. However, an agent is not required for interactively testing the task.

Importing

For now, the built vsts-task-lib (in _build) should be packaged with your task in a node_modules folder

The build generates a vsts-task-lib.d.ts file for use when compiling tasks In the example below, it is in a folder named definitions above the tasks lib

/// <reference path="../definitions/vsts-task-lib.d.ts" />
import tl = require('vsts-task-lib/task')

Release notes

## Index

## Input Functions

Functions for retrieving inputs for the task

### task.getInput (^) Gets the value of an input. The value is also trimmed. If required is true and the value is not set, it will throw. ```javascript getInput(name:string, required?:boolean):string ```

Param	Type	Description
name	string	name of the input to get
required	boolean	whether input is required. optional, defaults to false

### task.getBoolInput (^) Gets the value of an input and converts to a bool. Convenience. If required is true and the value is not set, it will throw. ```javascript getBoolInput(name:string, required?:boolean):boolean ```

Param	Type	Description
name	string	name of the bool input to get
required	boolean	whether input is required. optional, defaults to false

### task.getPathInput (^) Gets the value of a path input It will be quoted for you if it isn't already and contains spaces If required is true and the value is not set, it will throw. If check is true and the path does not exist, it will throw. ```javascript getPathInput(name:string, required?:boolean, check?:boolean):string ```

Param	Type	Description
name	string	name of the input to get
required	boolean	whether input is required. optional, defaults to false
check	boolean	whether path is checked. optional, defaults to false

### task.filePathSupplied (^) Checks whether a path inputs value was supplied by the user File paths are relative with a picker, so an empty path is the root of the repo. Useful if you need to condition work (like append an arg) if a value was supplied ```javascript filePathSupplied(name:string):boolean ```

Param	Type	Description
name	string	name of the path input to check

### task.getDelimitedInput (^) Gets the value of an input and splits the value using a delimiter (space, comma, etc). Empty values are removed. This function is useful for splitting an input containing a simple list of items - such as build targets. IMPORTANT: Do not use this function for splitting additional args! Instead use argString(), which follows normal argument splitting rules and handles values encapsulated by quotes. If required is true and the value is not set, it will throw. ```javascript getDelimitedInput(name:string, delim:string, required?:boolean):string ```

Param	Type	Description
name	string	name of the input to get
delim	string	delimiter to split on
required	boolean	whether input is required. optional, defaults to false

### task.getVariable (^) Gets a variable value that is defined on the build/release definition or set at runtime. ```javascript getVariable(name:string):string ```

Param	Type	Description
name	string	name of the variable to get

### task.getVariables (^) Gets a snapshot of the current state of all job variables available to the task. Requires a 2.104.1 agent or higher for full functionality. ```javascript getVariables():VariableInfo[] ```

### task.setVariable (^) Sets a variable which will be available to subsequent tasks as well. ```javascript setVariable(name:string, val:string, secret:boolean):void ```

Param	Type	Description
name	string	name of the variable to set
val	string	value to set
secret	boolean	whether variable is secret. optional, defaults to false

## Execution

Tasks typically execute a series of tools (cli) and set the result of the task based on the outcome of those

/// <reference path="../definitions/vsts-task-lib.d.ts" />
import tl = require('vsts-task-lib/task');
import tr = require('vsts-task-lib/toolrunner');

try {
    var toolPath = tl.which('atool');
    var atool:tr.ToolRunner = tl.tool(toolPath).arg('--afile').line('arguments');
    var code: number = await tr.exec();
    console.log('rc=' + code);
}
catch (err) {
    tl.setResult(tl.TaskResult.Failed, err.message);
}

### task.tool (^) Convenience factory to create a ToolRunner. ```javascript tool(tool:string):ToolRunner ```

Param	Type	Description
tool	string	path to tool to exec

### toolrunner.ToolRunner.arg (^) Add argument Append an argument or an array of arguments returns ToolRunner for chaining ```javascript arg(val:string | string[]):ToolRunner ```

Param	Type	Description
val	string or string[]	string cmdline or array of strings

### toolrunner.ToolRunner.line (^) Append argument command line string e.g. '"arg one" two -z' would append args[]=['arg one', 'two', '-z'] returns ToolRunner for chaining ```javascript line(val:string):ToolRunner ```

Param	Type	Description
val	string	string cmdline

### toolrunner.ToolRunner.argIf (^) Add argument(s) if a condition is met Wraps arg(). See arg for details returns ToolRunner for chaining ```javascript argIf(condition:any, val:any):this ```

Param	Type	Description
condition	any	boolean condition
val	any	string cmdline or array of strings

### toolrunner.ToolRunner.pipeExecOutputToTool (^) Pipe output of exec() to another tool ```javascript pipeExecOutputToTool(tool:ToolRunner):ToolRunner ```

Param	Type	Description
tool	ToolRunner	-

### toolrunner.IExecOptions (^) Interface for exec options

Property	Description
cwd	optional working directory. defaults to current
env	optional envvar dictionary. defaults to current processes env
silent	optional. defaults to false
failOnStdErr	optional. whether to fail if output to stderr. defaults to false
ignoreReturnCode	optional. defaults to failing on non zero. ignore will not fail leaving it up to the caller

### toolrunner.ToolRunner.exec (^) Exec a tool. Output will be streamed to the live console. Returns promise with return code ```javascript exec(options?:IExecOptions):Promise ```

Param	Type	Description
options	IExecOptions	optional exec options. See IExecOptions

### toolrunner.ToolRunner.execSync (^) Exec a tool synchronously. Output will be *not* be streamed to the live console. It will be returned after execution is complete. Appropriate for short running tools Returns IExecResult with output and return code ```javascript execSync(options?:IExecOptions):IExecResult ```

Param	Type	Description
options	IExecOptions	optionalexec options. See IExecOptions

### toolrunner.IExecResult (^) Interface for exec results returned from synchronous exec functions

Property	Description
stdout	standard output
stderr	error output
code	return code
error	Error on failure

### task.exec (^) Exec a tool. Convenience wrapper over ToolRunner to exec with args in one call. Output will be streamed to the live console. Returns promise with return code ```javascript exec(tool:string, args:any, options?:IExecOptions):Promise ```

Param	Type	Description
tool	string	path to tool to exec
args	any	an arg string or array of args
options	IExecOptions	optional exec options. See IExecOptions

### task.execSync (^) Exec a tool synchronously. Convenience wrapper over ToolRunner to execSync with args in one call. Output will be *not* be streamed to the live console. It will be returned after execution is complete. Appropriate for short running tools Returns IExecResult with output and return code ```javascript execSync(tool:string, args:string | string[], options?:IExecOptions):IExecResult ```

Param	Type	Description
tool	string	path to tool to exec
args	string or string[]	an arg string or array of args
options	IExecOptions	optionalexec options. See IExecOptions

### task.setResult (^) Sets the result of the task. Execution will continue. If not set, task will be Succeeded. If multiple calls are made to setResult the most pessimistic call wins (Failed) regardless of the order of calls. ```javascript setResult(result:TaskResult, message:string):void ```

Param	Type	Description
result	TaskResult	TaskResult enum of Success or Failed.
message	string	A message which will be logged as an error issue if the result is Failed.

## Service Endpoints

Retrieve service endpoints and authorization details

### task.getEndpointUrl (^) Gets the url for a service endpoint If the url was not set and is not optional, it will throw. ```javascript getEndpointUrl(id:string, optional:boolean):string ```

Param	Type	Description
id	string	name of the service endpoint
optional	boolean	whether the url is optional

### task.EndpointAuthorization (^) Interface for EndpointAuthorization Contains a schema and a string/string dictionary of auth data

Property	Description
parameters	string string dictionary of auth data
scheme	auth scheme such as OAuth or username/password etc...

### task.getEndpointAuthorization (^) Gets the authorization details for a service endpoint If the authorization was not set and is not optional, it will throw. ```javascript getEndpointAuthorization(id:string, optional:boolean):EndpointAuthorization ```

Param	Type	Description
id	string	name of the service endpoint
optional	boolean	whether the url is optional

## Disk Functions

Functions for disk operations

### task.which (^) Returns path of a tool had the tool actually been invoked. Resolves via paths. If you check and the tool does not exist, it will throw. ```javascript which(tool:string, check?:boolean):string ```

Param	Type	Description
tool	string	name of the tool
check	boolean	whether to check if tool exists

### task.checkPath (^) Checks whether a path exists. If the path does not exist, it will throw. ```javascript checkPath(p:string, name:string):void ```

Param	Type	Description
p	string	path to check
name	string	name only used in error message to identify the path

### task.exist (^) Returns whether a path exists. ```javascript exist(path:string):boolean ```

Param	Type	Description
path	string	path to check

### task.cd (^) Change working directory. ```javascript cd(path:string):void ```

Param	Type	Description
path	string	new working directory path

### task.cp (^) Returns path of a tool had the tool actually been invoked. Resolves via paths. If you check and the tool does not exist, it will throw. Returns whether the copy was successful ```javascript cp(source:string, dest:string, options?:string, continueOnError?:boolean):void ```

Param	Type	Description
source	string	source path
dest	string	destination path
options	string	string -r, -f or -rf for recursive and force
continueOnError	boolean	optional. whether to continue on error

### task.mv (^) Moves a path. Returns whether the copy was successful ```javascript mv(source:string, dest:string, options?:string, continueOnError?:boolean):void ```

Param	Type	Description
source	string	source path
dest	string	destination path
options	string	string -f or -n for force and no clobber
continueOnError	boolean	optional. whether to continue on error

### task.mkdirP (^) Make a directory. Creates the full path with folders in between Will throw if it fails ```javascript mkdirP(p:string):void ```

Param	Type	Description
p	string	path to create

### task.FindOptions (^) Interface for FindOptions Contains properties to control whether to follow symlinks

Property	Description
followSpecifiedSymbolicLink	Equivalent to the -H command line option. Indicates whether to traverse descendants if the specified path is a symbolic link directory. Does not cause nested symbolic link directories to be traversed.
followSymbolicLinks	Equivalent to the -L command line option. Indicates whether to traverse descendants of symbolic link directories.

### task.find (^) Find all files under a give path Returns an array of paths ```javascript find(findPath:string, options?:FindOptions):string ```

Param	Type	Description
findPath	string	path to find files under
options	FindOptions	options to control whether to follow symlinks

### task.rmRF (^) Remove a path recursively with force Returns whether it succeeds ```javascript rmRF(path:string, continueOnError?:boolean):void ```

Param	Type	Description
path	string	path to remove
continueOnError	boolean	optional. whether to continue on error

### task.pushd (^) Change working directory and push it on the stack ```javascript pushd(path:string):void ```

Param	Type	Description
path	string	new working directory path

### task.popd (^) Change working directory back to previously pushed directory ```javascript popd():void ```

### task.resolve (^) Resolves a sequence of paths or path segments into an absolute path. Calls node.js path.resolve() Allows L0 testing with consistent path formats on Mac/Linux and Windows in the mock implementation ```javascript resolve(pathSegments:any):string ```

Param	Type	Description
pathSegments	any	-

### task.stats (^) Get's stat on a path. Useful for checking whether a file or directory. Also getting created, modified and accessed time. see [fs.stat](https://nodejs.org/api/fs.html#fs_class_fs_stats) ```javascript stats(path:string):FsStats ```

Param	Type	Description
path	string	path to check

### task.writeFile (^) Synchronously writes data to a file, replacing the file if it already exists. See [fs.writeFileSync](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options) ```javascript writeFile(file:string, data:undefined, options?:undefined):void ```

Param	Type	Description
file	string	-
data	undefined	-
options	undefined	-

## Localization

Localization is optional but is supported using these functions at runtime

/// <reference path="../definitions/vsts-task-lib.d.ts" />

tl.setResourcePath(path.join( __dirname, 'task.json'));

...

var errMsg = tl.loc('FailedWithReturnCode', code));

// in the task.json
{
    "messages": {
        "FailedWithReturnCode": "Tool exited with return code: %d",
        "ToolFailed": "Tool failed with error: %s"
    }
}

### task.setResourcePath (^) Sets the location of the resources json. This is typically the task.json file. Call once at the beginning of the script before any calls to loc. ```javascript setResourcePath(path:string):void ```

Param	Type	Description
path	string	Full path to the json.

### task.loc (^) Gets the localized string from the json resource file. Optionally formats with additional params. ```javascript loc(key:string, param:any):string ```

Param	Type	Description
key	string	key of the resources string in the resource file
param	any	additional params for formatting the string

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

VSTS-TASK-LIB TYPESCRIPT API

Dependencies

Importing

Release notes

Input Functions (v)

Execution (v)

Service Endpoints (v)

Disk Functions (v)

Localization (v)

FilesExpand file tree

vsts-task-lib.md

Latest commit

History

vsts-task-lib.md

File metadata and controls

VSTS-TASK-LIB TYPESCRIPT API

Dependencies

Importing

Release notes

Input Functions (v)

Execution (v)

Service Endpoints (v)

Disk Functions (v)

Localization (v)