CommandBox : CLI, Package Manager, REPL & More
5.4.0
5.4.0
  • Introduction
  • About This Book
  • Authors
  • Overview
  • Release History
    • 5.x Versions
      • What's New in 5.4.2
      • What's New in 5.4.1
      • What's New in 5.4.0
      • What's New in 5.3.1
      • What's New in 5.3.0
      • What's New in 5.2.1
      • What's New in 5.2.0
      • What's New in 5.1.1
      • What's New in 5.1.0
      • What's New in 5.0.0
    • 4.x Versions
      • What's new in 4.8.0
      • What's New in 4.7.0
      • What's New in 4.6.0
      • What's New in 4.5.0
      • What's New in 4.4.0
      • What's New in 4.3.0
      • What's New in 4.2.0
      • What's New in 4.1.0
      • What's New in 4.0.0
    • 3.x Versions
      • What's New in 3.9.0
      • What's New in 3.8.0
      • What's New in 3.7.0
      • What's New in 3.6.0
      • What's New in 3.5.0
      • What's New in 3.4.0
      • What's New in 3.3.0
      • What's New in 3.2.0
      • What's New in 3.1.1
      • What's New in 3.0.1
      • What's New in 3.0.0
    • 2.x Versions
      • What's New in 2.2.0
      • What's New in 2.1.1
      • What's New in 2.1.0
      • What's New in 2.0.0
    • 1.x Versions
      • What's in 1.0.0
  • Getting Started Guide
  • Setup
    • Requirements
    • Download
    • Installation
    • Light and Thin Binaries
    • Non-Oracle JREs
    • Upgrading
    • Common Errors
  • Usage
    • Execution
      • Recipes
      • CFML Files
        • Using a DB in CFML scripts
      • OS Binaries
      • CFML Functions
      • Exit Codes
    • Commands
    • Parameters
      • Escaping Special Characters
      • File Paths
      • Globbing Patterns
      • Piping into Commands
      • Expressions
    • Command Help
    • Environment Variables
    • System Settings
    • System Setting Expansion Namespaces
    • Ad-hoc Command Aliases
    • Default Command Parameters
    • REPL
    • Tab Completion
    • Interactive Shell Features
    • forEach Command
    • watch Command
    • jq Command
    • printTable Command
    • sql Command
    • Auto Update Checks
    • Bullet Train Prompt
    • 256 Color Support
    • A Little Fun
  • IDE Integrations
    • Sublime Text
    • Visual Studio Code
  • Config Settings
    • Module Settings
    • Proxy Settings
    • Endpoint Settings
    • Server Settings
    • JSON Settings
    • Misc Settings
    • Task Runner Settings
    • Env Var Overrides
  • Embedded Server
    • Multi-Engine Support
    • Server Versions
    • Start HTML Server
    • Offline Server Starts
    • Debugging Server Starts
    • Server Processes
    • Manage Servers
    • FusionReactor
    • Server Logs
    • Configuring Your Server
      • Server Profiles
      • Server Rules
        • Baked in Rules
        • Allowed Static Files
        • Rule Language
        • Custom Predicates/Handlers
        • Rule Examples
        • Debugging Server Rules
      • JVM Args
      • Server Port and Host
      • SSL Certs
      • HTTPS Redirect/HSTS
      • URL Rewrites
      • Aliases
      • Custom Error Pages
      • Welcome Files
      • Basic Authentication
      • Custom Java Version
      • Adding Custom Libs
      • GZip Compression
      • REST Servlet
      • Performance Tuning
      • Undertow Options
      • Custom Tray Menus
      • Ad-hoc Env Vars
      • server.json Env Var overrides
      • Server Home
      • web.xml Overrides
      • Experimental Features
    • External Web Server
    • Starting as a Service
    • Single Server Mode
    • Server.json
      • Working with server.json
      • Packaging Your Server
      • Using Multiple server.json Files
  • Package Management
    • Installing Packages
      • Installation Path
      • Installation Options
      • Advanced Installation
    • Private Packages
    • System Modules
    • Code Endpoints
      • ForgeBox
      • HTTP(S)
      • File
      • Folder
      • Git
      • Java
      • S3
      • CFLib
      • Jar (via HTTP)
      • Lex (via HTTP or File)
      • Gist
    • Package Scripts
    • Dependencies
    • Semantic Versioning
    • Updating Packages
    • Creating Packages
      • Editing Package Properties
      • Publishing Lucee Extensions to ForgeBox
    • Artifacts
    • Box.json
      • Basic Package Data
      • Extended Package Data
      • Package URLs
      • Installation
      • Embedded Server
      • Dependencies
      • TestBox
    • Managing Version
  • Task Runners
    • Task Anatomy
    • BaseTask Super Class
    • Task Target Dependencies
    • Passing Parameters
    • Using Parameters
    • Task Output
      • Printing tables
    • Lifecycle Events
    • Threading/Async
    • Task Interactivity
    • Shell Integration
    • Downloading Files
    • Running Other Commands
    • Error Handling
    • Hitting Your Database
    • Sending E-mail
    • Interactive Jobs
    • Watchers
    • Property Files
    • Running other Tasks
    • Loading Ad hoc Jars
    • Loading Ad-hoc Modules
    • Cancel Long Tasks
    • Progress Bar
    • Caching Task Runners
  • Helpful Commands
    • Token Replacements
    • Checksums
    • Code Quality Tools
    • ask and confirm
  • Deploying CommandBox
    • Github Actions
    • Docker
    • Heroku
    • Amazon Lightsail
  • TestBox Integration
    • Test Runner
    • Test Watcher
  • Developing For CommandBox
    • Modules
      • Installation and Locations
      • Configuration
        • Public Properties
        • Configure() Method
        • Lifecycle Methods
      • Conventions
      • User Settings
      • Linking Modules
    • Commands
      • Aliases
      • Using Parameters
        • Using File Globs
        • Dynamic Parameters
      • Command Output
      • Tab Completion & Help
      • Interactivity
      • Watchers
      • Shell integration
      • Running Other Commands
      • Error handling
      • Watchers
      • Loading Ad hoc Jars
    • Interceptors
      • Core Interception Points
        • CLI Lifecycle
        • Command Execution Lifecycle
        • Module Lifecycle
        • Server Lifecycle
        • Error Handling
        • Package Lifecycle
      • Custom Interception Points
    • Injection DSL
    • Example Project
    • FusionReactor for the CLI
  • ForgeBox Enterprise
    • Introduction
    • Storage
    • Commands
      • List
      • Register
      • Login
      • Set Default
      • Remove
    • Usage
