Typed API for logging in Azure Pipelines
A typed API for Azure Pipelines logging commands. Designed to be used with TypeScript.
npm install --save azure-pipelines-logging
// docs/examples/basic.ts
import { command, format, log } from "azure-pipelines-logging";
log(command("task", "logissue", { type: "error" })("Error summary"));
log(format("error")(
"Details about error.",
"Second line of details.",
"Third and\nfourth line.",
));
/*
Output:
##vso[task.logissue type=error;]Error summary
##[error]Details about error.
##[error]Second line of details.
##[error]Third and
##[error]fourth line.
*/
The exported functions are typed as strictly as possible and in a way such that editors can provide useful autocompletion.
For example, give "task"
as the first argument to command
to get autocompletion for all actions in the task
area.
The properties that each command supports, if any, are encoded in the types.
// docs/examples/properties.ts
import { command, log } from "azure-pipelines-logging";
const addbuildtag = command("build", "addbuildtag");
const associate = command("artifact", "associate", {
artifactname: "whatever",
type: "container", // Type error if invalid value given.
// Type error if unknown property given or required property missing.
});
log(addbuildtag("Tag_UnitTestPassed"));
log(associate("#/1/build"));
/*
Output:
##vso[build.addbuildtag]Tag_UnitTestPassed
##vso[artifact.associate artifactname=whatever;type=container;]#/1/build
*/
log
vs console.log
The exported log
function is a more strictly typed alias for console.log
that eliminates this class of bugs:
// docs/examples/console.log-bad.ts
import { command } from "azure-pipelines-logging";
console.log(
command("task", "logissue", { type: "error" }) // A function, not a string!
);
/*
Output:
[Function (anonymous)]
*/
This bug is made possible by the combination of command
(and format
) being curried and console.log
taking parameters of type any
.
Correct code:
// docs/examples/console.log-good.ts
import { command } from "azure-pipelines-logging";
console.log(
command("task", "logissue", { type: "error" })("Error summary")
);
/*
Output:
##vso[task.logissue type=error;]Error summary
*/
Using log
instead of console.log
prevents such mistakes by making them static type errors.
Run these commands to build everything and run the tests:
npm ci
npm run make
embedme
is used for code examples in the readme.