VSTS-TASK-LIB TYPESCRIPT API

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')

## 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, the task will fail with an error. Execution halts. ```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, the task will fail with an error. Execution halts. ```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, the task will fail with an error. Execution halts. If check is true and the path does not exist, the task will fail with an error. Execution halts. ```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 values by a delimiter (space, comma, etc...) Useful for splitting an input with simple list of items like targets IMPORTANT: Do not use for splitting additional args! Instead use arg() - it will split and handle If required is true and the value is not set, the task will fail with an error. Execution halts. ```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 variables value which is defined on the build definition or set at runtime. ```javascript getVariable(name:string):string ```

Param	Type	Description
name	string	name of the variable to get

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

Param	Type	Description
name	string	name of the variable to set
val	string	value to set

## 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');

var toolPath = tl.which('atool');
var tool = tl.createToolRunner(toolPath);

tool.arg('--afile');
tool.arg(tl.getPathInput('afile', true));

// NOTE: arg function handles complex additional args with double quotes like
//       "arg one" arg2 -x
//
tool.arg(tl.getInput('arguments', false));

tool.exec()
.then((code) => {
    tl.setResult(tl.TaskResult.Succeeded, "tool returned " + code);
})
.fail((err) => {
    tl.debug('toolRunner fail');
    tl.setResult(tl.TaskResult.Failed, err.message);
})

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

Param	Type	Description
tool	string	path to tool to exec

### toolrunner.ToolRunner.arg (^) Adds individual arguments Accepts a string argument or a string array as well ```javascript arg(val:string | string[]):void ```

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

### toolrunner.ToolRunner.argString (^) Add command line args Accepts a full string command line Will handle double quoted args. E.g. '"arg one" two -z' ```javascript argString(val:string):void ```

Param	Type	Description
val	string	string cmdline

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

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

### 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:any, options?:IExecOptions):IExecResult ```

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

### task.setResult (^) Sets the result of the task. If the result is Failed (1), then execution will halt. ```javascript setResult(result:TaskResult, message:string):void ```

Param	Type	Description
result	TaskResult	TaskResult enum of Success or Failed. If the result is Failed (1), then execution will halt.
message	string	-

## 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, the task will fail with an error message. Execution will halt. ```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, the task will fail with an error message. Execution will halt. ```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, the task will fail with an error message and halt execution. ```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, the task will fail with an error message. Execution will halt. ```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, the task will fail with an error message and halt execution. Returns whether the copy was successful ```javascript cp(options:any, source:string, dest:string, continueOnError?:boolean):boolean ```

Param	Type	Description
options	any	string -r, -f or -rf for recursive and force
source	string	source path
dest	string	destination path
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, force:boolean, continueOnError?:boolean):boolean ```

Param	Type	Description
source	string	source path
dest	string	destination path
force	boolean	whether to force and overwrite
continueOnError	boolean	optional. whether to continue on error

### task.mkdirP (^) Make a directory. Creates the full path with folders in between Returns whether it was successful or not ```javascript mkdirP(p:any):boolean ```

Param	Type	Description
p	any	path to create

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

Param	Type	Description
findPath	string	path to find files under

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

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.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

## 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.md

vsts-task-lib.md

VSTS-TASK-LIB TYPESCRIPT API

Importing

Input Functions (v)

Execution (v)

Service Endpoints (v)

Disk Functions (v)

Localization (v)

Files

vsts-task-lib.md

Latest commit

History

vsts-task-lib.md

File metadata and controls

VSTS-TASK-LIB TYPESCRIPT API

Importing

Input Functions (v)

Execution (v)

Service Endpoints (v)

Disk Functions (v)

Localization (v)