Powered by GitBook
On this page
  • Default conventions
  • Take you to task
  • Hit the target
  • WireBox DI
  • Modifying Application Settings
  • Sending Email

Was this helpful?

Edit on Git
Export as PDF
  1. Task Runners

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 run

task run

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

component {
  function run() {
    // Do awesome task stuff here
  }
}

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!

task run path/to/myTaskName

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

component {

  function createZips() {
    print.line( 'Zips created!' );
  }

  function compileAssets(){
    print.line( 'Assets Compiled!' );
  }

  function minimizeJS(){
    print.line( 'JS Minimized!' );
  }

}

To run each of the targets above, you'd type this:

task run build createZips
task run build compileAssets
task run build minimzeJS

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.

component {

    property name='artifactService' inject='artifactService';

    function run(){
        var results = artifactService.listArtifacts();
        for( var package in results ) {
            print.boldCyanLine( package );
        }
    }

}

Tasks also have a variables.wirebox variable as well as their own getInstance() method which proxies to WireBox to get objects.

var results = getInstance( 'artifactService' ).listArtifacts();

Modifying Application Settings

// to create a datasource, first get the application settings
appSettings = getApplicationSettings();

// initialize with the current value of application datasources
dsources = appSettings.datasources ?: {};

// add a new datasource to it
dsources[ 'myNewDS' ] = { ... };

// call cfapplication (cfscript variant) to update the datasources and set AWS S3 credentials
application action="update" datasources=dsources s3={} /* and any other settings */ ;

You can also define mappings as follows:

fileSystemUtil.createMapping( name, physicalpath );

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.

PreviousTask RunnersNextBaseTask Super Class

Last updated 4 years ago

Was this helpful?

Task Runners do not execute a application.cfc or application.cfm, but you can use the tag (or script variant: application) to modify the properties and behaviors of the Task Runner application. Any setting that can be modified using can be modified in Task Runners as follows:

cfapplication
cfapplication