Task Anatomy
In the previous section, we built our first task and executed it. Let's take a look at how the simple conventions work for task runners.
Default conventions
The
task run command will look for a default task name of task.cfc in the current working directory. The default target (or method) is called run. Therefore, when you run1
task run
Copied!
you will execute the
run() method of ./task.cfc relative to your current working directory.Take you to task
A task is just a CFC file. The task CFCs will extend the
commandbox.system.BaseTask class, but it isn't necessary for your to extend it manually. CommandBox will add in virtual inheritance for you. The task CFCs can live wherever you want in your project (or outside of it!) and can have any name you wish. Since tasks are not scanned and registered by CommandBox, but rather created on-the-fly by convention, you don't have to worry about more than one task in different projects with the same name. That means, each of your projects can have a workbench/build.cfc task runner and they won't collide. When you run the task, the correct CFC will be located based on your current working directory. Therefore, tasks are not "global" like commands, but rather in the context of a given project or folder.myTaskName.cfc
1
component {
2
function run() {
3
// Do awesome task stuff here
4
}
5
}
Copied!
To call the above task, we'd reference the path to where the CFC lives. It isn't necessary to include the
.cfc part of the name, though we'll forgive you if you do!1
task run path/to/myTaskName
Copied!
Hit the target
You can have as many targets in your task as you wish, by simply declaring public methods. A task can have no parameters or as many as you like. Default argument values will be used as well. It's just a method execution, but from the command line!
build.cfc
1
component {
2
​
3
function createZips() {
4
print.line( 'Zips created!' );
5
}
6
​
7
function compileAssets(){
8
print.line( 'Assets Compiled!' );
9
}
10
​
11
function minimizeJS(){
12
print.line( 'JS Minimized!' );
13
}
14
​
15
}
Copied!
To run each of the targets above, you'd type this:
1
task run build createZips
2
task run build compileAssets
3
task run build minimzeJS
Copied!
WireBox DI
All CFCs including tasks are created and wired via WireBox, so dependency injection and AOP are available to them. This can be handy for tasks to wrap services provided by models, or to access utilities and services inside CommandBox.
This task would inject CommandBox's ArtifactService to list out all the packages being stored.
1
component {
2
​
3
property name='artifactService' inject='artifactService';
4
​
5
function run(){
6
var results = artifactService.listArtifacts();
7
for( var package in results ) {
8
print.boldCyanLine( package );
9
}
10
}
11
​
12
}
Copied!
Tasks also have a
variables.wirebox variable as well as their own getInstance() method which proxies to WireBox to get objects.1
var results = getInstance( 'artifactService' ).listArtifacts();
Copied!
Modifying Application Settings
Task Runners do not execute a
application.cfc or application.cfm, but you can use the cfapplication tag (or script variant: application) to modify the properties and behaviors of the Task Runner application. Any setting that can be modified using cfapplication can be modified in Task Runners as follows:1
// to create a datasource, first get the application settings
2
appSettings = getApplicationSettings();
3
​
4
// initialize with the current value of application datasources
5
dsources = appSettings.datasources ?: {};
6
​
7
// add a new datasource to it
8
dsources[ 'myNewDS' ] = { ... };
9
​
10
// call cfapplication (cfscript variant) to update the datasources and set AWS S3 credentials
11
application action="update" datasources=dsources s3={} /* and any other settings */ ;
Copied!
You can also define mappings as follows:
1
fileSystemUtil.createMapping( name, physicalpath );
Copied!
NOTE: The settings that are changed using
cfapplication will last for the duration of the CLI shell and will affect any and all code run from the CLI including the CommandBox core code.Sending Email
To send email, use the
cfscript variant of cfmail making sure you set async=false (see below). Not setting this flag to false may result in undelivered email because mail may still exist in Lucee spooler (Lucee tasks) when your task runner exits.Last modified 1mo ago
Copy link
Edit on GitHub