# Tasks

[This is preliminary documentation and subject to change.]

## Contents

1 Introduction
2 Loading custom extensions
2.1 Automatic discovery
2.1.1 Operating system
2.1.2 Runtime framework
2.1.3 Project
2.2 Forced scan

## 1 Introduction

A task is a piece of code that can be executed.

A task can have multiple attributes (or arguments, if you prefer). The value of an attribute may contain references to a property. These references will be resolved before the task is executed.

Tasks have a common structure:

>     <name attribute1="value1" attribute2="value2" ... />

where name is the name of the task, attribute# is the attribute name, and value# is the value for this attribute.

For more information see the Task Reference.

## 2 Loading custom extensions

Extensions can be devided in the following categories:

- Tasks
- Filters
- Functions
- Global Types

NAnt currently provides two mechanisms to make third-party extensions available for use in build scripts:

- Automatic discovery
- Forced scan

Both mechanisms use .NET reflection to scan one or more assemblies for the presence of extensions. When found, these extensions are registered in the NAnt type system, and from then on these are available for all build scripts (in the current NAnt instance).

### 2.1 Automatic discovery

To facilitate registration of extensions that are used in multiple (or even all) build scripts, NAnt supports automatic discovery of extensions.

In this context, automatic discovery means scanning a predefined set of directories and files for extensions.

The actual set of directories and files that is scanned is determined by:

- Operating system
- Runtime framework
- Project

#### 2.1.1 Operating system

When starting NAnt, all assemblies matching the following patterns will be scanned for extensions:

Windows

Pattern | Action | Description
--- | --- | ---
*Tasks.dll | include | NAnt Core assemblies
*Tests.dll | include | NAnt test assemblies
extensions/common/neutral/**/*.dll | include | Framework and version-neutral assemblies
NAnt.MSNetTasks.dll | exclude | Microsoft.NET specific assembly
NAnt.MSNet.Tests.dll | exclude | Microsoft.NET specific test assembly

Unix

Pattern | Action | Description
--- | --- | ---
*Tasks.dll | include | NAnt Core assemblies
*Tests.dll | include | NAnt test assemblies
extensions/common/neutral/**/*.dll | include | Framework and version-neutral assemblies
NAnt.MSNetTasks.dll | exclude | Microsoft.NET specific assembly
NAnt.MSNet.Tests.dll | exclude | Microsoft.NET specific test assembly
NAnt.Win32Tasks.dll | exclude | Win32 specific assembly
NAnt.Win32.Tests.dll | exclude | Win32 specific test assembly

NOTE: all patterns are matched relative to the NAnt base directory, which is the directory in which NAnt.exe is located.

#### 2.1.2 Runtime framework

Depending on the runtime framework on which NAnt is running, some additional directories are scanned.

In general, the following include patterns are applied:

extensions/common/<CLR version>/**/*.dll
extensions/<framework family>/neutral/**/*.dll
extensions/<framework family>/<framework version>/**/*.dll

Example:

When running NAnt on Microsoft .NET Framework 1.0, assemblies matching the following pattern would be scanned:

extensions/common/1.0/**/*.dll
extensions/net/neutral/**/*.dll
extensions/net/1.0/**/*.dll

NOTE: the exact set of patterns that are used for a given runtime framework is defined in the NAnt configuration file (NAnt.exe.config).

#### 2.1.3 Project

Whenever a build project is started, NAnt will scan the following directories for assemblies that match the *.dll pattern:

- <Project Base Directory>/extensions/common/neutral/
- <Project Base Directory>/extensions/common/<CLR version>/
- <Project Base Directory>/extensions/<framework family>/neutral/
- <Project Base Directory>/tasks/<framework family>/<framework version>/

Example:

For a project file located in "c:\projects\log4net" with NAnt running on the Microsoft .NET 2.0 runtime, NAnt would end-up scanning the following project-level directories:

- c:\projects\log4net\extensions\common\neutral\
- c:\projects\log4net\extensions\common\2.0\
- c:\projects\log4net\extensions\net\neutral\
- c:\projects\log4net\extensions\net\2.0\

### 2.2 Forced scan

To explicitly instruct NAnt to scan a certain assembly (or set of assemblies) for extensions, build authors can use the `<loadtasks>` tasks.