# Writing Tasks

version 9.1.0-20250801000225+0000

Gradle tasks are created by extending `DefaultTask`.

However, the generic `DefaultTask` provides no action for Gradle. If users want to extend the capabilities of Gradle and their build script, they must either use a built-in task or create a custom task:

1. Built-in task - Gradle provides built-in utility tasks such as `Copy`, `Jar`, `Zip`, `Delete`, etc…​

2. Custom task - Gradle allows users to subclass `DefaultTask` to create their own task types.

## Create a task

The simplest and quickest way to create a custom task is in a build script:

To create a task, inherit from the `DefaultTask` class and implement a `@TaskAction` handler:

build.gradle.kts

    abstract class CreateFileTask : DefaultTask() {
        @TaskAction
        fun action() {
            val file = File("myfile.txt")
            file.createNewFile()
            file.writeText("HELLO FROM MY TASK")
        }
    }

build.gradle

    class CreateFileTask extends DefaultTask {
        @TaskAction
        void action() {
            def file = new File("myfile.txt")
            file.createNewFile()
            file.text = "HELLO FROM MY TASK"
        }
    }

The `CreateFileTask` implements a simple set of actions. First, a file called "myfile.txt" is created in the main project. Then, some text is written to the file.

## Register a task

A task is registered in the build script using the `TaskContainer.register()` method, which allows it to be then used in the build logic.

build.gradle.kts

    abstract class CreateFileTask : DefaultTask() {
        @TaskAction
        fun action() {
            val file = File("myfile.txt")
            file.createNewFile()
            file.writeText("HELLO FROM MY TASK")
        }
    }

    tasks.register<CreateFileTask>("createFileTask")

build.gradle

    class CreateFileTask extends DefaultTask {
        @TaskAction
        void action() {
            def file = new File("myfile.txt")
            file.createNewFile()
            file.text = "HELLO FROM MY TASK"
        }
    }

    tasks.register("createFileTask", CreateFileTask)

## Task group and description

Setting the group and description properties on your tasks can help users understand how to use your task:

build.gradle.kts

    abstract class CreateFileTask : DefaultTask() {
        @TaskAction
        fun action() {
            val file = File("myfile.txt")
            file.createNewFile()
            file.writeText("HELLO FROM MY TASK")
        }
    }

    tasks.register<CreateFileTask>("createFileTask") {
        group = "custom"
        description = "Create myfile.txt in the current directory"
    }

build.gradle

    class CreateFileTask extends DefaultTask {
        @TaskAction
        void action() {
            def file = new File("myfile.txt")
            file.createNewFile()
            file.text = "HELLO FROM MY TASK"
        }
    }

    tasks.register("createFileTask", CreateFileTask) {
        group = "custom"
        description = "Create myfile.txt in the current directory"
    }

Once a task is added to a group, it is visible when listing tasks.

## Task input and outputs

For the task to do useful work, it typically needs some inputs. A task typically produces outputs.

build.gradle.kts

    abstract class CreateAFileTask : DefaultTask() {
        @get:Input
        abstract val fileText: Property<String>

        @Input
        val fileName = "myfile.txt"

        @OutputFile
        val myFile: File = File(fileName)

        @TaskAction
        fun action() {
            myFile.createNewFile()
            myFile.writeText(fileText.get())
        }
    }

build.gradle

    abstract class CreateAFileTask extends DefaultTask {
        @Input
        abstract Property<String> getFileText()

        @Input
        final String fileName = "myfile.txt"

        @OutputFile
        final File myFile = new File(fileName)

        @TaskAction
        void action() {
            myFile.createNewFile()
            myFile.text = fileText.get()
        }
    }

## Configure a task

A task is optionally configured in a build script using the `TaskCollection.named()` method.

The `CreateAFileTask` class is updated so that the text in the file is configurable:

build.gradle.kts

    abstract class CreateAFileTask : DefaultTask() {
        @get:Input
        abstract val fileText: Property<String>

        @Input
        val fileName = "myfile.txt"

        @OutputFile
        val myFile: File = File(fileName)

        @TaskAction
        fun action() {
            myFile.createNewFile()
            myFile.writeText(fileText.get())
        }
    }

    tasks.register<CreateAFileTask>("createAFileTask") {
        group = "custom"
        description = "Create myfile.txt in the current directory"
        fileText.convention("HELLO FROM THE CREATE FILE TASK METHOD") // Set convention
    }

    tasks.named<CreateAFileTask>("createAFileTask") {
        fileText.set("HELLO FROM THE NAMED METHOD") // Override with custom message
    }

build.gradle

    abstract class CreateAFileTask extends DefaultTask {
        @Input
        abstract Property<String> getFileText()

        @Input
        final String fileName = "myfile.txt"

        @OutputFile
        final File myFile = new File(fileName)

        @TaskAction
        void action() {
            myFile.createNewFile()
            myFile.text = fileText.get()
        }
    }

    tasks.register("createAFileTask", CreateAFileTask) {
        group = "custom"
        description = "Create myfile.txt in the current directory"
        fileText.convention("HELLO FROM THE CREATE FILE TASK METHOD") // Set convention
    }

    tasks.named("createAFileTask", CreateAFileTask) {
        fileText.set("HELLO FROM THE NAMED METHOD") // Override with custom message
    }

In the `named()` method, we find the `createAFileTask` task and set the text that will be written to the file.

When the task is executed:

    $ ./gradlew createAFileTask

    > Configure project :app

    > Task :app:createAFileTask

    BUILD SUCCESSFUL in 5s
    2 actionable tasks: 1 executed, 1 up-to-date

A text file called `myfile.txt` is created in the project root folder:

myfile.txt

    HELLO FROM THE NAMED METHOD

Consult the Developing Gradle Tasks chapter to learn more.

Next Step: Learn how to use Plugins >>